Skip to navigation
API ReferenceObservabilitySpans

List span groups with filters

Group spans using the same query parameters as GET and optional standard Respan filters in the request body.

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.

OR
AuthorizationBearer

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

Query parameters

group_byenumOptionalDefaults to model

Grouping dimension. trace and thread use entity rollups.

sort_bystringOptionalDefaults to number_of_requests
start_timedatetimeOptional
end_timedatetimeOptional
environmentstringOptional
pageintegerOptional>=1
page_sizeintegerOptional1-1000

Request

This endpoint expects an object.
filtersmap from strings to anyOptional

Narrows what’s grouped.

Each key is a field to filter on, and each value is a condition: {"<field>": {"operator": "<operator>", "value": [...]}}. Each span, trace or thread must match every condition. To set two conditions on one field, such as a range, pass a list of conditions.

Operators: "" (equals, the default), not, in, not_in, lt, lte, gt, gte, contains, not_contains, icontains (ignores case), startswith, not_startswith, endswith, not_endswith, empty, not_empty. Put values in a list: "" and in match any of the listed values, and not and not_in match none of them. Other operators take one value; for empty and not_empty, send [""].

Fields depend on group_by:

  • trace: trace fields such as total_cost, error_count, span_count, customer_identifier and metadata__<key>, plus span fields such as model, which match a trace when any of its spans matches.
  • thread: thread fields such as thread_identifier, customer_identifier, number_of_requests, total_cost and total_tokens.
  • Any other value: span columns, such as model, provider_id, deployment_name, customer_identifier, custom_identifier, organization_key_id, prompt_id, log_type, status_code, cost, latency, prompt_tokens, completion_tokens and total_request_tokens, plus metadata__<key> (values are strings). Aliases such as total_tokens don’t work.

Example:

{
  "status_code": {"operator": "not", "value": [200]},
  "metadata__plan": {"operator": "", "value": ["pro"]}
}

Response

Paginated groups and aggregate metrics.
countinteger

Number of results on this page, not the total. Request pages until next is null to get every result.

resultslist of objects
nextstring or nullOptional
previousstring or nullOptional
current_filtersmap from strings to anyOptional
filters_datamap from strings to anyOptional

Errors

400
Bad Request Error
403
Forbidden Error