Retrieve Trace

GEThttps://api.confident-ai.com/v1/traces/{traceUuid}

Retrieves an existing trace on your Confident AI project.

GET/v1/traces/{traceUuid}

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

200

{
  "success": true,
  "data": {
    "uuid": "TRACE-ID",
    "name": "Trace Name",
    "startTime": "2025-01-15T10:30:00Z",
    "endTime": "2025-01-15T10:30:05Z",
    "projectId": "PROJECT-ID",
    "environment": "production",
    "spans": [
      {
        "id": "SPAN-ID",
        "uuid": "SPAN-UUID",
        "name": "Span Name",
        "startTime": "2025-01-15T10:30:00Z",
        "endTime": "2025-01-15T10:30:05Z",
        "traceUuid": "TRACE-UUID",
        "status": "SUCCESS",
        "type": "LLM",
        "provider": "OpenAI",
        "integration": "LangChain",
        "model": "gpt-4o"
      }
    ]
  },
  "deprecated": false
}

Headers

CONFIDENT_API_KEYstringRequired
The API key of your Confident AI project.

Path parameters

traceUuidstringRequired
This is the trace UUID you wish to retrieve.

Response

successboolean
This is true if the trace was successfully retrieved.
dataobject
This maps to the retrieved trace data.
Show 21 propertiesHide 21 properties
- uuidstring
  This is the uuid of the trace, not to be confused with the trace id.
- inputany
  This is the input to the trace.
- outputany
  This is the output of the trace.
- startTimestring
  This is the time the span started.
- endTimestring
  This is the time the span ended.
- namestring
  This is the name of the trace.
- metadataobject
  This is any additional metadata associated with the span.
- environmentenum
  This is the environment where the trace was created.
  Show 4 enum valuesHide 4 enum values
  - production
  - development
  - staging
  - testing
- threadIdstring
  This is the thread id of the trace, which groups traces in the same thread into a conversation.
- testCaseIdstring
  This is the test case id of the trace, which is only set if the trace was created in a testing environment.
- userIdstring
  This is the user id you provided for this trace.
- projectIdstring
  This is the id of the project where the trace lives.
- metricCollectionNamestring
  This is the name of the metric collection assigned to evaluate the trace.
- retrievalContextlist of strings
  This is the retrieval context associated with the trace, to be used for evaluations.
- contextlist of strings
  This is the ideal retrieval context associated with the trace, to be used for evaluations.
- expectedOutputlist of objects
  This is the expected output associated with the trace, to be used for evaluations.
  Show 5 propertiesHide 5 properties
  - namestring
    This is the name of the tool.
  - descriptionstring
    This is the description of the tool.
  - inputParametersobject
    This is the input parameters that are passed to the tool.
  - outputstring
    This is the output of the tool.
  - reasoningstring
    This is the reasoning your LLM provided for the tool call.
- expectedToolslist of objects
  This is the list of expected tools associated with the trace, to be used for evaluations.
  Show 5 propertiesHide 5 properties
  - namestring
    This is the name of the tool.
  - descriptionstring
    This is the description of the tool.
  - inputParametersobject
    This is the input parameters that are passed to the tool.
  - outputstring
    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 list of metrics data associated with the trace after running evaluations.
  Show 21 propertiesHide 21 properties
  - idstring
    The unique identifier of the metrics data entry.
  - projectIdstring
    The project this metric data belongs to.
  - traceUuidstring
    The UUID of the trace this metric data is associated with, if any.
  - spanUuidstring
    The UUID of the span this metric data is associated with, if any.
  - testCaseIdstring
    The ID of the test case this metric data is associated with, if any.
  - testRunIdstring
    The ID of the test run this metric data is associated with, if any.
  - threadIdstring
    The ID of the thread this metric data is associated with, if any.
  - namestring
    The name of the metric.
  - multiTurnboolean
    Whether this metric was evaluated on a multi-turn conversation.
  - scorenumber
    The final metric score.
  - reasonstring
    The reason for the metric score, generated by the evaluation model at evaluation time.
  - successboolean
    Whether the metric score is above the threshold.
  - createdAtstring
    The time the metric data was created.
  - evaluatedAtstring
    The time the metric was evaluated.
  - thresholdnumber
    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.
  - evaluationModelstring
    The evaluation model used to run the evaluation.
  - errorstring
    The error message if the evaluation failed.
  - evaluationCostnumber
    The cost of running the evaluation.
  - verboseLogsstring
    The verbose logs of the evaluation, which breaks down the metric score calculation into individual steps.
- annotationobject
  This is the text annotation for the trace.
  Show 14 propertiesHide 14 properties
  - idstring
    This is the id of the annotation generated by Confident AI, not to be confused with the alias you supplied or version number.
  - 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
    THUMBS_RATING
    FIVE_STAR_RATING
  - namestring
    The name of the annotation.
  - expectedOutcomestring
    This is the annotated expected outcome, for conversation annotations.
  - expectedOutputstring
    This is the annotated expected output, for span and trace annotations.
  - explanationstring
    This is the explanation for the annotation.
  - createdAtstring
    The timestamp when the annotation was created.
  - traceUuidstring
    The UUID of the trace associated with this annotation, if applicable.
  - spanUuidstring
    The UUID of the span associated with this annotation, if applicable.
  - threadIdstring
    The ID of the thread associated with this annotation, if applicable.
  - testCaseIdstring
    The ID of the test case associated with this annotation, if applicable.
  - userobject
    The user who created this annotation.
    Show 4 propertiesHide 4 properties
    idstring
    The id of the user.
    emailstring
    The email address of the user.
    namestring
    The name of the user.
    imagestring
    The image of the user.
  - userEmailstring
    The email address of the user created this annotation. The field is being deprecated. Please use user.email instead.
- tagslist of strings
  This is the list of tags associated with the trace, which is useful for grouping and filtering for traces.
- spanslist of objects
  This is the list of spans in the trace.
  Show 37 propertiesHide 37 properties
  - idstring
    This is the id of the span generated by Confident AI, not to be confused with the uuid of the span.
  - uuidstring
    This is the uuid of the span, not to be confused with the span id.
  - namestring
    This is the name of the span.
  - inputany
    This is the input to the span.
  - outputany
    This is the output of the span.
  - errorstring
    This is the error string that caused the span to fail, if an error occurred.
  - parentUuidstring
    This is the uuid of the parent span, if any.
  - startTimestring
    This is the time the span started.
  - endTimestring
    This is the time the span ended.
  - traceUuidstring
    This is the uuid of the trace containing the span.
  - agentHandoffslist of unknown
    This is the list of agent handoffs associated with an agent span.
  - availableToolslist of unknown
    This is the list of available tools associated with an agent span.
  - chunkSizeinteger
    This is the chunk size of each retrieved context for a retriever span.
  - costPerInputTokennumber
    This is the cost per input token of the LLM model for an LLM span.
  - costPerOutputTokennumber
    This is the cost per output token of the LLM model for an LLM span.
  - descriptionstring
    This is a description if the span is a tool span.
  - embedderstring
    This is the embedder model used in a retriever span.
  - inputTokenCostnumber
    This is the total cost of the input tokens passed to the LLM model in an LLM span.
  - inputTokenCountinteger
    This is the total number of input tokens passed to the LLM model in an LLM span.
  - modelstring
    This is the LLM model used in an LLM span.
  - providerstring
    This is the LLM provider used in an LLM span.
  - integrationstring
    This is the integration associated with the span.
  - outputTokenCostnumber
    This is the total cost of the output tokens generated by the LLM model in an LLM span.
  - outputTokenCountinteger
    This is the total number of output tokens generated by the LLM model in an LLM span.
  - statusenum
    This is the error status of the span.
    Show 3 enum valuesHide 3 enum values
    SUCCESS
    FAILED
    PENDING
  - topKinteger
    This is the top K chunks retrieved from your knowledge base.
  - typestring
    This is the type of the span.
  - metricCollectionNamestring
    This is the name of the metric collection to evaluate the span.
  - retrievalContextlist of strings
    This is the retrieval context of your span, which is to be used for evaluation.
  - contextlist of strings
    This is the ideal retrieval context of your span, which is to be used for evaluation.
  - expectedOutputstring
    This is the expected output of your span, which is the ideal actual output and to be used for evaluation.
  - toolsCalledlist of objects
    This is the tools called by your span, which is to be used for evaluation.
    Show 5 propertiesHide 5 properties
    namestring
    This is the name of the tool.
    descriptionstring
    This is the description of the tool.
    inputParametersobject
    This is the input parameters that are passed to the tool.
    outputstring
    This is the output of the tool.
    reasoningstring
    This is the reasoning your LLM provided for the tool call.
  - expectedToolslist of objects
    This is the expected tools to be called by the span, which is to be used for evaluation.
    Show 5 propertiesHide 5 properties
    namestring
    This is the name of the tool.
    descriptionstring
    This is the description of the tool.
    inputParametersobject
    This is the input parameters that are passed to the tool.
    outputstring
    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 metrics data entry.
    projectIdstring
    The project this metric data belongs to.
    traceUuidstring
    The UUID of the trace this metric data is associated with, if any.
    spanUuidstring
    The UUID of the span this metric data is associated with, if any.
    testCaseIdstring
    The ID of the test case this metric data is associated with, if any.
    testRunIdstring
    The ID of the test run this metric data is associated with, if any.
    threadIdstring
    The ID of the thread this metric data is associated with, if any.
    namestring
    The name of the metric.
    multiTurnboolean
    Whether this metric was evaluated on a multi-turn conversation.
    scorenumber
    The final metric score.
    reasonstring
    The reason for the metric score, generated by the evaluation model at evaluation time.
    successboolean
    Whether the metric score is above the threshold.
    createdAtstring
    The time the metric data was created.
    evaluatedAtstring
    The time the metric was evaluated.
    thresholdnumber
    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.
    evaluationModelstring
    The evaluation model used to run the evaluation.
    errorstring
    The error message if the evaluation failed.
    evaluationCostnumber
    The cost of running the evaluation.
    verboseLogsstring
    The verbose logs of the evaluation, which breaks down the metric score calculation into individual steps.
  - annotationobject
    This is the text annotation for the span.
    Show 14 propertiesHide 14 properties
    idstring
    This is the id of the annotation generated by Confident AI, not to be confused with the alias you supplied or version number.
    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
    THUMBS_RATING
    FIVE_STAR_RATING
    namestring
    The name of the annotation.
    expectedOutcomestring
    This is the annotated expected outcome, for conversation annotations.
    expectedOutputstring
    This is the annotated expected output, for span and trace annotations.
    explanationstring
    This is the explanation for the annotation.
    createdAtstring
    The timestamp when the annotation was created.
    traceUuidstring
    The UUID of the trace associated with this annotation, if applicable.
    spanUuidstring
    The UUID of the span associated with this annotation, if applicable.
    threadIdstring
    The ID of the thread associated with this annotation, if applicable.
    testCaseIdstring
    The ID of the test case associated with this annotation, if applicable.
    userobject
    The user who created this annotation.
    Show 4 propertiesHide 4 properties
    idstring
    The id of the user.
    emailstring
    The email address of the user.
    namestring
    The name of the user.
    imagestring
    The image of the user.
    userEmailstring
    The email address of the user created this annotation. The field is being deprecated. Please use user.email instead.
  - environmentenum
    This is the environment where your span was posted, which helps with separating and debugging spans from different environments on the Confident AI platform.
    Show 4 enum valuesHide 4 enum values
    production
    development
    staging
    testing
  - metadataobject
    This is any additional metadata associated with the span.
deprecatedboolean
This is true if this endpoint is deprecated.

Built byConfident AI