Get behavior signals over time
https://api.respan.ai/api/pulses/behaviors/timeseries/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.
Servers
https://api.respan.ai: Respan API Server
Authentication
RespanApiKey
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.
HTTP scheme: bearer; format: Respan API key.
Authorization: Bearer $RESPAN_API_KEYRequest body
The request body is optional.
application/json
$ object Optional body
#/components/schemas/BehaviorTimeSeriesRequeststart_time string OptionalFormat:
date-timeExample:
"2026-09-24T00:00:00Z"end_time string OptionalFormat:
date-timeExample:
"2026-10-01T00:00:00Z"environment string Optionalprod or test. Omit it to include every environment.Example:
"prod"granularity string OptionalAllowed:
"minute", "hour", "day", "week"Default:
dayExample:
"hour"group_by string Optionalbehavior returns one series per behavior. polarity sums them into one series per polarity.Allowed:
"behavior", "polarity"Default:
behaviorExample:
"behavior"behaviors array<string> Optional
Example:
["refusal","instruction_miss"]behaviors[] string Array itemOpenAPI request schema
{
"$ref": "#/components/schemas/BehaviorTimeSeriesRequest"
}Example
{
"start_time": "2026-09-30T00:00:00Z",
"end_time": "2026-10-01T00:00:00Z",
"granularity": "hour",
"group_by": "behavior",
"behaviors": [
"refusal",
"instruction_miss"
]
}Responses
200
Fired counts per bucket.
application/json
$ object Body
#/components/schemas/BehaviorTimeSeriesgranularity string Required in parent"minute", "hour", "day", "week"Example:
"hour"group_by string Required in parent"behavior", "polarity"Example:
"behavior"series array<object> Required in parent
bucket. A point appears only where the behavior fired, so empty buckets are missing.series[] object Array item
#/components/schemas/BehaviorTimeSeriesPointseries[].bucket string Required in parentYYYY-MM-DD) for week buckets. UTC, ISO 8601 without a timezone suffix.Example:
"2026-09-30T14:00:00"series[].behavior string Optionalrefusal) or a custom behavior’s id. Present when group_by is behavior.Example:
"instruction_miss"series[].polarity string Optional
group_by is polarity.series[].polarity (allOf 1) string Schema variantnegative (an Issue), positive (a Win) or neutral (Info). Display metadata only; it does not change how spans are scored.Reference:
#/components/schemas/BehaviorPolarityAllowed:
"negative", "positive", "neutral"Example:
"negative"series[].fired_spans integer Required in parentExample:
12OpenAPI response schema
{
"$ref": "#/components/schemas/BehaviorTimeSeries"
}Example
{
"granularity": "hour",
"group_by": "behavior",
"series": [
{
"bucket": "2026-09-30T13:00:00",
"behavior": "instruction_miss",
"fired_spans": 9
},
{
"bucket": "2026-09-30T14:00:00",
"behavior": "instruction_miss",
"fired_spans": 12
},
{
"bucket": "2026-09-30T14:00:00",
"behavior": "refusal",
"fired_spans": 3
}
]
}400
Invalid granularity or group_by.
application/json
$ object Body
error string Required in parentOpenAPI response schema
{
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
}Example
{
"error": "granularity must be one of ['day', 'hour', 'minute', 'week']"
}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.
application/json
$ object Body
detail string Required in parentOpenAPI response schema
{
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
}Missing or invalid API key
{
"detail": "Your API key is invalid or expired, please check your API key in the platform settings."
}Key lacks the permission
{
"detail": "This API key does not have the 'logs:read' permission."
}Behaviors are off for the organization
{
"detail": "Span Behaviors is not enabled for this organization."
}429
Rate limited. This endpoint allows 60 requests per minute per organization.
application/json
$ object Body
detail string Required in parentOpenAPI response schema
{
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
}Example
{
"detail": "Request was throttled."
}OpenAPI source
The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.
OpenAPI operation
{
"summary": "Get behavior signals over time",
"operationId": "getBehaviorTimeSeries",
"tags": [
"Behaviors"
],
"description": "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.",
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BehaviorTimeSeriesRequest"
},
"example": {
"start_time": "2026-09-30T00:00:00Z",
"end_time": "2026-10-01T00:00:00Z",
"granularity": "hour",
"group_by": "behavior",
"behaviors": [
"refusal",
"instruction_miss"
]
}
}
}
},
"responses": {
"200": {
"description": "Fired counts per bucket.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BehaviorTimeSeries"
},
"example": {
"granularity": "hour",
"group_by": "behavior",
"series": [
{
"bucket": "2026-09-30T13:00:00",
"behavior": "instruction_miss",
"fired_spans": 9
},
{
"bucket": "2026-09-30T14:00:00",
"behavior": "instruction_miss",
"fired_spans": 12
},
{
"bucket": "2026-09-30T14:00:00",
"behavior": "refusal",
"fired_spans": 3
}
]
}
}
}
},
"400": {
"description": "Invalid `granularity` or `group_by`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string"
}
}
},
"example": {
"error": "granularity must be one of ['day', 'hour', 'minute', 'week']"
}
}
}
},
"403": {
"description": "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.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
},
"examples": {
"invalidKey": {
"summary": "Missing or invalid API key",
"value": {
"detail": "Your API key is invalid or expired, please check your API key in the platform settings."
}
},
"missingPermission": {
"summary": "Key lacks the permission",
"value": {
"detail": "This API key does not have the 'logs:read' permission."
}
},
"behaviorsOff": {
"summary": "Behaviors are off for the organization",
"value": {
"detail": "Span Behaviors is not enabled for this organization."
}
}
}
}
}
},
"429": {
"description": "Rate limited. This endpoint allows 60 requests per minute per organization.",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"detail"
],
"properties": {
"detail": {
"type": "string"
}
}
},
"example": {
"detail": "Request was throttled."
}
}
}
}
},
"security": [
{
"RespanApiKey": []
}
]
}OpenAPI path metadata
{}Referenced OpenAPI components
{
"schemas": {
"BehaviorPolarity": {
"type": "string",
"enum": [
"negative",
"positive",
"neutral"
],
"description": "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.",
"example": "negative"
},
"BehaviorTimeSeries": {
"type": "object",
"required": [
"granularity",
"group_by",
"series"
],
"properties": {
"granularity": {
"type": "string",
"enum": [
"minute",
"hour",
"day",
"week"
],
"example": "hour"
},
"group_by": {
"type": "string",
"enum": [
"behavior",
"polarity"
],
"example": "behavior"
},
"series": {
"type": "array",
"description": "Points ordered by `bucket`. A point appears only where the behavior fired, so empty buckets are missing.",
"items": {
"$ref": "#/components/schemas/BehaviorTimeSeriesPoint"
}
}
}
},
"BehaviorTimeSeriesPoint": {
"type": "object",
"required": [
"bucket",
"fired_spans"
],
"properties": {
"bucket": {
"type": "string",
"description": "Start of the bucket. A date (`YYYY-MM-DD`) for `week` buckets. UTC, ISO 8601 without a timezone suffix.",
"example": "2026-09-30T14:00:00"
},
"behavior": {
"type": "string",
"description": "Behavior key: a built-in behavior's name (for example `refusal`) or a custom behavior's `id`. Present when `group_by` is `behavior`.",
"example": "instruction_miss"
},
"polarity": {
"allOf": [
{
"$ref": "#/components/schemas/BehaviorPolarity"
}
],
"description": "Present when `group_by` is `polarity`."
},
"fired_spans": {
"type": "integer",
"description": "Spans where the behavior (or any behavior of the polarity) fired in the bucket.",
"example": 12
}
}
},
"BehaviorTimeSeriesRequest": {
"type": "object",
"properties": {
"start_time": {
"type": "string",
"format": "date-time",
"description": "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.",
"example": "2026-09-24T00:00:00Z"
},
"end_time": {
"type": "string",
"format": "date-time",
"description": "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.",
"example": "2026-10-01T00:00:00Z"
},
"environment": {
"type": "string",
"description": "Only count spans from this environment, such as `prod` or `test`. Omit it to include every environment.",
"example": "prod"
},
"granularity": {
"type": "string",
"enum": [
"minute",
"hour",
"day",
"week"
],
"default": "day",
"description": "Bucket size.",
"example": "hour"
},
"group_by": {
"type": "string",
"enum": [
"behavior",
"polarity"
],
"default": "behavior",
"description": "`behavior` returns one series per behavior. `polarity` sums them into one series per polarity.",
"example": "behavior"
},
"behaviors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Only include these behavior keys (built-in names or custom behavior IDs). Omit for every behavior.",
"example": [
"refusal",
"instruction_miss"
]
}
}
}
},
"securitySchemes": {
"RespanApiKey": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "Respan API key",
"description": "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.",
"x-fern-bearer": {
"name": "respanApiKey",
"env": "RESPAN_API_KEY"
}
}
}
}