For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Trust CenterStatusSupportGet a demoPlatform
DocumentationEvals API ReferenceIntegrations & OTELPlatform SettingsSelf-HostingGuidesChangelog
DocumentationEvals API ReferenceIntegrations & OTELPlatform SettingsSelf-HostingGuidesChangelog
  • Get Started
    • Introduction
    • Quickstart
    • Authentication
    • Data Models
    • API Conventions
  • Data Models
      • GETList Spans
      • GETRetrieve Span
  • Evals
  • Legacy
LogoLogo
Trust CenterStatusSupportGet a demoPlatform
Data ModelsSpans

List Spans

GET
https://api.confident-ai.com/v1/spans
GET
/v1/spans
$curl https://api.confident-ai.com/v1/spans \
>     -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>"
200Retrieved
1{
2  "success": true,
3  "data": {
4    "spans": [
5      {
6        "id": "SPAN-ID",
7        "uuid": "SPAN-UUID",
8        "name": "Span Name",
9        "startTime": "2025-01-15T10:30:00Z",
10        "endTime": "2025-01-15T10:30:05Z",
11        "traceUuid": "TRACE-UUID",
12        "status": "SUCCESS",
13        "type": "LLM",
14        "model": "gpt-4o",
15        "provider": "OpenAI",
16        "integration": "LangChain"
17      }
18    ],
19    "totalSpans": 1
20  },
21  "deprecated": false
22}
Retrieves a list of spans from your Confident AI project.
Was this page helpful?
Previous

Retrieve Span

Next
Built with

Headers

CONFIDENT_API_KEYstringRequired
The API key of your Confident AI project.

Query parameters

pageintegerOptional>=1
This specifies the page number of the threads to return. Defaulted to 1.
pageSizeintegerOptional>=1
This specifies the maximum number of threads per page. Defaulted to 25.
typeenumOptional
Filter by the specific type of span.
Allowed values:
traceUuidstringOptionalformat: "uuid"
Filter spans that belong to a specific trace UUID.
namestringOptional
Filter spans by their exact name.
hasErrorbooleanOptional

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

modelstringOptional

Filter LLM spans by the model used (e.g., ‘gpt-4’).

promptAliasstringOptional
This filters the spans by the prompt alias used.
promptCommitHashstringOptional
This filters the spans by the exact prompt commit hash used.
promptVersionstringOptional
This filters the spans by the prompt version used.
promptLabelstringOptional
This filters the spans by the prompt label used.
embedderstringOptional
Filter retriever spans by the embedder model used.
topKintegerOptional>=0
Filter retriever spans by the topK value.
chunkSizeintegerOptional>=0
Filter retriever spans by the chunk size.
environmentstringOptional
This filters the threads by the environment where the thread was created, and returns threads from all environments if not specified.
startstringOptionalformat: "date-time"
This filters for threads created after the specified start datetime. Defaulted to 30 days ago.
endstringOptionalformat: "date-time"
This filters for threads created before the specified end datetime. Defaulted to the current time.
sortByenumOptional

This determines the field to sort by. Defaulted to lastActivity.

Allowed values:
ascendingenumOptional

This determines if the field specified in sortBy should be in ascending order. Defaults to false.

Allowed values:

Response

successboolean
This is true if the spans were successfully retrieved.
dataobject
The payload containing the paginated spans and total count.
deprecatedboolean
This is true if this endpoint is deprecated.