> ## Documentation Index > Fetch the complete documentation index at: https://docs.calibrate.artpark.ai/llms.txt > Use this file to discover all available pages before exploring further. # List traces > List ingested traces, newest first ## OpenAPI ````yaml /api-reference/openapi.json get /traces openapi: 3.1.0 info: title: Calibrate Public API version: 0.1.0 description: Programmatic API for CI/automation. Pass your key in the `X-API-Key` header. servers: - url: https://api.calibrate.artpark.ai description: Production security: [] paths: /traces: get: tags: - traces summary: List traces description: List ingested traces, newest first operationId: list_traces_endpoint_traces_get parameters: - name: agent_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Return only traces from this agent title: Agent Id description: Return only traces from this agent - name: conversation_id in: query required: false schema: anyOf: - type: string maxLength: 255 minLength: 1 - type: 'null' description: Return only the turns of this conversation. Requires `agent_id` title: Conversation Id description: Return only the turns of this conversation. Requires `agent_id` - name: q in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Return only traces containing this text in their message ID, conversation ID, conversation history, output, or metadata title: Q description: >- Return only traces containing this text in their message ID, conversation ID, conversation history, output, or metadata - name: output_type in: query required: false schema: anyOf: - enum: - response - tool_call type: string - type: 'null' description: >- Return only traces whose output is of this kind. `response` covers every trace carrying a reply, including one that also issued tool calls. `tool_call` covers traces that only issued tool calls title: Output Type description: >- Return only traces whose output is of this kind. `response` covers every trace carrying a reply, including one that also issued tool calls. `tool_call` covers traces that only issued tool calls - name: labels in: query required: false schema: anyOf: - type: array items: type: string maxLength: 128 minLength: 1 - type: 'null' description: >- Return only traces carrying at least one of these labels. Repeat the parameter for each label title: Labels description: >- Return only traces carrying at least one of these labels. Repeat the parameter for each label - name: score in: query required: false schema: anyOf: - items: type: string type: array - type: 'null' description: >- Return only traces whose latest scoring run matches this condition. Each is written as `:`, where the condition is `passed`, `failed`, or one of `=`, `!=`, `<`, `<=`, `>`, `>=` followed by a number, such as `>=4`. Repeat the parameter to require every condition at once title: Score description: >- Return only traces whose latest scoring run matches this condition. Each is written as `:`, where the condition is `passed`, `failed`, or one of `=`, `!=`, `<`, `<=`, `>`, `>=` followed by a number, such as `>=4`. Repeat the parameter to require every condition at once - name: created_after in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: >- Return only traces created at or after this time (ISO 8601). A time with no timezone is read as UTC. Omit for no earliest date title: Created After description: >- Return only traces created at or after this time (ISO 8601). A time with no timezone is read as UTC. Omit for no earliest date - name: created_before in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: >- Return only traces created before this time (ISO 8601). A time with no timezone is read as UTC. Omit for no latest date title: Created Before description: >- Return only traces created before this time (ISO 8601). A time with no timezone is read as UTC. Omit for no latest date - name: sort_by_evaluator in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Order traces by this evaluator's score on each trace's latest scoring run. Traces this evaluator has not scored come last whichever direction you pick, and an evaluator not linked to the agent counts as having scored none title: Sort By Evaluator description: >- Order traces by this evaluator's score on each trace's latest scoring run. Traces this evaluator has not scored come last whichever direction you pick, and an evaluator not linked to the agent counts as having scored none - name: sort_order in: query required: false schema: enum: - asc - desc type: string description: >- Whether `sort_by_evaluator` puts the highest scores first or the lowest. Ignored without it default: desc title: Sort Order description: >- Whether `sort_by_evaluator` puts the highest scores first or the lowest. Ignored without it - name: include_content in: query required: false schema: type: boolean description: >- Also return each trace's full input, output and metadata. Use `limit` and `offset` to page through them default: false title: Include Content description: >- Also return each trace's full input, output and metadata. Use `limit` and `offset` to page through them - name: include_score_averages in: query required: false schema: type: boolean description: >- Also return each evaluator's mean score over every matching trace, not just this page. Costs a pass over those traces, so ask for it when the filters change rather than on every page default: false title: Include Score Averages description: >- Also return each evaluator's mean score over every matching trace, not just this page. Costs a pass over those traces, so ask for it when the filters change rather than on every page - name: limit in: query required: false schema: type: integer maximum: 1000000 minimum: 1 description: Maximum number of items to return default: 50 title: Limit description: Maximum number of items to return - name: offset in: query required: false schema: type: integer minimum: 0 description: Number of items to skip before returning results default: 0 title: Offset description: Number of items to skip before returning results responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/TraceListResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - ApiKeyAuth: [] components: schemas: TraceListResponse: properties: items: items: $ref: '#/components/schemas/TraceSummary' type: array title: Items description: The page of results total: type: integer title: Total description: Total number of items matching the query, before pagination limit: anyOf: - type: integer - type: 'null' title: Limit description: The applied `limit` (null when unbounded) offset: type: integer title: Offset description: The applied `offset` default: 0 score_averages: anyOf: - items: $ref: '#/components/schemas/TraceScoreAverage' type: array - type: 'null' title: Score Averages description: >- One average for each evaluator linked to the agent that scored at least one trace matching the filters, covering all the matching traces it scored rather than this page. Ask for it with `include_score_averages` type: object required: - items - total title: TraceListResponse description: >- The page, plus the averages when `include_score_averages` asked for them. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError TraceSummary: properties: uuid: type: string maxLength: 36 minLength: 36 title: Uuid description: Unique ID for the trace examples: - f47ac10b-58cc-4372-a567-0e02b2c3d479 agent_id: type: string title: Agent Id description: ID of the agent that produced the turn message_id: anyOf: - type: string - type: 'null' title: Message Id description: The message ID you sent, if any conversation_id: anyOf: - type: string - type: 'null' title: Conversation Id description: The conversation ID you sent, if any input_preview: anyOf: - type: string - type: 'null' title: Input Preview description: >- The standalone prompt or the last user message, truncated for display response_preview: anyOf: - type: string - type: 'null' title: Response Preview description: The agent reply, truncated for display tool_names: items: type: string type: array title: Tool Names description: Names of the tools the agent issued on this turn, in order tool_calls: items: $ref: '#/components/schemas/TraceToolCall' type: array title: Tool Calls description: Tools the agent issued on this turn, with the arguments it passed turn_count: type: integer title: Turn Count description: Number of turns in the stored input. A standalone prompt counts as 1 tool_call_count: type: integer title: Tool Call Count description: Number of tool calls the agent issued for this turn metadata_count: type: integer title: Metadata Count description: Number of metadata entries stored with the trace labels: items: type: string type: array title: Labels description: >- Your own tags for this turn, such as an environment or a release. Matched exactly when filtering, so keep the spelling stable input: anyOf: - type: string maxLength: 50000 minLength: 1 - items: $ref: '#/components/schemas/TraceTurn' type: array maxItems: 500 minItems: 1 - type: 'null' title: Input description: >- What the agent was given for this turn. For a `general` agent, the standalone prompt as a string. For a `conversation` agent, the history up to the reported output, oldest turn first, in OpenAI chat format. Sent only with `include_content` output: anyOf: - $ref: '#/components/schemas/TraceOutput' - type: 'null' description: >- What the agent produced for this turn. Sent only with `include_content` metadata: anyOf: - items: $ref: '#/components/schemas/TraceMetadataEntry' type: array - type: 'null' title: Metadata description: >- Key-value pairs stored with the trace. Sent only with `include_content` created_at: type: string title: Created At description: When the trace was created (ISO 8601 UTC) latest_run_status: anyOf: - $ref: '#/components/schemas/TraceEvalRunStatus' - type: 'null' description: Status of the latest scoring run for this trace latest_run_error: anyOf: - type: string - type: 'null' title: Latest Run Error description: Why the latest scoring run was skipped or failed results: items: $ref: '#/components/schemas/TraceScoreResult' type: array title: Results description: >- Results on the latest scoring run from the evaluators linked to the agent type: object required: - uuid - agent_id - tool_names - tool_calls - turn_count - tool_call_count - metadata_count - labels - created_at title: TraceSummary TraceScoreAverage: properties: evaluator_uuid: type: string maxLength: 36 minLength: 36 title: Evaluator Uuid description: ID of the evaluator these numbers are for examples: - f47ac10b-58cc-4372-a567-0e02b2c3d479 name: type: string title: Name description: >- Name of the evaluator. Uses the last stored name if it has been deleted output_type: type: string enum: - binary - rating title: Output Type description: | How the evaluator scores: - `binary`: pass or fail - `rating`: a numeric score, using the scale in `output_config` traces_scored: type: integer title: Traces Scored description: How many of the matching traces this evaluator scored average: type: number title: Average description: >- Mean of those scores. A binary evaluator averages 0 and 1, so its mean is the share that passed scale_min: anyOf: - type: number - type: 'null' title: Scale Min description: Lowest value on a rating scale scale_max: anyOf: - type: number - type: 'null' title: Scale Max description: Highest value on a rating scale type: object required: - evaluator_uuid - name - output_type - traces_scored - average title: TraceScoreAverage ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError TraceToolCall: properties: tool: type: string maxLength: 255 minLength: 1 title: Tool description: Name of the tool the agent called arguments: anyOf: - additionalProperties: true type: object - type: 'null' description: >- Argument values the agent passed to the tool. Omit when the call had none output: title: Output description: >- What the tool returned for this call. Any JSON value. Omit when you do not record it additionalProperties: false type: object required: - tool title: TraceToolCall TraceTurn: properties: role: type: string maxLength: 64 minLength: 1 title: Role description: Message author role in the conversation history content: anyOf: - type: string maxLength: 50000 - type: 'null' title: Content description: Message text. Omit for turns that only carry tool calls additionalProperties: true type: object required: - role title: TraceTurn TraceOutput: properties: response: anyOf: - type: string maxLength: 50000 - type: 'null' title: Response description: >- The assistant reply text for this turn. Omit for turns that only issued tool calls tool_calls: anyOf: - items: $ref: '#/components/schemas/TraceToolCall' type: array maxItems: 50 - type: 'null' title: Tool Calls description: >- Tool calls the agent issued for this turn. Omit for plain text replies additionalProperties: false type: object title: TraceOutput TraceMetadataEntry: properties: key: type: string maxLength: 256 minLength: 1 title: Key description: Name of the metadata entry value: type: string maxLength: 8192 title: Value description: Value of the metadata entry additionalProperties: false type: object required: - key - value title: TraceMetadataEntry TraceEvalRunStatus: type: string enum: - pending - processing - completed - failed - skipped title: TraceEvalRunStatus TraceScoreResult: properties: evaluator_uuid: type: string maxLength: 36 minLength: 36 title: Evaluator Uuid description: ID of the evaluator that produced this result examples: - f47ac10b-58cc-4372-a567-0e02b2c3d479 name: type: string title: Name description: >- Name of the evaluator. Uses the last stored name if it has been deleted evaluator_type: anyOf: - type: string enum: - tts - stt - llm - llm-general - conversation - tool-call - type: 'null' title: Evaluator Type description: > What the evaluator judges: - `tts`: TTS audio - `stt`: one transcript - `llm`: a reply with its conversation history - `llm-general`: a standalone input and output pair - `conversation`: a full conversation - `tool-call`: whether the agent called the right tool, labelled by a person output_type: type: string enum: - binary - rating title: Output Type description: | How the evaluator scores: - `binary`: pass or fail - `rating`: a numeric score, using the scale in `output_config` scale_min: anyOf: - type: number - type: 'null' title: Scale Min description: Lowest value on a rating scale scale_max: anyOf: - type: number - type: 'null' title: Scale Max description: Highest value on a rating scale value: type: number title: Value description: >- The judged result. Binary stores 0 or 1. Rating stores the numeric score reasoning: anyOf: - type: string - type: 'null' title: Reasoning description: The judge's rationale for this result evaluator_version_id: type: string maxLength: 36 minLength: 36 title: Evaluator Version Id description: ID of the evaluator version that produced this result examples: - f47ac10b-58cc-4372-a567-0e02b2c3d479 passed: type: boolean title: Passed description: >- Whether this evaluator passed. A binary result passes on 1. A rating passes at the top of its scale type: object required: - evaluator_uuid - name - output_type - value - evaluator_version_id - passed title: TraceScoreResult securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key for authentication ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.