Skip to navigation
API ReferenceObservabilityBehaviors

List spans where a behavior fired

Lists the spans in a time range where one behavior fired, newest first. Use the span IDs with Get a span for the full request and response.

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.

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.

pageintegerOptional>=1Defaults to 1
Page number, starting at 1.
page_sizeintegerOptional1-1000Defaults to 100
Spans per page. Values above 1000 are capped at 1000.

Response

A page of spans.
behaviorstring

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

pageinteger
page_sizeinteger
logslist of objects

Spans where the behavior fired, newest first. Fewer than page_size items means this is the last page. Empty when the behavior is turned off.

Errors

400
Bad Request Error
403
Forbidden Error
429
Too Many Requests Error