Skip to main content
POST
Query spans
Returns a list of span summaries matching the provided filters. All filters are optional. If min_start_datetime is not provided, the query defaults to the last 15 minutes. Start with run_id when investigating a specific agent run. Use limit and offset to paginate results and order to sort by start time. To retrieve the full record for a specific span, use the retrieve span endpoint.

Authorizations

Authorization
string
header
required

Your Seekr API key, sent in the Authorization header with no 'Bearer' prefix.

Headers

x-team-id
string | null

ID of the team to use for the request. If omitted, the request uses your personal workspace.

Body

application/json

Object to contain request data for retrieving spans in bulk.

min_start_datetime
string<date-time> | null

Inclusive lower bound for span start times, in ISO 8601 format. Defaults to 15 minutes before the query when omitted.

max_start_datetime
string<date-time> | null

Inclusive upper bound for span start times, in ISO 8601 format. Omit to leave the upper bound open.

agent_id
string | null

ID of the agent.

run_id
string | null

ID of the run.

trace_id
string | null

Return only spans belonging to this trace.

thread_id
string | null

ID of the thread.

group
string | null

Return only spans with this run group label.

Required string length: 1 - 32768
metadata
Metadata · object | null

Match all supplied run metadata key-value pairs. Keys must contain only letters, digits, or underscores and must exist on an accessible span.

limit
integer
default:100

Maximum number of results to return.

Required range: x >= 0
order
enum<string>
default:desc

Options for order query param in list endpoints.

Available options:
asc,
desc
offset
integer
default:0

Number of results to skip.

Required range: x >= 0

Response

Success

run_id
string
required

ID of the run.

thread_id
string
required

ID of the thread.

agent_id
string
required

ID of the agent.

trace_id
string
required

ID of the distributed trace containing the span.

span_id
string
required

ID of this span within the trace.

span_name
string
required

Name of the operation represented by the span.

level
integer
required

Numeric severity level recorded for the span.

service_name
string
required

Name of the service that emitted the span.

start_timestamp
string<date-time>
required

Time the span started, in ISO 8601 format.

end_timestamp
string<date-time>
required

Time the span ended, in ISO 8601 format.

kind
enum<string>
required

Indicates the type of record for a logfire record.

Available options:
span,
pending_span,
log,
span_event
message
string
required

Human-readable message recorded for the span.

group
string | null

Group label attached to the run that produced the span.

parent_span_id
string | null

ID of the parent span, or null for a span without a recorded parent.

otel_scope_name
string | null

Name of the OpenTelemetry instrumentation scope that emitted the span.

is_exception
boolean | null

Whether an exception was recorded on the span.

exception_type
string | null

Type of the exception recorded on the span, when available.

gen_ai_operation_name
string | null

Name of the generative AI operation recorded on the span.

gen_ai_request_model
string | null

Model identifier recorded in the generative AI request.

gen_ai_response_model
string | null

Model identifier recorded in the generative AI response.

gen_ai_system
string | null

Generative AI provider or system recorded on the span.

gen_ai_usage_input_tokens
string | null

Input token count recorded on the span, represented as a string when available.

gen_ai_usage_output_token
string | null

Reserved output-token count. The span-summary query does not populate this field, so it returns null.

seekr_metadata
Seekr Metadata · object | null

Run metadata key-value pairs recorded on the span.

Last modified on July 31, 2026