---
title: "List spans where a behavior fired"
method: POST
path: "/api/pulses/behaviors/logs/"
tags: ["Behaviors"]
---

# List spans where a behavior fired

`POST /api/pulses/behaviors/logs/`

## Request

- Base URL: `https://api.respan.ai`
- URL: `https://api.respan.ai/api/pulses/behaviors/logs/`
- Auth: HTTP bearer

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.

## Request body

- BehaviorSpansRequest
  - `behavior` string, required: Behavior key: a built-in behavior's name (for example `refusal`) or a custom behavior's `id`.
  - `start_time` string, date-time: 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_time` string, date-time: 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.
  - `environment` string: Only count spans from this environment, such as `prod` or `test`. Omit it to include every environment.
  - `page` integer: Page number, starting at 1.
  - `page_size` integer: Spans per page. Values above 1000 are capped at 1000.

## Response `200`

A page of spans.

- BehaviorSpans
  - `behavior` string, required: Behavior key: a built-in behavior's name (for example `refusal`) or a custom behavior's `id`.
  - `page` integer, required
  - `page_size` integer, required
  - `logs` BehaviorSpan[], required: 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.
    - `unique_id` string, required: Span ID. Pass it to Get a span (`GET /api/request-logs/{unique_id}/`).
    - `model` string, required: Model the span used.
    - `status` string, required: Span status, such as `success` or `failed`.
    - `environment` string, required: Span environment.
    - `timestamp` string, required: Span timestamp. UTC, ISO 8601 without a timezone suffix.

## Other responses

- `400`: `behavior` is missing.
- `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.
- `429`: Rate limited. This endpoint allows 60 requests per minute per organization.

## Changes

- **2026-10-21** `c30bcb383ee8`: 1 breaking, 3 info
  - request body became required
  - api operation id `behaviors_listBehaviorSpans` removed and replaced with `listBehaviorSpans`
  - api tag `Behaviors` added
  - api tag `behaviors` removed
- **2026-10-02** `b830b79cfd52`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/respan/apis/respan-api/changes/api/pulses/behaviors/logs/post.md)

---

[API](https://skmtc.dev/respan/apis/respan-api.md) - [All operations](https://skmtc.dev/respan/apis/respan-api/llms.txt) - [OpenAPI document](https://skmtc.dev/respan/apis/respan-api/revisions/900841387635?raw)