List Spans

Headers

• CONFIDENT_API_KEYstringRequired

  The API key of your Confident AI project.

Query parameters

• pageSizeintegerdefault: 25

  The number of results per page, at most 100. Defaults to 25.

• cursorstring

  This is used for pagination, and should be set to the nextCursor value returned in the previous response to get the next page of results.

• startstring

  This filters for results created at or after the specified start datetime, in ISO 8601 format. Defaults to 60 days ago.

• endstring

  This filters for results created before the specified end datetime, in ISO 8601 format. Defaults to the current time.

• ascendingenumdefault: false

  This determines if the field specified in sortBy should be in ascending order. Defaults to false, which returns the newest results first.

• sortByenumdefault: createdAt

  This determines the field to sort by. Defaults to createdAt.

• environmentenum

  This filters the spans by the environment where their trace was created, and returns spans from all environments if not specified.

• typeenum

  Filter by the specific type of span.

• traceUuidstring

  Filter spans that belong to the trace with this uuid.

• namestring

  Filter spans by their exact name.

• hasErrorenum

  Filter for spans that either failed (true) or succeeded (false).

• modelstring

  Filter LLM spans by the model used.

• promptAliasstring

  This filters the spans by the prompt alias used.

• promptVersionstring

  This filters the spans by the prompt version used.

• promptLabelstring

  This filters the spans by the prompt label used.

• promptCommitHashstring

  This filters the spans by the exact prompt commit hash used.

• embedderstring

  Filter retriever spans by the embedder model used.

• topKinteger | null

  Filter retriever spans by the topK value.

• chunkSizeinteger | null

  Filter retriever spans by the chunk size.

Response

List Spans succeeded.

• successboolean

  Indicates if the request was successful.

• dataobject

  Show 3 propertiesHide 3 properties

  • spanslist of objects

    The list of spans for the current page.

    Show 34 propertiesHide 34 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.

    • inputPreviewstring | null

      The first characters of the span's input, or null when it has none. Retrieve the span by id for the full value.

    • outputPreviewstring | null

      The first characters of the span's output, or null when it has none. Retrieve the span by id for the full value.

  • totalSpansinteger

    The total number of spans matching the query across all pages. Present on the first page only; omitted when a cursor is given.

  • nextCursorstring | null

    The value to pass as cursor to get the next page, or null when this is the last page.

• deprecatedboolean

  Indicates if this endpoint is deprecated.