Get Trace

GEThttps://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.

GET/v2/traces/{traceUuid}

curl -X GET "https://api.confident-ai.com/v2/traces/{traceUuid}" \
  -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>"

200

{
  "success": true,
  "data": {
    "uuid": "<TRACE-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",
    "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": "<SPAN-UUID>",
        "traceUuid": "<TRACE-UUID>",
        "parentUuid": "<PARENT-SPAN-UUID>",
        "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."
          }
        ],
        "metricsData": [
          {
            "id": "<METRIC-DATA-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
          }
        ],
        "annotations": [
          {
            "id": "<ANNOTATION-ID>",
            "rating": 1,
            "type": "FIVE_STAR_RATING",
            "name": null,
            "explanation": "Correct and concise.",
            "expectedOutcome": null,
            "expectedOutput": "The capital of France is Paris.",
            "createdAt": "2025-01-15T11:00:00.000Z",
            "user": {
              "id": "<USER-ID>",
              "email": "jane@acme.com",
              "name": "Jane Doe",
              "image": null
            }
          }
        ]
      }
    ],
    "metricsData": [
      {
        "id": "<METRIC-DATA-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
      }
    ],
    "annotations": [
      {
        "id": "<ANNOTATION-ID>",
        "rating": 1,
        "type": "FIVE_STAR_RATING",
        "name": null,
        "explanation": "Correct and concise.",
        "expectedOutcome": null,
        "expectedOutput": "The capital of France is Paris.",
        "createdAt": "2025-01-15T11:00:00.000Z",
        "user": {
          "id": "<USER-ID>",
          "email": "jane@acme.com",
          "name": "Jane Doe",
          "image": null
        }
      }
    ]
  },
  "deprecated": false
}

Headers

CONFIDENT_API_KEYstringRequired
The API key of your Confident AI project.

Path parameters

traceUuidstringRequired
The unique identifier of the trace.

Response

Get Trace succeeded.

successboolean
Indicates if the request was successful.
dataobject
A trace with its full input and output, evaluation fields, classifier labels, results and annotations, and its spans when retrieved by id.
Show 25 propertiesHide 25 properties
- uuidstring
  This is the unique identifier of the trace.
- namestring | null
  This is the name of the trace.
- statusenum
  This represents the error status of a trace or span: SUCCESS when it completed, ERRORED when it failed.
  Show 2 enum valuesHide 2 enum values
  - SUCCESS
  - ERRORED
- startTimestring
  This is the time the trace started.
- endTimestring
  This is the time the trace ended.
- latencyinteger
  This is how long the trace took, in milliseconds.
- costnumber | null
  This is the total cost of the trace in USD, summed from its spans, or null when it is not known.
- threadIdstring | 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.
- userIdstring | null
  This is the user id you provided for this trace, or null when you did not.
- environmentenum
  This is the environment where your trace was posted, which helps with separating and debugging traces from different environments on the Confident AI platform.
  Show 4 enum valuesHide 4 enum values
  - production
  - development
  - staging
  - testing
- tagsarray | null
  This is the list of tags associated with the trace, which is useful for grouping and filtering for traces.
- metadataobject | null
  This is any additional metadata associated with the trace.
- inputstring | null
  This is the input to the trace. JSON inputs are serialized to a string.
- outputstring | null
  This is the output of the trace. JSON outputs are serialized to a string.
- expectedOutputstring | null
  This is the expected output associated with the trace, to be used for evaluations.
- retrievalContextarray | null
  This is the retrieval context associated with the trace, to be used for evaluations.
- contextarray | null
  This is the ideal retrieval context associated with the trace, to be used for evaluations.
- toolsCalledarray | null
  This is the list of tools called by the trace, to be used for evaluations.
  Show 6 propertiesHide 6 properties
  - namestring
    This is the name of the tool.
  - typeenum
    The type of the tool call, either a function or an MCP tool.
    Show 2 enum valuesHide 2 enum values
    FUNCTION
    MCP
  - descriptionstring
    This is the description of the tool.
  - inputParametersobject | null
    This is the input parameters that are passed to the tool.
  - outputany
    This is the output of the tool.
  - reasoningstring
    This is the reasoning your LLM provided for the tool call.
- expectedToolsarray | null
  This is the list of expected tools associated with the trace, to be used for evaluations.
  Show 6 propertiesHide 6 properties
  - namestring
    This is the name of the tool.
  - typeenum
    The type of the tool call, either a function or an MCP tool.
    Show 2 enum valuesHide 2 enum values
    FUNCTION
    MCP
  - descriptionstring
    This is the description of the tool.
  - inputParametersobject | null
    This is the input parameters that are passed to the tool.
  - outputany
    This is the output of the tool.
  - reasoningstring
    This is the reasoning your LLM provided for the tool call.
- testCaseIdstring | null
  This is the test case id of the trace, which is only set if the trace was created while evaluating a test case.
- metricCollectionNamestring | null
  This is the name of the metric collection assigned to evaluate the trace.
- labelsobject
  The labels your project's classifiers assigned to the trace, keyed by classifier name.
- spanslist 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.
  Show 41 propertiesHide 41 properties
  - uuidstring
    This is the unique identifier of the span.
  - traceUuidstring
    This is the uuid of the trace containing the span.
  - parentUuidstring | null
    This is the uuid of the parent span, or null for a root span.
  - namestring | null
    This is the name of the span.
  - typeenum
    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.
    Show 5 enum valuesHide 5 enum values
    SPAN
    AGENT
    TOOL
    RETRIEVER
    LLM
  - statusenum
    This represents the error status of a trace or span: SUCCESS when it completed, ERRORED when it failed.
    Show 2 enum valuesHide 2 enum values
    SUCCESS
    ERRORED
  - startTimestring
    This is the time the span started.
  - endTimestring
    This is the time the span ended.
  - errorstring | null
    This is the error string that caused the span to fail, or null when no error occurred.
  - integrationstring | null
    This is the integration associated with the span.
  - providerstring | null
    This is the LLM provider used in an LLM span.
  - modelstring | null
    This is the LLM model used in an LLM span.
  - endpointstring | null
    This is the API endpoint the model was called through in an LLM span.
  - costnumber | null
    This is the total cost of the span in USD, or null when it is not known.
  - inputTokenCostnumber | null
    This is the total cost of the input tokens passed to the LLM model in an LLM span.
  - outputTokenCostnumber | null
    This is the total cost of the output tokens generated by the LLM model in an LLM span.
  - costPerInputTokennumber | null
    This is the cost per input token of the LLM model for an LLM span.
  - costPerOutputTokennumber | null
    This is the cost per output token of the LLM model for an LLM span.
  - inputTokenCountinteger | null
    This is the total number of input tokens passed to the LLM model in an LLM span.
  - outputTokenCountinteger | null
    This is the total number of output tokens generated by the LLM model in an LLM span.
  - promptAliasstring | null
    This is the alias of your prompt which is stored on Confident AI.
  - promptVersionstring | null
    This is the version assigned to your prompt on Confident AI.
  - promptLabelstring | null
    This is the label assigned to a specific version of prompt on the Confident AI platform.
  - promptCommitHashstring | null
    This is the hash of the current prompt being logged in the llm span.
  - embedderstring | null
    This is the embedder model used in a retriever span.
  - topKinteger | null
    This is the top K chunks retrieved from your knowledge base in a retriever span.
  - chunkSizeinteger | null
    This is the chunk size of each retrieved context for a retriever span.
  - descriptionstring | null
    This is a description if the span is a tool span.
  - agentHandoffsarray | null
    This is the list of agent handoffs associated with an agent span.
  - availableToolsarray | null
    This is the list of available tools associated with an agent span.
  - metadataobject | null
    This is any additional metadata associated with the span.
  - metricCollectionNamestring | null
    This is the name of the metric collection to evaluate the span.
  - inputstring | null
    This is the input to the span. JSON inputs are serialized to a string.
  - outputstring | null
    This is the output of the span. JSON outputs are serialized to a string.
  - expectedOutputstring | null
    This is the expected output of your span, which is the ideal actual output and to be used for evaluation.
  - retrievalContextarray | null
    This is the retrieval context of your span, which is to be used for evaluation.
  - contextarray | null
    This is the ideal retrieval context of your span, which is to be used for evaluation.
  - toolsCalledarray | null
    This is the tools called by your span, which is to be used for evaluation.
    Show 6 propertiesHide 6 properties
    namestring
    This is the name of the tool.
    typeenum
    The type of the tool call, either a function or an MCP tool.
    Show 2 enum valuesHide 2 enum values
    FUNCTION
    MCP
    descriptionstring
    This is the description of the tool.
    inputParametersobject | null
    This is the input parameters that are passed to the tool.
    outputany
    This is the output of the tool.
    reasoningstring
    This is the reasoning your LLM provided for the tool call.
  - expectedToolsarray | null
    This is the expected tools to be called by the span, which is to be used for evaluation.
    Show 6 propertiesHide 6 properties
    namestring
    This is the name of the tool.
    typeenum
    The type of the tool call, either a function or an MCP tool.
    Show 2 enum valuesHide 2 enum values
    FUNCTION
    MCP
    descriptionstring
    This is the description of the tool.
    inputParametersobject | null
    This is the input parameters that are passed to the tool.
    outputany
    This is the output of the tool.
    reasoningstring
    This is the reasoning your LLM provided for the tool call.
  - metricsDatalist of objects
    This is the metrics data associated with the span.
    Show 16 propertiesHide 16 properties
    idstring
    The unique identifier of the metric data entry.
    namestring
    The name of the metric.
    scorenumber | null
    The final metric score, or null when the metric errored or was skipped.
    reasonstring | null
    The reason for the metric score, generated by the evaluation model at evaluation time.
    successboolean | null
    Whether the metric score is above the threshold, or null while the evaluation is still running.
    thresholdnumber | null
    The threshold for the metric, which determines if the metric is passing or failing.
    strictModeboolean
    Whether the metric was run in strict mode, which outputs a binary score of 0 or 1.
    skippedboolean
    Whether the metric evaluation was skipped.
    flakyboolean
    Whether the metric's verdict was non-deterministic across runs.
    evaluationModelstring | null
    The evaluation model used to run the evaluation.
    evaluationCostnumber | null
    The cost of running the evaluation in USD.
    errorstring | null
    The error message if the evaluation failed.
    errorTypeenum | null
    Why an evaluation errored: the AI connection or a transformer failed, the evaluation model failed, the test case lacked the parameters the metric needs, or an internal error occurred.
    Show 5 enum valuesHide 5 enum values
    AI_CONNECTION_ERROR
    TRANSFORMER_ERROR
    EVALUATION_MODEL_ERROR
    INVALID_TEST_CASE_PARAMETERS
    INTERNAL_ERROR
    createdAtstring
    The time the metric data was created.
    evaluatedAtstring | null
    The time the metric was evaluated, or null while it is still running.
    multiTurnboolean
    Whether this metric was evaluated on a multi-turn conversation.
  - annotationslist of objects
    This is the list of annotations associated with the span.
    Show 9 propertiesHide 9 properties
    idstring
    This is the id of the annotation generated by Confident AI.
    ratinginteger
    This is the annotated rating score.
    typeenum
    This is the type of annotation, which can be either thumbs rating or five star rating.
    Show 2 enum valuesHide 2 enum values
    FIVE_STAR_RATING
    THUMBS_RATING
    namestring | null
    The name of the annotation.
    explanationstring | null
    This is the explanation for the annotation.
    expectedOutcomestring | null
    This is the annotated expected outcome, for conversation annotations.
    expectedOutputstring | null
    This is the annotated expected output, for span and trace annotations.
    createdAtstring
    The timestamp when the annotation was created.
    userobject | null
    A Confident AI user, as referenced by the records they created.
    Show 4 propertiesHide 4 properties
    idstring
    This is the id of the user.
    emailstring
    This is the email address of the user.
    namestring | null
    This is the display name of the user, or null when they have not set one.
    imagestring | null
    This is the URL of the user's avatar, or null when they have none.
- metricsDatalist of objects
  This is the list of metrics data associated with the trace after running evaluations.
  Show 16 propertiesHide 16 properties
  - idstring
    The unique identifier of the metric data entry.
  - namestring
    The name of the metric.
  - scorenumber | null
    The final metric score, or null when the metric errored or was skipped.
  - reasonstring | null
    The reason for the metric score, generated by the evaluation model at evaluation time.
  - successboolean | null
    Whether the metric score is above the threshold, or null while the evaluation is still running.
  - thresholdnumber | null
    The threshold for the metric, which determines if the metric is passing or failing.
  - strictModeboolean
    Whether the metric was run in strict mode, which outputs a binary score of 0 or 1.
  - skippedboolean
    Whether the metric evaluation was skipped.
  - flakyboolean
    Whether the metric's verdict was non-deterministic across runs.
  - evaluationModelstring | null
    The evaluation model used to run the evaluation.
  - evaluationCostnumber | null
    The cost of running the evaluation in USD.
  - errorstring | null
    The error message if the evaluation failed.
  - errorTypeenum | null
    Why an evaluation errored: the AI connection or a transformer failed, the evaluation model failed, the test case lacked the parameters the metric needs, or an internal error occurred.
    Show 5 enum valuesHide 5 enum values
    AI_CONNECTION_ERROR
    TRANSFORMER_ERROR
    EVALUATION_MODEL_ERROR
    INVALID_TEST_CASE_PARAMETERS
    INTERNAL_ERROR
  - createdAtstring
    The time the metric data was created.
  - evaluatedAtstring | null
    The time the metric was evaluated, or null while it is still running.
  - multiTurnboolean
    Whether this metric was evaluated on a multi-turn conversation.
- annotationslist of objects
  This is the list of annotations associated with the trace.
  Show 9 propertiesHide 9 properties
  - idstring
    This is the id of the annotation generated by Confident AI.
  - ratinginteger
    This is the annotated rating score.
  - typeenum
    This is the type of annotation, which can be either thumbs rating or five star rating.
    Show 2 enum valuesHide 2 enum values
    FIVE_STAR_RATING
    THUMBS_RATING
  - namestring | null
    The name of the annotation.
  - explanationstring | null
    This is the explanation for the annotation.
  - expectedOutcomestring | null
    This is the annotated expected outcome, for conversation annotations.
  - expectedOutputstring | null
    This is the annotated expected output, for span and trace annotations.
  - createdAtstring
    The timestamp when the annotation was created.
  - userobject | null
    A Confident AI user, as referenced by the records they created.
    Show 4 propertiesHide 4 properties
    idstring
    This is the id of the user.
    emailstring
    This is the email address of the user.
    namestring | null
    This is the display name of the user, or null when they have not set one.
    imagestring | null
    This is the URL of the user's avatar, or null when they have none.
deprecatedboolean
Indicates if this endpoint is deprecated.

Built byConfident AI