--- title: "List Traces" method: GET path: "/v1/traces" tags: ["Tracing"] --- # List Traces `GET /v1/traces` ## Request - Base URL: `https://api.confident-ai.com` - URL: `https://api.confident-ai.com/v1/traces` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) Retrieves a list of traces from your Confident AI project. ## Response `200` - GetTraceResponse - `success` boolean, required: This is true if the traces were successfully retrieved. - `data` object, required: This maps to the list of traces retrieved. - `traces` Trace[], required: This is the list of traces retrieved. - `uuid` string, required: This is the unique identifier of the trace. - `name` string: This is the name of the trace. - `input` string: This is the input to the trace. - `output` string: This is the output of the trace. - `startTime` string, date-time, required: This is the time the trace started. - `endTime` string, date-time, required: This is the time the trace ended. - `environment` 'production' | 'development' | 'staging' | 'testing': This is the environment where your trace was posted, which helps with separating and debugging traces from different environments on the Confident AI platform. - `metadata` object: This is any additional metadata associated with the trace. - `tags` string[]: This is any tags associated with the trace, which helps with grouping traces and filtering them on the Confident AI platform. - `spans` union[]: This is the list of base spans associated with the trace. - union - BaseSpan - `uuid` string, required: This is the unique identifier of the span. - `name` string, required: This is the name of the span. - `input` string: This is the input to the span. - `output` string: This is the output of the span. - `error` string: This is the error message, if an error occurred inside the span. - `status` 'SUCCESS' | 'ERRORED': This represents the error status of the span. - `startTime` string, date-time, required: This is the time the span started. - `endTime` string, date-time, required: This is the time the span ended. - `parentUuid` string, uuid: This is the unique identifier of the span's parent span. - `metadata` object: This is any additional metadata associated with the span. - `metricCollection` string: This is the metric collection to be used for evaluating the span. - `type` string: This is a string that represents the type of span. - `retrievalContext` string[]: This is the retrieval context of your span, which is to be used for evaluation. - `context` string[]: This is the ideal retrieval context of your span, which is to be used for evaluation. - `expectedOutput` string: This is the expected output of your span, which is the ideal actual output and to be used for evaluation. - `toolsCalled` ToolCallData[]: This is the tools called by your span, which is to be used for evaluation. - … - `expectedTools` ToolCallData[]: This is the expected tools to be called by the span, which is to be used for evaluation. - … - `integration` string: This is the integration associated with the span. - LlmSpan - `uuid` string: This is the unique identifier of the span. - `name` string: This is the name of the span. - `input` string: This is the input to the span. - `output` string: This is the output of the span. - `error` string: This is the error message, if an error occurred inside the span. - `status` 'SUCCESS' | 'ERRORED': This represents the error status of the span. - `startTime` string, date-time: This is the time the span started. - `endTime` string, date-time: This is the time the span ended. - `parentUuid` string, uuid: This is the unique identifier of the span's parent span. - `metadata` object: This is any additional metadata associated with the span. - `metricCollection` string: This is the metric collection to be used for evaluating the span. - `type` string: This is a string that represents the type of span. - `retrievalContext` string[]: This is the retrieval context of your span, which is to be used for evaluation. - `context` string[]: This is the ideal retrieval context of your span, which is to be used for evaluation. - `expectedOutput` string: This is the expected output of your span, which is the ideal actual output and to be used for evaluation. - `toolsCalled` ToolCallData[]: This is the tools called by your span, which is to be used for evaluation. - … - `expectedTools` ToolCallData[]: This is the expected tools to be called by the span, which is to be used for evaluation. - … - `model` string, required: This is the LLM model used in the span. - `provider` string: This is the provider of the generation model used in the span. - `integration` string: This is the integration associated with the span. - `promptAlias` string: This is the alias of your prompt which is stored on Confident AI. - `promptCommitHash` string: This is the hash of the current prompt being logged in the llm span. - `promptLabel` string: This is the label assigned to a specific version of prompt on the Confident AI platform. - `promptVersion` string: This is the version assigned to your prompt on Confident AI. - `costPerInputToken` number, float: This is the cost per input token of the LLM model. - `costPerOutputToken` number, float: This is the cost per output token of the LLM model. - `inputTokenCount` integer: This is the number of input tokens passed to the LLM model. - `outputTokenCount` integer: This is the number of output tokens generated by the LLM model. - RetrieverSpan - `uuid` string: This is the unique identifier of the span. - `name` string: This is the name of the span. - `input` string: This is the input to the span. - `output` string: This is the output of the span. - `error` string: This is the error message, if an error occurred inside the span. - `status` 'SUCCESS' | 'ERRORED': This represents the error status of the span. - `startTime` string, date-time: This is the time the span started. - `endTime` string, date-time: This is the time the span ended. - `parentUuid` string, uuid: This is the unique identifier of the span's parent span. - `metadata` object: This is any additional metadata associated with the span. - `metricCollection` string: This is the metric collection to be used for evaluating the span. - `type` string: This is a string that represents the type of span. - `retrievalContext` string[]: This is the retrieval context of your span, which is to be used for evaluation. - `context` string[]: This is the ideal retrieval context of your span, which is to be used for evaluation. - `expectedOutput` string: This is the expected output of your span, which is the ideal actual output and to be used for evaluation. - `integration` string: This is the integration associated with the span. - `toolsCalled` ToolCallData[]: This is the tools called by your span, which is to be used for evaluation. - … - `expectedTools` ToolCallData[]: This is the expected tools to be called by the span, which is to be used for evaluation. - … - `embedder` string, required: This is the embedder model used in the span. - `topK` integer: This is the top K chunks retrieved from your knowledge base. - `chunkSize` integer: This is the chunk size of each retrieved context. - ToolSpan - `uuid` string: This is the unique identifier of the span. - `name` string: This is the name of the span. - `input` string: This is the input to the span. - `output` string: This is the output of the span. - `error` string: This is the error message, if an error occurred inside the span. - `integration` string: This is the integration associated with the span. - `status` 'SUCCESS' | 'ERRORED': This represents the error status of the span. - `startTime` string, date-time: This is the time the span started. - `endTime` string, date-time: This is the time the span ended. - `parentUuid` string, uuid: This is the unique identifier of the span's parent span. - `metadata` object: This is any additional metadata associated with the span. - `metricCollection` string: This is the metric collection to be used for evaluating the span. - `type` string: This is a string that represents the type of span. - `retrievalContext` string[]: This is the retrieval context of your span, which is to be used for evaluation. - `context` string[]: This is the ideal retrieval context of your span, which is to be used for evaluation. - `expectedOutput` string: This is the expected output of your span, which is the ideal actual output and to be used for evaluation. - `toolsCalled` ToolCallData[]: This is the tools called by your span, which is to be used for evaluation. - … - `expectedTools` ToolCallData[]: This is the expected tools to be called by the span, which is to be used for evaluation. - … - `description` string: This is the description of the tool used in the span. - AgentSpan - `uuid` string: This is the unique identifier of the span. - `name` string: This is the name of the span. - `input` string: This is the input to the span. - `output` string: This is the output of the span. - `integration` string: This is the integration associated with the span. - `error` string: This is the error message, if an error occurred inside the span. - `status` 'SUCCESS' | 'ERRORED': This represents the error status of the span. - `startTime` string, date-time: This is the time the span started. - `endTime` string, date-time: This is the time the span ended. - `parentUuid` string, uuid: This is the unique identifier of the span's parent span. - `metadata` object: This is any additional metadata associated with the span. - `metricCollection` string: This is the metric collection to be used for evaluating the span. - `type` string: This is a string that represents the type of span. - `retrievalContext` string[]: This is the retrieval context of your span, which is to be used for evaluation. - `context` string[]: This is the ideal retrieval context of your span, which is to be used for evaluation. - `expectedOutput` string: This is the expected output of your span, which is the ideal actual output and to be used for evaluation. - `toolsCalled` ToolCallData[]: This is the tools called by your span, which is to be used for evaluation. - … - `expectedTools` ToolCallData[]: This is the expected tools to be called by the span, which is to be used for evaluation. - … - `availableTools` string[]: This is the list of names of available tools to be used in the span. - `agentHandoffs` string[]: This is the list of potential agent handoffs in the span. - `threadId` string: This is the unique identifier of the thread associated with the trace. - `thread` object: Thread-level fields applied to the thread record. `thread.id` is an alternate way to specify the thread (must match top-level `threadId` if both are provided). `metadata` and `tags` only take effect when a thread id is resolvable; successive ingestions merge metadata keys, while tags replace any prior value. - `id` string: The thread id. Equivalent to top-level `threadId`; if both are set they must match. - `metadata` object, nullable: Custom key/value metadata to attach to the thread. Values can be any JSON-serializable type and are stringified server-side. Successive ingestions for the same thread merge metadata keys. - `tags` string[], nullable: Tags to set on the thread. Replaces any previously stored tags. - `userId` string: This is the unique identifier for your end user for the trace. - `metricCollection` string: This is the metric collection you wish to use to evaluate the trace. - `testRunId` string: This is the unique identifier of the test run to associate the trace with. When set, the trace becomes one test case in that test run, and `metricCollection` is required. Create a test run with the `POST /v1/test-runs` endpoint to get this id. - `retrievalContext` string[]: This is the retrieval context of your trace, which is to be used for evaluation. - `context` string[]: This is the ideal retrieval context of your trace, which is to be used for evaluation. - `expectedOutput` string: This is the expected output of your trace, which is the ideal actual output and to be used for evaluation. - `toolsCalled` ToolCallData[]: This is the tools called by your trace, which is to be used for evaluation. - `name` string, required: This is the name of the tool. - `description` string, required: This is the description of the tool. - `inputParameters` object: This is the input parameters that are passed to the tool. - `output` string: This is the output of the tool. - `reasoning` string: This is the reasoning your LLM provided for the tool call. - `expectedTools` ToolCallData[]: This is the expected tools to be called by the trace, which is to be used for evaluation. - `name` string, required: This is the name of the tool. - `description` string, required: This is the description of the tool. - `inputParameters` object: This is the input parameters that are passed to the tool. - `output` string: This is the output of the tool. - `reasoning` string: This is the reasoning your LLM provided for the tool call. - `attachments` object: Map of attachment ids to payloads for all `[DEEPEVAL:IMAGE:…]` and `[DEEPEVAL:PDF:…]` markers in this trace. Define attachments at the trace level with same ids for same instances. - `totalTraces` integer, required: This is the total number of traces retrieved. - `deprecated` boolean, required: This is true if this endpoint is deprecated. ## Changes > 54 revisions in range; 3 not diffed. - **2026-06-30** `448829180950`: 1 info - added the optional property `data/traces/items/testRunId` to the response with the `200` status - **2026-06-29** `77c4156f18d2`: 1 warning - removed the optional property `data/traces/items/testRunId` from the response with the `200` status - **2026-06-29** `c77c54067665`: 1 info - added the optional property `data/traces/items/testRunId` to the response with the `200` status - **2026-06-28** `0d196a3b614e`: 1 warning - removed the optional property `data/traces/items/testRunId` from the response with the `200` status - **2026-06-28** `c1fef814439e`: 1 info - added the optional property `data/traces/items/testRunId` to the response with the `200` status [Operation history](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/changes/v1/traces/get.md) --- [API](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api.md) - [All operations](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/revisions/95cdde71b65e?raw)