---
title: "Get behavior counts by dimension"
method: POST
path: "/api/pulses/behaviors/grouped/"
tags: ["Behaviors"]
---

# Get behavior counts by dimension

`POST /api/pulses/behaviors/grouped/`

## Request

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

Splits the spans where one behavior fired by a span field, such as model or customer. The signals panel uses it for its "By model" and "By customer" splits.

## Request body

- BehaviorBreakdownRequest
  - `behavior` string, required: Behavior key: a built-in behavior's name (for example `refusal`) or a custom behavior's `id`.
  - `group_by` 'customer_identifier' | 'deployment_name' | 'environment' | 'model' | 'prompt_id' | 'prompt_name' | 'provider_id' | 'status', required: Span field to split by. `status` is the span status, such as `success` or `failed`.
  - `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.
  - `limit` integer: Maximum groups to return. Values above 100 are capped at 100.

## Response `200`

Fired counts per group.

- BehaviorBreakdown
  - `behavior` string, required: Behavior key: a built-in behavior's name (for example `refusal`) or a custom behavior's `id`.
  - `group_by` 'customer_identifier' | 'deployment_name' | 'environment' | 'model' | 'prompt_id' | 'prompt_name' | 'provider_id' | 'status', required
  - `groups` BehaviorBreakdownGroup[], required: Groups ordered by `fired_spans`, highest first. Empty when the behavior is turned off.
    - `group_value` string, required: Value of the `group_by` field. Spans with no value are grouped under an empty string.
    - `fired_spans` integer, required: Spans with this value where the behavior fired.

## Other responses

- `400`: `behavior` is missing or `group_by` is not supported.
- `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_getBehaviorBreakdown` removed and replaced with `getBehaviorBreakdown`
  - 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/grouped/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)