Get behavior summary

POST

https://api.respan.ai/api/pulses/behaviors/

POST

/api/pulses/behaviors/

curl -X POST https://api.respan.ai/api/pulses/behaviors/ \
     -H "Authorization: Bearer <respanApiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "start_time": "2026-09-24T00:00:00Z",
  "end_time": "2026-10-01T00:00:00Z",
  "environment": "prod"
}'

{
  "behaviors": [
    {
      "behavior": "task_complete",
      "fired_spans": 412,
      "classified_spans": 5210,
      "polarity": "positive",
      "is_builtin": true
    },
    {
      "behavior": "structured_output",
      "fired_spans": 388,
      "classified_spans": 5210,
      "polarity": "neutral",
      "is_builtin": true
    },
    {
      "behavior": "instruction_miss",
      "fired_spans": 143,
      "classified_spans": 5210,
      "polarity": "negative",
      "is_builtin": true
    },
    {
      "behavior": "6f1c2a9e-3b7d-4c55-9a0e-2d8f4b1c7e93",
      "fired_spans": 44,
      "classified_spans": 5210,
      "polarity": "negative",
      "is_builtin": false
    }
  ],
  "total_behaviors_tracked": 4,
  "total_classified_spans": 5210,
  "total_fired_spans": 902,
  "polarity_totals": {
    "positive": 412,
    "negative": 187,
    "neutral": 388
  },
  "net_sentiment": 225
}

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.

Authentication

AuthorizationBearer

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.

Request

This endpoint expects an object.

start_timedatetimeOptional

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_timedatetimeOptional

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.

environmentstringOptional

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

Response

Behavior counts for the range.

behaviorslist of objects

One row per behavior scored in the range, most fired first. Turned-off behaviors are left out.

total_behaviors_trackedinteger

Behaviors in behaviors that fired at least once.

total_classified_spansinteger

Distinct spans scored in the range. A span scored for several behaviors counts once.

total_fired_spansinteger

Distinct spans where at least one behavior fired.

polarity_totalsobject

Fired verdicts per polarity. A span that fires several behaviors counts once per behavior.

net_sentimentinteger

polarity_totals.positive minus polarity_totals.negative.

Errors

403

Forbidden Error

429

Too Many Requests Error