API ReferenceDashboard

List metrics broken down by dimension

Return time-series metrics broken down by a dimension. Span scope supports full filtering and dimensions; trace scope accepts no body filters and only customer or organization-key breakdowns; thread scope accepts neither filters nor a breakdown dimension. Each requested metric is a top-level key whose value is an array of time buckets.

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

summary_typeenumOptionalDefaults to all

Preset time range. Use this or explicit start_time / end_time.

datedateOptional

Base date used with summary_type presets.

start_timedatetimeOptional
Optional explicit ISO start time.
end_timedatetimeOptional
Optional explicit ISO end time.
time_tickenumOptionalDefaults to hour

Bucket granularity for time-series responses.

Allowed values:
timezone_offsetdoubleOptionalDefaults to 0
Timezone offset, in hours, used when resolving preset ranges.
breakdown_byenumOptionalDefaults to model
Dimension to break the time series down by.
scopeenumOptionalDefaults to span
Aggregation unit.
Allowed values:

Request

Optional POST body. Only filters is read from the body; time range controls are URL query parameters.

filtersobjectOptional

Filter criteria. See Filters API Reference for operator syntax.

metrics_to_aggregatelist of enumsOptional

Metrics to return. Supported values depend on scope; when omitted the API returns number of requests, total cost, and total tokens.

Response

Metric-keyed time-series breakdown.

list of objects
OR
map from strings to strings

Errors

400
Bad Request Error
413
Content Too Large Error