Get spans summary | Respan Docs

Get aggregated statistics for spans/log rows in a time range. start_time, end_time, and environment are URL query parameters. Additional filters must be sent in the JSON body under filters; fields such as log_type are not read as summary query parameters. When filters is omitted or empty, the backend may use the pre-aggregated summary path; when filters is non-empty, it queries raw logs using the same filter object shape as List spans.

Get aggregated statistics for spans/log rows in a time range. `start_time`, `end_time`, and `environment` are URL query parameters. Additional filters must be sent in the JSON body under `filters`; fields such as `log_type` are not read as summary query parameters. When `filters` is omitted or empty, the backend may use the pre-aggregated summary path; when `filters` is non-empty, it queries raw logs using the same filter object shape as List spans.

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

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:

Request

This endpoint expects an object.

filtersobjectOptional

Filter criteria. See Filters API Reference for operator syntax.

Response

Summary statistics for matching spans.

number_of_requestsinteger

Total number of matching spans/log rows.

total_costdouble

Total cost in USD for all matching spans/log rows.

total_tokensinteger

Total tokens across all matching spans/log rows.

total_prompt_tokensinteger

Total prompt/input tokens.

total_completion_tokensinteger

Total completion/output tokens.

avg_latencydouble

Average latency in seconds.

avg_tpsdouble

Average tokens per second.

avg_ttftdouble

Average time to first token in seconds.

scoresmap from strings to any

Aggregated score summaries grouped by evaluator ID.

Errors

400

Bad Request Error

401

Unauthorized Error

413

Content Too Large Error

429

Too Many Requests Error

500

Internal Server Error