Skip to main content
GET
/
api
/
v2
/
warehouse
/
spans
Get Spans
curl --request GET \
  --url https://app.traceloop.com/api/v2/warehouse/spans \
  --header 'Authorization: Bearer <token>'
{
  "organizationId": "<string>",
  "environment": "<string>",
  "timestamp": {},
  "traceId": "<string>",
  "spanId": "<string>",
  "parentSpanId": "<string>",
  "traceState": "<string>",
  "spanName": "<string>",
  "spanKind": "<string>",
  "serviceName": "<string>",
  "resourceAttributes": {},
  "scopeName": "<string>",
  "scopeVersion": "<string>",
  "spanAttributes": {},
  "workflowName": "<string>",
  "duration": {},
  "statusCode": "<string>",
  "statusMessage": "<string>",
  "eventsName": [
    "<string>"
  ],
  "eventsAttributes": [
    {}
  ],
  "prompts": {},
  "completions": {},
  "input": "<string>",
  "output": "<string>"
}
Retrieve spans from the data warehouse with flexible filtering and pagination options. This endpoint allows you to query trace data based on various criteria including time ranges, environments, workflows, attributes, and more.

​
Request Parameters

​
env
string
The environment name.
​
environments
string[]
List of environment names to filter by.
​
envProjectIDs
string[]
List of environment project IDs to filter by.
​
fromTimestampSec
int64
required
Start time in Unix seconds timestamp.
​
toTimestampSec
int64
required
End time in Unix seconds timestamp.
​
workflowName
string
Filter spans by workflow name.
​
attributes
map[string]string
Key-value pairs of attributes to filter by.
​
spanName
string
Filter spans by span name.
​
sortOrder
string
Sort order for results. Accepted values: asc or desc.
​
sortBy
string
Field to sort by (e.g., timestamp, duration).
​
cursor
int64
Deprecated: Use compositeCursor instead. Pagination cursor for fetching the next set of results.
​
compositeCursor
CompositeCursor
Advanced pagination cursor for fetching the next set of results.
​
limit
int
Maximum number of spans to return.
​
filters
FilterCondition[]
Array of filter conditions to apply to the query.
​
logicalOperator
string
Logical operator to apply between filter conditions. Accepted values: AND or OR.

​
Response

Returns an array of Span objects:
​
organizationId
string
The organization ID associated with the span.
​
environment
string
The environment where the span was captured.
​
timestamp
timestamp
The timestamp when the span was created.
​
traceId
string
The unique trace identifier.
​
spanId
string
The unique span identifier.
​
parentSpanId
string
The parent span identifier.
​
traceState
string
The trace state information.
​
spanName
string
The name of the span.
​
spanKind
string
The kind of span (e.g., CLIENT, SERVER, INTERNAL).
​
serviceName
string
The name of the service that generated the span.
​
resourceAttributes
map
Key-value pairs of resource attributes.
​
scopeName
string
The instrumentation scope name.
​
scopeVersion
string
The instrumentation scope version.
​
spanAttributes
map
Key-value pairs of span attributes.
​
workflowName
string
The workflow name associated with the span.
​
duration
int64
The duration of the span in nanoseconds.
​
statusCode
string
The status code of the span (e.g., OK, ERROR).
​
statusMessage
string
The status message providing additional context.
​
eventsName
string[]
Array of event names associated with the span.
​
eventsAttributes
map[]
Array of event attributes as key-value pairs.
​
prompts
map
Prompt data associated with the span.
​
completions
map
Completion data associated with the span.
​
input
string
Input data for the span.
​
output
string
Output data for the span.

​
Example Response

[
  {
    "organizationId": "org_123",
    "environment": "production",
    "timestamp": "2025-11-01T12:00:00Z",
    "traceId": "trace_abc123",
    "spanId": "span_def456",
    "parentSpanId": "span_parent_789",
    "traceState": "",
    "spanName": "llm.completion",
    "spanKind": "CLIENT",
    "serviceName": "chat-service",
    "resourceAttributes": {
      "service.version": "1.0.0"
    },
    "scopeName": "opentelemetry",
    "scopeVersion": "1.0.0",
    "spanAttributes": {
      "llm.model": "gpt-4",
      "llm.provider": "openai"
    },
    "workflowName": "chat-workflow",
    "duration": 1500000000,
    "statusCode": "OK",
    "statusMessage": "",
    "eventsName": ["start", "end"],
    "eventsAttributes": [
      {
        "event.type": "start"
      },
      {
        "event.type": "end"
      }
    ],
    "prompts": {
      "role": "user",
      "content": "Hello, how are you?"
    },
    "completions": {
      "role": "assistant",
      "content": "I'm doing well, thank you!"
    },
    "input": "Hello, how are you?",
    "output": "I'm doing well, thank you!"
  }
]