Skip to Content

List spans where a behavior fired

POSThttps://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.

HTTP
Authorization: Bearer $RESPAN_API_KEY

Request body

A request body is required.

application/json

Field Type Requirement Description and constraints
$ object Required body
Reference: #/components/schemas/BehaviorSpansRequest
behavior string Required in parent
Behavior key: a built-in behavior’s name (for example refusal) or a custom behavior’s id.
Example: "refusal"
start_time string Optional
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.
Format: date-time
Example: "2026-09-24T00:00:00Z"
end_time string Optional
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.
Format: date-time
Example: "2026-10-01T00:00:00Z"
environment string Optional
Only count spans from this environment, such as prod or test. Omit it to include every environment.
Example: "prod"
page integer Optional
Page number, starting at 1.
Default: 1
Minimum: 1
Example: 1
page_size integer Optional
Spans per page. Values above 1000 are capped at 1000.
Default: 100
Minimum: 1
Maximum: 1000
Example: 50

OpenAPI request schema

{
  "$ref": "#/components/schemas/BehaviorSpansRequest"
}
Example
JSON
{ "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

Field Type Requirement Description and constraints
$ object Body
Reference: #/components/schemas/BehaviorSpans
behavior string Required in parent
Behavior key: a built-in behavior’s name (for example refusal) or a custom behavior’s id.
Example: "refusal"
page integer Required in parent
Example: 1
page_size integer Required in parent
Example: 50
logs array<object> Required in parent
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.
logs[] object Array item
Reference: #/components/schemas/BehaviorSpan
logs[].unique_id string Required in parent
Span ID. Pass it to Get a span (GET /api/request-logs/{unique_id}/).
Example: "c3a1f8e2b9d04e6f8a7b5c4d3e2f1a0b"
logs[].model string Required in parent
Model the span used.
Example: "gpt-4o-mini"
logs[].status string Required in parent
Span status, such as success or failed.
Example: "success"
logs[].environment string Required in parent
Span environment.
Example: "prod"
logs[].timestamp string Required in parent
Span timestamp. UTC, ISO 8601 without a timezone suffix.
Example: "2026-09-30T14:22:05.381204"

OpenAPI response schema

{
  "$ref": "#/components/schemas/BehaviorSpans"
}
Example
JSON
{ "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

Field Type Requirement Description and constraints
$ object Body
-
error string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string"
    }
  }
}
Example
JSON
{ "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

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Missing or invalid API key
JSON
{ "detail": "Your API key is invalid or expired, please check your API key in the platform settings." }
Key lacks the permission
JSON
{ "detail": "This API key does not have the 'logs:read' permission." }
Behaviors are off for the organization
JSON
{ "detail": "Span Behaviors is not enabled for this organization." }

429

Rate limited. This endpoint allows 60 requests per minute per organization.

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
JSON
{ "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"
      }
    }
  }
}