List behaviors
https://api.respan.ai/api/request-logs/behavior-columns/Lists every behavior turned on for your organization, built-in and custom, with the key it’s counted under. Use the keys with the other behavior endpoints. Returns an empty list instead of an error when behaviors are off.
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_KEYResponses
200
The behaviors.
application/json
$ object Body
#/components/schemas/BehaviorCatalogcolumns array<object> Required in parent
columns[] object Array item
#/components/schemas/BehaviorCatalogEntrycolumns[].id string Required in parentbehavior__<key>. Spans list filters accept it as a filter key.Example:
"behavior__instruction_miss"columns[].key string Required in parentrefusal) or a custom behavior’s id.Example:
"instruction_miss"columns[].name string Required in parentInstruction Miss). For a custom behavior, its name, else its description, else its id.Example:
"Instruction Miss"columns[].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"columns[].type string Required in parentboolean.Allowed:
"boolean"Example:
"boolean"columns[].source string Required in parentbuiltin or custom.Allowed:
"builtin", "custom"Example:
"builtin"is_span_behaviors_enabled boolean Required in parentExample:
truemax_selected_columns integer Required in parentbehavior_columns.Example:
20true_probability_threshold number Required in parentExample:
0.65OpenAPI response schema
{
"$ref": "#/components/schemas/BehaviorCatalog"
}Example
{
"columns": [
{
"id": "behavior__refusal",
"key": "refusal",
"name": "Refusal",
"polarity": "neutral",
"type": "boolean",
"source": "builtin"
},
{
"id": "behavior__instruction_miss",
"key": "instruction_miss",
"name": "Instruction Miss",
"polarity": "negative",
"type": "boolean",
"source": "builtin"
},
{
"id": "behavior__6f1c2a9e-3b7d-4c55-9a0e-2d8f4b1c7e93",
"key": "6f1c2a9e-3b7d-4c55-9a0e-2d8f4b1c7e93",
"name": "Refund promise",
"polarity": "negative",
"type": "boolean",
"source": "custom"
}
],
"is_span_behaviors_enabled": true,
"max_selected_columns": 20,
"true_probability_threshold": 0.65
}403
Forbidden: the API key is missing, invalid or expired; the key doesn’t grant logs:read (Read access does).
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."
}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": "List behaviors",
"operationId": "listBehaviors",
"tags": [
"Behaviors"
],
"description": "Lists every behavior turned on for your organization, built-in and custom, with the key it's counted under. Use the keys with the other behavior endpoints. Returns an empty list instead of an error when behaviors are off.",
"responses": {
"200": {
"description": "The behaviors.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BehaviorCatalog"
},
"example": {
"columns": [
{
"id": "behavior__refusal",
"key": "refusal",
"name": "Refusal",
"polarity": "neutral",
"type": "boolean",
"source": "builtin"
},
{
"id": "behavior__instruction_miss",
"key": "instruction_miss",
"name": "Instruction Miss",
"polarity": "negative",
"type": "boolean",
"source": "builtin"
},
{
"id": "behavior__6f1c2a9e-3b7d-4c55-9a0e-2d8f4b1c7e93",
"key": "6f1c2a9e-3b7d-4c55-9a0e-2d8f4b1c7e93",
"name": "Refund promise",
"polarity": "negative",
"type": "boolean",
"source": "custom"
}
],
"is_span_behaviors_enabled": true,
"max_selected_columns": 20,
"true_probability_threshold": 0.65
}
}
}
},
"403": {
"description": "Forbidden: the API key is missing, invalid or expired; the key doesn't grant `logs:read` (Read access does).",
"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."
}
}
}
}
}
},
"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": {
"BehaviorCatalog": {
"type": "object",
"required": [
"columns",
"is_span_behaviors_enabled",
"max_selected_columns",
"true_probability_threshold"
],
"properties": {
"columns": {
"type": "array",
"description": "Built-in behaviors, then custom behaviors oldest first. Turned-off behaviors are left out. Empty when behaviors are off for the organization.",
"items": {
"$ref": "#/components/schemas/BehaviorCatalogEntry"
}
},
"is_span_behaviors_enabled": {
"type": "boolean",
"description": "Whether behaviors are turned on for the organization.",
"example": true
},
"max_selected_columns": {
"type": "integer",
"description": "Most behaviors one spans list or summary request can ask counts for in `behavior_columns`.",
"example": 20
},
"true_probability_threshold": {
"type": "number",
"description": "A behavior fires on a span when its latest score is at or above this value.",
"example": 0.65
}
}
},
"BehaviorCatalogEntry": {
"type": "object",
"required": [
"id",
"key",
"name",
"polarity",
"type",
"source"
],
"properties": {
"id": {
"type": "string",
"description": "Column ID, `behavior__<key>`. Spans list filters accept it as a filter key.",
"example": "behavior__instruction_miss"
},
"key": {
"type": "string",
"description": "Behavior key: a built-in behavior's name (for example `refusal`) or a custom behavior's `id`.",
"example": "instruction_miss"
},
"name": {
"type": "string",
"description": "Display name. For a built-in behavior, its key in title case (`Instruction Miss`). For a custom behavior, its `name`, else its `description`, else its `id`.",
"example": "Instruction Miss"
},
"polarity": {
"$ref": "#/components/schemas/BehaviorPolarity"
},
"type": {
"type": "string",
"enum": [
"boolean"
],
"description": "Always `boolean`.",
"example": "boolean"
},
"source": {
"type": "string",
"enum": [
"builtin",
"custom"
],
"description": "`builtin` or `custom`.",
"example": "builtin"
}
}
},
"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"
}
},
"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"
}
}
}
}