List spans where a behavior fired
https://api.respan.ai/api/pulses/behaviors/logs/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.
Servers
https://api.respan.ai: Respan API Server
Authentication
RespanApiKey
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.
HTTP scheme: bearer; format: Respan API key.
Authorization: Bearer $RESPAN_API_KEYRequest body
A request body is required.
application/json
$ object Required body
#/components/schemas/BehaviorSpansRequestbehavior string Required in parentrefusal) or a custom behavior’s id.Example:
"refusal"start_time string OptionalFormat:
date-timeExample:
"2026-09-24T00:00:00Z"end_time string OptionalFormat:
date-timeExample:
"2026-10-01T00:00:00Z"environment string Optionalprod or test. Omit it to include every environment.Example:
"prod"page integer OptionalDefault:
1Minimum:
1Example:
1page_size integer OptionalDefault:
100Minimum:
1Maximum:
1000Example:
50OpenAPI request schema
{
"$ref": "#/components/schemas/BehaviorSpansRequest"
}Example
{
"behavior": "refusal",
"start_time": "2026-09-30T00:00:00Z",
"end_time": "2026-10-01T00:00:00Z",
"page": 1,
"page_size": 50
}Responses
200
A page of spans.
application/json
$ object Body
#/components/schemas/BehaviorSpansbehavior string Required in parentrefusal) or a custom behavior’s id.Example:
"refusal"page integer Required in parent1page_size integer Required in parent50logs array<object> Required in parent
page_size items means this is the last page. Empty when the behavior is turned off.logs[] object Array item
#/components/schemas/BehaviorSpanlogs[].unique_id string Required in parentGET /api/request-logs/{unique_id}/).Example:
"c3a1f8e2b9d04e6f8a7b5c4d3e2f1a0b"logs[].model string Required in parentExample:
"gpt-4o-mini"logs[].status string Required in parentsuccess or failed.Example:
"success"logs[].environment string Required in parentExample:
"prod"logs[].timestamp string Required in parentExample:
"2026-09-30T14:22:05.381204"OpenAPI response schema
{
"$ref": "#/components/schemas/BehaviorSpans"
}Example
{
"behavior": "refusal",
"page": 1,
"page_size": 50,
"logs": [
{
"unique_id": "c3a1f8e2b9d04e6f8a7b5c4d3e2f1a0b",
"model": "gpt-4o-mini",
"status": "success",
"environment": "prod",
"timestamp": "2026-09-30T14:22:05.381204"
}
]
}400
behavior is missing.
application/json
$ object Body
error string Required in parentOpenAPI response schema
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
}Example
{
"error": "'behavior' is required"
}403
Forbidden: the API key is missing, invalid or expired; the key doesn’t grant logs:read (Read access does); behaviors are turned off for the organization.
application/json
$ object Body
detail string Required in parentOpenAPI response schema
{
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
}Missing or invalid API key
{
"detail": "Your API key is invalid or expired, please check your API key in the platform settings."
}Key lacks the permission
{
"detail": "This API key does not have the 'logs:read' permission."
}Behaviors are off for the organization
{
"detail": "Span Behaviors is not enabled for this organization."
}429
Rate limited. This endpoint allows 60 requests per minute per organization.
application/json
$ object Body
detail string Required in parentOpenAPI response schema
{
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
}Example
{
"detail": "Request was throttled."
}OpenAPI source
The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.
OpenAPI operation
{
"summary": "List spans where a behavior fired",
"operationId": "listBehaviorSpans",
"tags": [
"Behaviors"
],
"description": "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.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BehaviorSpansRequest"
},
"example": {
"behavior": "refusal",
"start_time": "2026-09-30T00:00:00Z",
"end_time": "2026-10-01T00:00:00Z",
"page": 1,
"page_size": 50
}
}
}
},
"responses": {
"200": {
"description": "A page of spans.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BehaviorSpans"
},
"example": {
"behavior": "refusal",
"page": 1,
"page_size": 50,
"logs": [
{
"unique_id": "c3a1f8e2b9d04e6f8a7b5c4d3e2f1a0b",
"model": "gpt-4o-mini",
"status": "success",
"environment": "prod",
"timestamp": "2026-09-30T14:22:05.381204"
}
]
}
}
}
},
"400": {
"description": "`behavior` is missing.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "'behavior' is required"
}
}
}
},
"403": {
"description": "Forbidden: the API key is missing, invalid or expired; the key doesn't grant `logs:read` (Read access does); behaviors are turned off for the organization.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
},
"examples": {
"invalidKey": {
"summary": "Missing or invalid API key",
"value": {
"detail": "Your API key is invalid or expired, please check your API key in the platform settings."
}
},
"missingPermission": {
"summary": "Key lacks the permission",
"value": {
"detail": "This API key does not have the 'logs:read' permission."
}
},
"behaviorsOff": {
"summary": "Behaviors are off for the organization",
"value": {
"detail": "Span Behaviors is not enabled for this organization."
}
}
}
}
}
},
"429": {
"description": "Rate limited. This endpoint allows 60 requests per minute per organization.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
},
"example": {
"detail": "Request was throttled."
}
}
}
}
},
"security": [
{
"RespanApiKey": []
}
]
}OpenAPI path metadata
{}Referenced OpenAPI components
{
"schemas": {
"BehaviorSpan": {
"type": "object",
"required": [
"unique_id",
"model",
"status",
"environment",
"timestamp"
],
"properties": {
"unique_id": {
"type": "string",
"description": "Span ID. Pass it to Get a span (`GET /api/request-logs/{unique_id}/`).",
"example": "c3a1f8e2b9d04e6f8a7b5c4d3e2f1a0b"
},
"model": {
"type": "string",
"description": "Model the span used.",
"example": "gpt-4o-mini"
},
"status": {
"type": "string",
"description": "Span status, such as `success` or `failed`.",
"example": "success"
},
"environment": {
"type": "string",
"description": "Span environment.",
"example": "prod"
},
"timestamp": {
"type": "string",
"description": "Span timestamp. UTC, ISO 8601 without a timezone suffix.",
"example": "2026-09-30T14:22:05.381204"
}
}
},
"BehaviorSpans": {
"type": "object",
"required": [
"behavior",
"page",
"page_size",
"logs"
],
"properties": {
"behavior": {
"type": "string",
"description": "Behavior key: a built-in behavior's name (for example `refusal`) or a custom behavior's `id`.",
"example": "refusal"
},
"page": {
"type": "integer",
"example": 1
},
"page_size": {
"type": "integer",
"example": 50
},
"logs": {
"type": "array",
"description": "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.",
"items": {
"$ref": "#/components/schemas/BehaviorSpan"
}
}
}
},
"BehaviorSpansRequest": {
"type": "object",
"required": [
"behavior"
],
"properties": {
"behavior": {
"type": "string",
"description": "Behavior key: a built-in behavior's name (for example `refusal`) or a custom behavior's `id`.",
"example": "refusal"
},
"start_time": {
"type": "string",
"format": "date-time",
"description": "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.",
"example": "2026-09-24T00:00:00Z"
},
"end_time": {
"type": "string",
"format": "date-time",
"description": "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.",
"example": "2026-10-01T00:00:00Z"
},
"environment": {
"type": "string",
"description": "Only count spans from this environment, such as `prod` or `test`. Omit it to include every environment.",
"example": "prod"
},
"page": {
"type": "integer",
"minimum": 1,
"default": 1,
"description": "Page number, starting at 1.",
"example": 1
},
"page_size": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"default": 100,
"description": "Spans per page. Values above 1000 are capped at 1000.",
"example": 50
}
}
}
},
"securitySchemes": {
"RespanApiKey": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "Respan API key",
"description": "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.",
"x-fern-bearer": {
"name": "respanApiKey",
"env": "RESPAN_API_KEY"
}
}
}
}