List spans | Respan Docs

Retrieve spans matching the specified filters with pagination. Supports filtering by any span field, URL-based quick filters, and sorting by evaluator scores. See Filters API Reference for full filter syntax. Metadata keys beginning with _ are reserved for platform use and are omitted from customer-facing span and trace responses, so they do not round-trip through read APIs.

Retrieve spans matching the specified filters with pagination. Supports filtering by any span field, URL-based quick filters, and sorting by evaluator scores. See [Filters API Reference](/docs/apis/reference/filters-api-reference) for full filter syntax. Metadata keys beginning with `_` are reserved for platform use and are omitted from customer-facing span and trace responses, so they do not round-trip through read APIs.

Authentication

AuthorizationBearer

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

AuthorizationBearer

Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.

Query parameters

pageintegerOptionalDefaults to 1

Page number.

page_sizeintegerOptional<=1000Defaults to 50

Results per page (max 1000).

sort_bystringOptionalDefaults to -timestamp

Field to sort by. Prefix - for descending.

start_timedatetimeOptional

Start of time range (ISO 8601).

end_timedatetimeOptional

End of time range (ISO 8601).

environmentenumOptional

Filter by environment (prod or test).

Allowed values:

log_typeenumOptional

Filter by span/log type. Use values like chat, completion, or response to focus on model-inference spans; omitting this can also return non-chat span/log rows such as legacy text logs.

include_fieldsstringOptional

Comma-separated list of fields to include in each span. Reduces response size.

Request

This endpoint expects an object.

filtersobjectOptional

Filter criteria. See Filters API Reference for operator syntax.

Response

Successful response for List spans

countinteger

Total number of results

resultslist of objects

Array of results for the current page

nextstring or nullOptional

URL for the next page of results

previousstring or nullOptional

URL for the previous page of results

Errors

400

Bad Request Error

401

Unauthorized Error

413

Content Too Large Error

429

Too Many Requests Error

500

Internal Server Error