# Get Trace `GET https://api.confident-ai.com/v2/traces/{traceUuid}` Retrieves a trace by uuid from your Confident AI project, with its spans, full input and output, evaluation fields, classifier labels, results and annotations. ## Headers - `CONFIDENT_API_KEY` (string, required) — The API key of your Confident AI project. ## Path parameters - `traceUuid` (string, required) — The unique identifier of the trace. ## Response Get Trace succeeded. - `success` (boolean) — Indicates if the request was successful. - `data` (object) — A trace with its full input and output, evaluation fields, classifier labels, results and annotations, and its spans when retrieved by id. - `uuid` (string) — This is the unique identifier of the trace. - `name` (string | null) — This is the name of the trace. - `status` (enum) — This represents the error status of a trace or span: `SUCCESS` when it completed, `ERRORED` when it failed. One of `SUCCESS`, `ERRORED`. - `startTime` (string) — This is the time the trace started. - `endTime` (string) — This is the time the trace ended. - `latency` (integer) — This is how long the trace took, in milliseconds. - `cost` (number | null) — This is the total cost of the trace in `USD`, summed from its spans, or `null` when it is not known. - `threadId` (string | null) — This is the thread id of the trace, which groups traces in the same thread into a conversation, or `null` when the trace is not part of one. - `userId` (string | null) — This is the user id you provided for this trace, or `null` when you did not. - `customerId` (string | null) — This is the customer id you provided for this trace, or `null` when you did not. - `environment` (string) — This is the environment where your trace was posted, which helps with separating and debugging traces from different environments on the Confident AI platform. Any name up to 64 characters is accepted, for example production, staging or eu-prod. - `tags` (array | null) — This is the list of tags associated with the trace, which is useful for grouping and filtering for traces. - `metadata` (object | null) — This is any additional metadata associated with the trace. - `input` (string | null) — This is the input to the trace. JSON inputs are serialized to a string. - `output` (string | null) — This is the output of the trace. JSON outputs are serialized to a string. - `expectedOutput` (string | null) — This is the expected output associated with the trace, to be used for evaluations. - `retrievalContext` (array | null) — This is the retrieval context associated with the trace, to be used for evaluations. - `context` (array | null) — This is the ideal retrieval context associated with the trace, to be used for evaluations. - `toolsCalled` (array | null) — This is the list of tools called by the trace, to be used for evaluations. - `name` (string) — This is the name of the tool. - `type` (enum) — The type of the tool call, either a function or an MCP tool. One of `FUNCTION`, `MCP`. - `description` (string) — This is the description of the tool. - `inputParameters` (object | null) — This is the input parameters that are passed to the tool. - `output` (any) — This is the output of the tool. - `reasoning` (string) — This is the reasoning your LLM provided for the tool call. - `expectedTools` (array | null) — This is the list of expected tools associated with the trace, to be used for evaluations. - `name` (string) — This is the name of the tool. - `type` (enum) — The type of the tool call, either a function or an MCP tool. One of `FUNCTION`, `MCP`. - `description` (string) — This is the description of the tool. - `inputParameters` (object | null) — This is the input parameters that are passed to the tool. - `output` (any) — This is the output of the tool. - `reasoning` (string) — This is the reasoning your LLM provided for the tool call. - `testCaseId` (string | null) — This is the test case id of the trace, which is only set if the trace was created while evaluating a test case. - `metricCollectionName` (string | null) — This is the name of the metric collection assigned to evaluate the trace. - `labels` (object) — The labels your project's classifiers assigned to the trace, keyed by classifier name. - `spans` (list of objects) — This is the list of spans in the trace, present when the trace is retrieved by id. A thread's traces omit their spans. - `uuid` (string) — This is the unique identifier of the span. - `traceUuid` (string) — This is the uuid of the trace containing the span. - `parentUuid` (string | null) — This is the uuid of the parent span, or `null` for a root span. - `name` (string | null) — This is the name of the span. - `type` (enum) — The kind of work a span records: `SPAN` for a plain step, `LLM` for a model call, `RETRIEVER` for a knowledge-base lookup, `TOOL` for a tool call, and `AGENT` for an agent step. One of `SPAN`, `AGENT`, `TOOL`, `RETRIEVER`, `LLM`. - `status` (enum) — This represents the error status of a trace or span: `SUCCESS` when it completed, `ERRORED` when it failed. One of `SUCCESS`, `ERRORED`. - `startTime` (string) — This is the time the span started. - `endTime` (string) — This is the time the span ended. - `error` (string | null) — This is the error string that caused the span to fail, or `null` when no error occurred. - `integration` (string | null) — This is the integration associated with the span. - `provider` (string | null) — This is the LLM provider used in an LLM span. - `model` (string | null) — This is the LLM model used in an LLM span. - `endpoint` (string | null) — This is the API endpoint the model was called through in an LLM span. - `cost` (number | null) — This is the total cost of the span in `USD`, or `null` when it is not known. - `inputTokenCost` (number | null) — This is the total cost of the input tokens passed to the LLM model in an LLM span. - `outputTokenCost` (number | null) — This is the total cost of the output tokens generated by the LLM model in an LLM span. - `costPerInputToken` (number | null) — This is the cost per input token of the LLM model for an LLM span. - `costPerOutputToken` (number | null) — This is the cost per output token of the LLM model for an LLM span. - `inputTokenCount` (integer | null) — This is the total number of input tokens passed to the LLM model in an LLM span. - `outputTokenCount` (integer | null) — This is the total number of output tokens generated by the LLM model in an LLM span. - `promptAlias` (string | null) — This is the alias of your prompt which is stored on Confident AI. - `promptVersion` (string | null) — This is the version assigned to your prompt on Confident AI. - `promptLabel` (string | null) — This is the label assigned to a specific version of prompt on the Confident AI platform. - `promptCommitHash` (string | null) — This is the hash of the current prompt being logged in the llm span. - `embedder` (string | null) — This is the embedder model used in a retriever span. - `topK` (integer | null) — This is the top K chunks retrieved from your knowledge base in a retriever span. - `chunkSize` (integer | null) — This is the chunk size of each retrieved context for a retriever span. - `description` (string | null) — This is a description if the span is a tool span. - `agentHandoffs` (array | null) — This is the list of agent handoffs associated with an agent span. - `availableTools` (array | null) — This is the list of available tools associated with an agent span. - `metadata` (object | null) — This is any additional metadata associated with the span. - `metricCollectionName` (string | null) — This is the name of the metric collection to evaluate the span. - `input` (string | null) — This is the input to the span. JSON inputs are serialized to a string. - `output` (string | null) — This is the output of the span. JSON outputs are serialized to a string. - `expectedOutput` (string | null) — This is the expected output of your span, which is the ideal actual output and to be used for evaluation. - `retrievalContext` (array | null) — This is the retrieval context of your span, which is to be used for evaluation. - `context` (array | null) — This is the ideal retrieval context of your span, which is to be used for evaluation. - `toolsCalled` (array | null) — This is the tools called by your span, which is to be used for evaluation. - `name` (string) — This is the name of the tool. - `type` (enum) — The type of the tool call, either a function or an MCP tool. One of `FUNCTION`, `MCP`. - `description` (string) — This is the description of the tool. - `inputParameters` (object | null) — This is the input parameters that are passed to the tool. - `output` (any) — This is the output of the tool. - `reasoning` (string) — This is the reasoning your LLM provided for the tool call. - `expectedTools` (array | null) — This is the expected tools to be called by the span, which is to be used for evaluation. - `name` (string) — This is the name of the tool. - `type` (enum) — The type of the tool call, either a function or an MCP tool. One of `FUNCTION`, `MCP`. - `description` (string) — This is the description of the tool. - `inputParameters` (object | null) — This is the input parameters that are passed to the tool. - `output` (any) — This is the output of the tool. - `reasoning` (string) — This is the reasoning your LLM provided for the tool call. - `labels` (object) — The labels your project's classifiers assigned to the span, keyed by classifier name. - `metricsData` (list of objects) — This is the metrics data associated with the span. - `id` (string) — The unique identifier of the metric data entry. - `name` (string) — The name of the metric. - `score` (number | null) — The final metric score, or `null` when the metric errored or was skipped. - `reason` (string | null) — The reason for the metric score, generated by the evaluation model at evaluation time. - `success` (boolean | null) — Whether the metric score is above the threshold, or `null` while the evaluation is still running. - `threshold` (number | null) — The threshold for the metric, which determines if the metric is passing or failing. - `strictMode` (boolean) — Whether the metric was run in strict mode, which outputs a binary score of 0 or 1. - `skipped` (boolean) — Whether the metric evaluation was skipped. - `flaky` (boolean) — Whether the metric's verdict was non-deterministic across runs. - `evaluationModel` (string | null) — The evaluation model used to run the evaluation. - `evaluationCost` (number | null) — The cost of running the evaluation in `USD`. - `error` (string | null) — The error message if the evaluation failed. - `errorType` (enum | null) - `createdAt` (string) — The time the metric data was created. - `evaluatedAt` (string | null) — The time the metric was evaluated, or `null` while it is still running. - `multiTurn` (boolean) — Whether this metric was evaluated on a multi-turn conversation. - `traceUuid` (string | null) — The uuid of the trace this metric was evaluated on, or `null` if it was not evaluated on one. - `spanUuid` (string | null) — The uuid of the span this metric was evaluated on, for component-level metrics. - `threadId` (string | null) — The id of the thread this metric was evaluated on, for conversation-level metrics. - `testCaseId` (string | null) — The id of the test case this metric was evaluated on. - `testRunId` (string | null) — The id of the test run this result belongs to. Retrieve that test run to read the result alongside the rest of its test cases. - `annotations` (list of objects) — This is the list of annotations associated with the span. - `id` (string) — This is the id of the annotation generated by Confident AI. - `fieldType` (enum) — The kind of value an annotation holds: `TEXT`, `NUMBER`, `FLOAT` or `BOOLEAN` for a free value, `CHOICE` or `MULTIPLE_CHOICE` for a choice from the options in the field's `config`, and `THUMBS_RATING` or `FIVE_STAR_RATING` for a rating. One of `TEXT`, `NUMBER`, `FLOAT`, `BOOLEAN`, `CHOICE`, `MULTIPLE_CHOICE`, `FIVE_STAR_RATING`, `THUMBS_RATING`. - `value` (string | number | boolean | list of strings | null) — The annotated value, in the shape its `fieldType` expects: a boolean for `THUMBS_RATING` (`true` is thumbs up) and `BOOLEAN`, a whole number from 1 to 5 for `FIVE_STAR_RATING`, a number for `NUMBER` or `FLOAT`, a string for `TEXT` and `CHOICE`, and a list of strings for `MULTIPLE_CHOICE`. Null when the annotation was left without a value. - (string) - (number) - (boolean) - (list of strings) - (null) - `name` (string | null) — The name of the annotation. - `explanation` (string | null) — This is the explanation for the annotation. - `expectedOutcome` (string | null) — This is the annotated expected outcome, for conversation annotations. - `expectedOutput` (string | null) — This is the annotated expected output, for span and trace annotations. - `createdAt` (string) — The timestamp when the annotation was created. - `user` (object | null) - `id` (string) — This is the id of the user. - `email` (string) — This is the email address of the user. - `name` (string | null) — This is the display name of the user, or `null` when they have not set one. - `image` (string | null) — This is the URL of the user's avatar, or `null` when they have none. - `metricsData` (list of objects) — This is the list of metrics data associated with the trace after running evaluations. - `id` (string) — The unique identifier of the metric data entry. - `name` (string) — The name of the metric. - `score` (number | null) — The final metric score, or `null` when the metric errored or was skipped. - `reason` (string | null) — The reason for the metric score, generated by the evaluation model at evaluation time. - `success` (boolean | null) — Whether the metric score is above the threshold, or `null` while the evaluation is still running. - `threshold` (number | null) — The threshold for the metric, which determines if the metric is passing or failing. - `strictMode` (boolean) — Whether the metric was run in strict mode, which outputs a binary score of 0 or 1. - `skipped` (boolean) — Whether the metric evaluation was skipped. - `flaky` (boolean) — Whether the metric's verdict was non-deterministic across runs. - `evaluationModel` (string | null) — The evaluation model used to run the evaluation. - `evaluationCost` (number | null) — The cost of running the evaluation in `USD`. - `error` (string | null) — The error message if the evaluation failed. - `errorType` (enum | null) - `createdAt` (string) — The time the metric data was created. - `evaluatedAt` (string | null) — The time the metric was evaluated, or `null` while it is still running. - `multiTurn` (boolean) — Whether this metric was evaluated on a multi-turn conversation. - `traceUuid` (string | null) — The uuid of the trace this metric was evaluated on, or `null` if it was not evaluated on one. - `spanUuid` (string | null) — The uuid of the span this metric was evaluated on, for component-level metrics. - `threadId` (string | null) — The id of the thread this metric was evaluated on, for conversation-level metrics. - `testCaseId` (string | null) — The id of the test case this metric was evaluated on. - `testRunId` (string | null) — The id of the test run this result belongs to. Retrieve that test run to read the result alongside the rest of its test cases. - `annotations` (list of objects) — This is the list of annotations associated with the trace. - `id` (string) — This is the id of the annotation generated by Confident AI. - `fieldType` (enum) — The kind of value an annotation holds: `TEXT`, `NUMBER`, `FLOAT` or `BOOLEAN` for a free value, `CHOICE` or `MULTIPLE_CHOICE` for a choice from the options in the field's `config`, and `THUMBS_RATING` or `FIVE_STAR_RATING` for a rating. One of `TEXT`, `NUMBER`, `FLOAT`, `BOOLEAN`, `CHOICE`, `MULTIPLE_CHOICE`, `FIVE_STAR_RATING`, `THUMBS_RATING`. - `value` (string | number | boolean | list of strings | null) — The annotated value, in the shape its `fieldType` expects: a boolean for `THUMBS_RATING` (`true` is thumbs up) and `BOOLEAN`, a whole number from 1 to 5 for `FIVE_STAR_RATING`, a number for `NUMBER` or `FLOAT`, a string for `TEXT` and `CHOICE`, and a list of strings for `MULTIPLE_CHOICE`. Null when the annotation was left without a value. - (string) - (number) - (boolean) - (list of strings) - (null) - `name` (string | null) — The name of the annotation. - `explanation` (string | null) — This is the explanation for the annotation. - `expectedOutcome` (string | null) — This is the annotated expected outcome, for conversation annotations. - `expectedOutput` (string | null) — This is the annotated expected output, for span and trace annotations. - `createdAt` (string) — The timestamp when the annotation was created. - `user` (object | null) - `id` (string) — This is the id of the user. - `email` (string) — This is the email address of the user. - `name` (string | null) — This is the display name of the user, or `null` when they have not set one. - `image` (string | null) — This is the URL of the user's avatar, or `null` when they have none. - `deprecated` (boolean) — Indicates if this endpoint is deprecated. ## Request example ```bash curl -X GET "https://api.confident-ai.com/v2/traces/{traceUuid}" \ -H "CONFIDENT_API_KEY: " ``` ## Response example ```json { "success": true, "data": { "uuid": "", "name": "Geography QA", "status": "SUCCESS", "startTime": "2025-01-15T10:30:00.000Z", "endTime": "2025-01-15T10:30:05.000Z", "latency": 5000, "cost": 0.00018, "threadId": "thread-42", "userId": "end-user-42", "customerId": "acme-hotels", "environment": "production", "tags": [ "geography" ], "metadata": { "client": "acme-corp" }, "input": "What is the capital of France?", "output": "The capital of France is Paris.", "expectedOutput": "Paris", "retrievalContext": [ "Paris is the capital and most populous city of France." ], "context": null, "toolsCalled": [ { "name": "get_landmark_info", "type": "FUNCTION", "description": "This tool gives information about a mountain.", "inputParameters": { "mountain": "Everest" }, "output": "8,848 metres", "reasoning": "The user asked for the height of a mountain." } ], "expectedTools": [ { "name": "get_landmark_info", "type": "FUNCTION", "description": "This tool gives information about a mountain.", "inputParameters": { "mountain": "Everest" }, "output": "8,848 metres", "reasoning": "The user asked for the height of a mountain." } ], "testCaseId": null, "metricCollectionName": "Collection Name", "labels": { "intent": { "label": "geography", "reason": "The user asks for the capital city of a country." } }, "spans": [ { "uuid": "", "traceUuid": "", "parentUuid": "", "name": "OpenAI Call", "type": "SPAN", "status": "SUCCESS", "startTime": "2025-01-15T10:30:00.000Z", "endTime": "2025-01-15T10:30:02.000Z", "error": null, "integration": "LangChain", "provider": "OpenAI", "model": "gpt-4o", "endpoint": null, "cost": 0.00018, "inputTokenCost": 0.00006, "outputTokenCost": 0.00012, "costPerInputToken": 0.0000025, "costPerOutputToken": 0.00001, "inputTokenCount": 24, "outputTokenCount": 12, "promptAlias": "geography-assistant", "promptVersion": "00.00.01", "promptLabel": "production", "promptCommitHash": "bab04ce", "embedder": null, "topK": null, "chunkSize": null, "description": null, "agentHandoffs": null, "availableTools": null, "metadata": { "region": "Europe" }, "metricCollectionName": "LLM Collection Name", "input": "What is the capital of France?", "output": "The capital of France is Paris.", "expectedOutput": "Paris", "retrievalContext": [ "Paris is the capital and most populous city of France." ], "context": null, "toolsCalled": [ { "name": "get_landmark_info", "type": "FUNCTION", "description": "This tool gives information about a mountain.", "inputParameters": { "mountain": "Everest" }, "output": "8,848 metres", "reasoning": "The user asked for the height of a mountain." } ], "expectedTools": [ { "name": "get_landmark_info", "type": "FUNCTION", "description": "This tool gives information about a mountain.", "inputParameters": { "mountain": "Everest" }, "output": "8,848 metres", "reasoning": "The user asked for the height of a mountain." } ], "labels": { "tool outcome": { "label": "succeeded", "reason": "The tool returned the requested rows without error." } }, "metricsData": [ { "id": "", "name": "Answer Relevancy", "score": 0.95, "reason": "The answer directly states the capital of France.", "success": true, "threshold": 0.5, "strictMode": false, "skipped": false, "flaky": false, "evaluationModel": "gpt-4o", "evaluationCost": 0.0004, "error": null, "errorType": "AI_CONNECTION_ERROR", "createdAt": "2025-01-15T10:30:06.000Z", "evaluatedAt": "2025-01-15T10:30:09.000Z", "multiTurn": false, "traceUuid": "3f9c2a1e-5b7d-4c8e-9f01-2a3b4c5d6e7f", "spanUuid": null, "threadId": null, "testCaseId": "string", "testRunId": null } ], "annotations": [ { "id": "", "fieldType": "TEXT", "value": true, "name": null, "explanation": "Correct and concise.", "expectedOutcome": null, "expectedOutput": "The capital of France is Paris.", "createdAt": "2025-01-15T11:00:00.000Z", "user": { "id": "", "email": "jane@acme.com", "name": "Jane Doe", "image": null } } ] } ], "metricsData": [ { "id": "", "name": "Answer Relevancy", "score": 0.95, "reason": "The answer directly states the capital of France.", "success": true, "threshold": 0.5, "strictMode": false, "skipped": false, "flaky": false, "evaluationModel": "gpt-4o", "evaluationCost": 0.0004, "error": null, "errorType": "AI_CONNECTION_ERROR", "createdAt": "2025-01-15T10:30:06.000Z", "evaluatedAt": "2025-01-15T10:30:09.000Z", "multiTurn": false, "traceUuid": "3f9c2a1e-5b7d-4c8e-9f01-2a3b4c5d6e7f", "spanUuid": null, "threadId": null, "testCaseId": "string", "testRunId": null } ], "annotations": [ { "id": "", "fieldType": "TEXT", "value": true, "name": null, "explanation": "Correct and concise.", "expectedOutcome": null, "expectedOutput": "The capital of France is Paris.", "createdAt": "2025-01-15T11:00:00.000Z", "user": { "id": "", "email": "jane@acme.com", "name": "Jane Doe", "image": null } } ] }, "deprecated": false } ```