API ReferenceSpans

Get spans summary

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.

OR
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