Get Trace

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 26 propertiesHide 26 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.

  • customerIdstring | null

    This is the customer id you provided for this trace, or null when you did not.

  • environmentstring

    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.

  • 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 21 propertiesHide 21 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.

      • traceUuidstring | null

        The uuid of the trace this metric was evaluated on, or null if it was not evaluated on one.

      • spanUuidstring | null

        The uuid of the span this metric was evaluated on, for component-level metrics.

      • threadIdstring | null

        The id of the thread this metric was evaluated on, for conversation-level metrics.

      • testCaseIdstring | null

        The id of the test case this metric was evaluated on.

      • testRunIdstring | 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.

    • 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.

      • fieldTypeenum

        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.

        Show 8 enum valuesHide 8 enum values

        • TEXT
        • NUMBER
        • FLOAT
        • BOOLEAN
        • CHOICE
        • MULTIPLE_CHOICE
        • FIVE_STAR_RATING
        • THUMBS_RATING

      • valuestring | 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.

        Show 5 variantsHide 5 variants

        • string

        • OR

        • number

        • OR

        • boolean

        • OR

        • list of strings

        • OR

        • null

      • 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 21 propertiesHide 21 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.

    • traceUuidstring | null

      The uuid of the trace this metric was evaluated on, or null if it was not evaluated on one.

    • spanUuidstring | null

      The uuid of the span this metric was evaluated on, for component-level metrics.

    • threadIdstring | null

      The id of the thread this metric was evaluated on, for conversation-level metrics.

    • testCaseIdstring | null

      The id of the test case this metric was evaluated on.

    • testRunIdstring | 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.

  • 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.

    • fieldTypeenum

      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.

      Show 8 enum valuesHide 8 enum values

      • TEXT
      • NUMBER
      • FLOAT
      • BOOLEAN
      • CHOICE
      • MULTIPLE_CHOICE
      • FIVE_STAR_RATING
      • THUMBS_RATING

    • valuestring | 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.

      Show 5 variantsHide 5 variants

      • string

      • OR

      • number

      • OR

      • boolean

      • OR

      • list of strings

      • OR

      • null

    • 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.