---
title: "Get behavior summary"
method: POST
path: "/api/pulses/behaviors/"
tags: ["Behaviors"]
---

# Get behavior summary

`POST /api/pulses/behaviors/`

## Request

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

Returns how often each behavior fired in a time range, with totals and a rollup by polarity. Counts come from an hourly rollup refreshed every 10 minutes, so the range is widened to whole hours.

## Request body

- BehaviorWindowRequest: Time range and environment shared by the behavior analytics endpoints.
  - `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.

## Response `200`

Behavior counts for the range.

- BehaviorSummary
  - `behaviors` BehaviorSummaryItem[], required: One row per behavior scored in the range, most fired first. Turned-off behaviors are left out.
    - `behavior` string, required: Behavior key: a built-in behavior's name (for example `refusal`) or a custom behavior's `id`.
    - `fired_spans` integer, required: Spans where the behavior fired (latest score at or above 0.65).
    - `classified_spans` integer, required: Spans scored for this behavior in the range.
    - `polarity` 'negative' | 'positive' | 'neutral', required: Whether the behavior firing is good or bad: `negative` (an Issue), `positive` (a Win) or `neutral` (Info). Display metadata only; it does not change how spans are scored.
    - `is_builtin` boolean, required: `true` for a built-in behavior, `false` for one of your custom behaviors.
  - `total_behaviors_tracked` integer, required: Behaviors in `behaviors` that fired at least once.
  - `total_classified_spans` integer, required: Distinct spans scored in the range. A span scored for several behaviors counts once.
  - `total_fired_spans` integer, required: Distinct spans where at least one behavior fired.
  - `polarity_totals` BehaviorPolarityCounts, required: Fired verdicts per polarity. A span that fires several behaviors counts once per behavior.
    - `positive` integer, required: Fired verdicts of `positive` behaviors (Wins).
    - `negative` integer, required: Fired verdicts of `negative` behaviors (Issues).
    - `neutral` integer, required: Fired verdicts of `neutral` behaviors (Info).
  - `net_sentiment` integer, required: `polarity_totals.positive` minus `polarity_totals.negative`.

## Other responses

- `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`: 3 info
  - api operation id `behaviors_getBehaviorSummary` removed and replaced with `getBehaviorSummary`
  - api tag `Behaviors` added
  - api tag `behaviors` removed
- **2026-10-02** `b830b79cfd52`: 1 info
  - endpoint added
- **2026-08-13** `4e064cf81dae`: 1 breaking
  - api path removed without deprecation
- **2026-07-31** `c26d550029f8`: 1 info
  - endpoint added

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

---

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