Get behavior counts by dimension

Splits the spans where one behavior fired by a span field, such as model or customer. The signals panel uses it for its “By model” and “By customer” splits.

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.

Request

This endpoint expects an object.

behaviorstringRequired

Behavior key: a built-in behavior's name (for example refusal) or a custom behavior's id.

group_byenumRequired

Span field to split by. status is the span status, such as success or failed.

start_timedatetimeOptional

Start of the range, ISO 8601. A time without an offset is read as UTC. Defaults to 7 days ago, which is also used if the value can't be parsed.

end_timedatetimeOptional

End of the range, ISO 8601. A time without an offset is read as UTC. Defaults to now, which is also used if the value can't be parsed.

environmentstringOptional

Only count spans from this environment, such as prod or test. Omit it to include every environment.

limitintegerOptional1-100Defaults to 100

Maximum groups to return. Values above 100 are capped at 100.

Response

Fired counts per group.

behaviorstring

Behavior key: a built-in behavior's name (for example refusal) or a custom behavior's id.

group_byenum

groupslist of objects

Groups ordered by fired_spans, highest first. Empty when the behavior is turned off.

Errors

400

Bad Request Error

403

Forbidden Error

429

Too Many Requests Error