Get Span

GEThttps://api.confident-ai.com/v2/spans/{spanUuid}

Retrieves a span by uuid from your Confident AI project, with its full input and output, evaluation fields, results and annotations.

GET/v2/spans/{spanUuid}

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

200

{
  "success": true,
  "data": {
    "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
        }
      }
    ]
  },
  "deprecated": false
}

Headers

CONFIDENT_API_KEYstringRequired
The API key of your Confident AI project.

Path parameters

spanUuidstringRequired
The unique identifier of the span.

Response

Get Span succeeded.

successboolean
Indicates if the request was successful.
dataobject
A span with its full input and output, evaluation fields, results and annotations.
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.
deprecatedboolean
Indicates if this endpoint is deprecated.

Built byConfident AI