Skip to Content

Get behavior summary

POSThttps://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.

HTTP
Authorization: Bearer $RESPAN_API_KEY

Request body

The request body is optional.

application/json

Field Type Requirement Description and constraints
$ object Optional body
Time range and environment shared by the behavior analytics endpoints.
Reference: #/components/schemas/BehaviorWindowRequest
start_time string Optional
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.
Format: date-time
Example: "2026-09-24T00:00:00Z"
end_time string Optional
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.
Format: date-time
Example: "2026-10-01T00:00:00Z"
environment string Optional
Only count spans from this environment, such as prod or test. Omit it to include every environment.
Example: "prod"

OpenAPI request schema

{
  "$ref": "#/components/schemas/BehaviorWindowRequest"
}
Example
JSON
{ "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

Field Type Requirement Description and constraints
$ object Body
Reference: #/components/schemas/BehaviorSummary
behaviors array<object> Required in parent
One row per behavior scored in the range, most fired first. Turned-off behaviors are left out.
behaviors[] object Array item
Reference: #/components/schemas/BehaviorSummaryItem
behaviors[].behavior string Required in parent
Behavior key: a built-in behavior’s name (for example refusal) or a custom behavior’s id.
Example: "instruction_miss"
behaviors[].fired_spans integer Required in parent
Spans where the behavior fired (latest score at or above 0.65).
Example: 143
behaviors[].classified_spans integer Required in parent
Spans scored for this behavior in the range.
Example: 5210
behaviors[].polarity string Required in parent
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.
Reference: #/components/schemas/BehaviorPolarity
Allowed: "negative", "positive", "neutral"
Example: "negative"
behaviors[].is_builtin boolean Required in parent
true for a built-in behavior, false for one of your custom behaviors.
Example: true
total_behaviors_tracked integer Required in parent
Behaviors in behaviors that fired at least once.
Example: 6
total_classified_spans integer Required in parent
Distinct spans scored in the range. A span scored for several behaviors counts once.
Example: 5210
total_fired_spans integer Required in parent
Distinct spans where at least one behavior fired.
Example: 1288
polarity_totals object Required in parent
Fired verdicts per polarity. A span that fires several behaviors counts once per behavior.
Reference: #/components/schemas/BehaviorPolarityCounts
polarity_totals.positive integer Required in parent
Fired verdicts of positive behaviors (Wins).
Example: 412
polarity_totals.negative integer Required in parent
Fired verdicts of negative behaviors (Issues).
Example: 187
polarity_totals.neutral integer Required in parent
Fired verdicts of neutral behaviors (Info).
Example: 960
net_sentiment integer Required in parent
polarity_totals.positive minus polarity_totals.negative.
Example: 225

OpenAPI response schema

{
  "$ref": "#/components/schemas/BehaviorSummary"
}
Example
JSON
{ "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

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Missing or invalid API key
JSON
{ "detail": "Your API key is invalid or expired, please check your API key in the platform settings." }
Key lacks the permission
JSON
{ "detail": "This API key does not have the 'logs:read' permission." }
Behaviors are off for the organization
JSON
{ "detail": "Span Behaviors is not enabled for this organization." }

429

Rate limited. This endpoint allows 60 requests per minute per organization.

application/json

Field Type Requirement Description and constraints
$ object Body
-
detail string Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "detail"
  ],
  "properties": {
    "detail": {
      "type": "string"
    }
  }
}
Example
JSON
{ "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"
      }
    }
  }
}