Get behavior signals over time

curl -X POST https://api.respan.ai/api/pulses/behaviors/timeseries/ \
     -H "Authorization: Bearer <respanApiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "start_time": "2026-09-30T00:00:00Z",
  "end_time": "2026-10-01T00:00:00Z",
  "granularity": "hour",
  "group_by": "behavior",
  "behaviors": [
    "refusal",
    "instruction_miss"
  ]
}'

{
  "granularity": "hour",
  "group_by": "behavior",
  "series": [
    {
      "bucket": "2026-09-30T13:00:00",
      "fired_spans": 9,
      "behavior": "instruction_miss"
    },
    {
      "bucket": "2026-09-30T14:00:00",
      "fired_spans": 12,
      "behavior": "instruction_miss"
    },
    {
      "bucket": "2026-09-30T14:00:00",
      "fired_spans": 3,
      "behavior": "refusal"
    }
  ]
}

Returns how many spans fired each behavior per time bucket, or per polarity with group_by: polarity. minute buckets use exact range edges; larger buckets read the hourly rollup.

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.

granularityenumOptionalDefaults to day

Bucket size.

Allowed values:

group_byenumOptionalDefaults to behavior

behavior returns one series per behavior. polarity sums them into one series per polarity.

Allowed values:

behaviorslist of stringsOptional

Only include these behavior keys (built-in names or custom behavior IDs). Omit for every behavior.

Response

Fired counts per bucket.

granularityenum

Allowed values:

group_byenum

Allowed values:

serieslist of objects

Points ordered by bucket. A point appears only where the behavior fired, so empty buckets are missing.

Errors

400

Bad Request Error

403

Forbidden Error

429

Too Many Requests Error