API ReferenceExperiments

Filter experiment trace summary

Get aggregate workflow metrics and evaluator score summaries for traces matching a POST filter payload.

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, OpenAI or Azure OpenAI provider credentials go in Settings -> Providers or the request body credential_override field, not in this auth field.

OR
AuthorizationBearer

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

Path parameters

experiment_idstringRequired

Experiment ID returned as id in experiment responses.

Query parameters

start_timedatetimeOptional
Filter results at or after this timestamp.
end_timedatetimeOptional
Filter results before this timestamp.

Request

This endpoint expects an object.
filtersobjectOptional
Filter criteria using the standard Respan filter format.
is_exportingbooleanOptionalDefaults to false
Reserved for dashboard exports.

Response

Experiment trace summary.
number_of_requestsinteger
Total number of traces matching the filters.
total_costdouble
Sum of request costs in USD.
total_tokensinteger
scoresmap from strings to objects

Scores keyed by evaluator ID or slug. Each value includes evaluator metadata and the score value field matching score_value_type.

total_prompt_tokensinteger
total_completion_tokensinteger
avg_latencydouble
Average latency in seconds.
avg_tpsdouble
Average output tokens per second.
avg_ttftdouble
Average time to first token in seconds.

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error