List Spans

GEThttps://api.confident-ai.com/v1/spans

Retrieves a list of spans from your Confident AI project.

GET/v1/spans

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

200

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

Headers

CONFIDENT_API_KEYstringRequired
The API key of your Confident AI project.

Query parameters

pageinteger
This specifies the page number of the threads to return. Defaulted to 1.
pageSizeinteger
This specifies the maximum number of threads per page. Defaulted to 25.
typeenum
Filter by the specific type of span.
traceUuidstring
Filter spans that belong to a specific trace UUID.
namestring
Filter spans by their exact name.
hasErrorboolean
Filter for spans that either failed (true) or succeeded (false).
modelstring
Filter LLM spans by the model used (e.g., 'gpt-4').
promptAliasstring
This filters the spans by the prompt alias used.
promptCommitHashstring
This filters the spans by the exact prompt commit hash used.
promptVersionstring
This filters the spans by the prompt version used.
promptLabelstring
This filters the spans by the prompt label used.
embedderstring
Filter retriever spans by the embedder model used.
topKinteger
Filter retriever spans by the topK value.
chunkSizeinteger
Filter retriever spans by the chunk size.
environmentstring
This filters the threads by the environment where the thread was created, and returns threads from all environments if not specified.
startstring
This filters for threads created after the specified start datetime. Defaulted to 30 days ago.
endstring
This filters for threads created before the specified end datetime. Defaulted to the current time.
sortByenum
This determines the field to sort by. Defaulted to lastActivity.
ascendingenum
This determines if the field specified in sortBy should be in ascending order. Defaults to false.

Response

successboolean
This is true if the spans were successfully retrieved.
dataobject
The payload containing the paginated spans and total count.
Show 2 propertiesHide 2 properties
- spanslist of objects
  The list of spans for the current page.
  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.
- totalSpansinteger
  The total number of spans matching the query across all pages.
deprecatedboolean
This is true if this endpoint is deprecated.

Built byConfident AI