Get behavior summary
https://api.respan.ai/api/pulses/behaviors/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.
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
Reference:
#/components/schemas/BehaviorWindowRequeststart_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"OpenAPI request schema
{
"$ref": "#/components/schemas/BehaviorWindowRequest"
}Example
{
"start_time": "2026-09-24T00:00:00Z",
"end_time": "2026-10-01T00:00:00Z",
"environment": "prod"
}Responses
200
Behavior counts for the range.
application/json
$ object Body
#/components/schemas/BehaviorSummarybehaviors array<object> Required in parent
behaviors[] object Array item
#/components/schemas/BehaviorSummaryItembehaviors[].behavior string Required in parentrefusal) or a custom behavior’s id.Example:
"instruction_miss"behaviors[].fired_spans integer Required in parentExample:
143behaviors[].classified_spans integer Required in parentExample:
5210behaviors[].polarity string Required in parentnegative (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"behaviors[].is_builtin boolean Required in parenttrue for a built-in behavior, false for one of your custom behaviors.Example:
truetotal_behaviors_tracked integer Required in parentbehaviors that fired at least once.Example:
6total_classified_spans integer Required in parentExample:
5210total_fired_spans integer Required in parentExample:
1288polarity_totals object Required in parent
Reference:
#/components/schemas/BehaviorPolarityCountspolarity_totals.positive integer Required in parentpositive behaviors (Wins).Example:
412polarity_totals.negative integer Required in parentnegative behaviors (Issues).Example:
187polarity_totals.neutral integer Required in parentneutral behaviors (Info).Example:
960net_sentiment integer Required in parentpolarity_totals.positive minus polarity_totals.negative.Example:
225OpenAPI response schema
{
"$ref": "#/components/schemas/BehaviorSummary"
}Example
{
"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
}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 summary",
"operationId": "getBehaviorSummary",
"tags": [
"Behaviors"
],
"description": "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.",
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BehaviorWindowRequest"
},
"example": {
"start_time": "2026-09-24T00:00:00Z",
"end_time": "2026-10-01T00:00:00Z",
"environment": "prod"
}
}
}
},
"responses": {
"200": {
"description": "Behavior counts for the range.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BehaviorSummary"
},
"example": {
"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
}
}
}
},
"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"
},
"BehaviorPolarityCounts": {
"type": "object",
"description": "Fired verdicts per polarity. A span that fires several behaviors counts once per behavior.",
"required": [
"positive",
"negative",
"neutral"
],
"properties": {
"positive": {
"type": "integer",
"description": "Fired verdicts of `positive` behaviors (Wins).",
"example": 412
},
"negative": {
"type": "integer",
"description": "Fired verdicts of `negative` behaviors (Issues).",
"example": 187
},
"neutral": {
"type": "integer",
"description": "Fired verdicts of `neutral` behaviors (Info).",
"example": 960
}
}
},
"BehaviorSummary": {
"type": "object",
"required": [
"behaviors",
"total_behaviors_tracked",
"total_classified_spans",
"total_fired_spans",
"polarity_totals",
"net_sentiment"
],
"properties": {
"behaviors": {
"type": "array",
"description": "One row per behavior scored in the range, most fired first. Turned-off behaviors are left out.",
"items": {
"$ref": "#/components/schemas/BehaviorSummaryItem"
}
},
"total_behaviors_tracked": {
"type": "integer",
"description": "Behaviors in `behaviors` that fired at least once.",
"example": 6
},
"total_classified_spans": {
"type": "integer",
"description": "Distinct spans scored in the range. A span scored for several behaviors counts once.",
"example": 5210
},
"total_fired_spans": {
"type": "integer",
"description": "Distinct spans where at least one behavior fired.",
"example": 1288
},
"polarity_totals": {
"$ref": "#/components/schemas/BehaviorPolarityCounts"
},
"net_sentiment": {
"type": "integer",
"description": "`polarity_totals.positive` minus `polarity_totals.negative`.",
"example": 225
}
}
},
"BehaviorSummaryItem": {
"type": "object",
"required": [
"behavior",
"fired_spans",
"classified_spans",
"polarity",
"is_builtin"
],
"properties": {
"behavior": {
"type": "string",
"description": "Behavior key: a built-in behavior's name (for example `refusal`) or a custom behavior's `id`.",
"example": "instruction_miss"
},
"fired_spans": {
"type": "integer",
"description": "Spans where the behavior fired (latest score at or above 0.65).",
"example": 143
},
"classified_spans": {
"type": "integer",
"description": "Spans scored for this behavior in the range.",
"example": 5210
},
"polarity": {
"$ref": "#/components/schemas/BehaviorPolarity"
},
"is_builtin": {
"type": "boolean",
"description": "`true` for a built-in behavior, `false` for one of your custom behaviors.",
"example": true
}
}
},
"BehaviorWindowRequest": {
"type": "object",
"description": "Time range and environment shared by the behavior analytics endpoints.",
"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"
}
}
}
},
"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"
}
}
}
}