KEkeywordsai
Behaviors

Get behavior counts by dimension

Changed on

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.

post/api/pulses/behaviors/grouped/

Request

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

Request body

behaviorstring 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_timestring 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_timestring 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.

environmentstring

Only count spans from this environment, such as prod or test. Omit it to include every environment.

limitinteger

Maximum groups to return. Values above 100 are capped at 100.

Example request

{
  "behavior": "instruction_miss",
  "group_by": "model",
  "start_time": "2026-09-24T00:00:00Z",
  "end_time": "2026-10-01T00:00:00Z",
  "environment": "prod",
  "limit": 10
}

Response

Fired counts per group.

behaviorstring 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

Example response

{
  "behavior": "instruction_miss",
  "group_by": "model",
  "groups": [
    {
      "group_value": "gpt-4o-mini",
      "fired_spans": 61
    }
  ]
}

Changes

  • c30bcb383ee8Revision changes
    • breaking

      request body became required

    • info

      api operation id behaviors_getBehaviorBreakdown removed and replaced with getBehaviorBreakdown

    • info

      api tag Behaviors added

    • info

      api tag behaviors removed

  • b830b79cfd52Revision changes
    • info

      endpoint added