Skip to Content

List behaviors

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

HTTP
Authorization: Bearer $RESPAN_API_KEY

Responses

200

The behaviors.

application/json

Field Type Requirement Description and constraints
$ object Body
Reference: #/components/schemas/BehaviorCatalog
columns array<object> Required in parent
Built-in behaviors, then custom behaviors oldest first. Turned-off behaviors are left out. Empty when behaviors are off for the organization.
columns[] object Array item
Reference: #/components/schemas/BehaviorCatalogEntry
columns[].id string Required in parent
Column ID, behavior__<key>. Spans list filters accept it as a filter key.
Example: "behavior__instruction_miss"
columns[].key string Required in parent
Behavior key: a built-in behavior’s name (for example refusal) or a custom behavior’s id.
Example: "instruction_miss"
columns[].name string Required in parent
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"
columns[].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"
columns[].type string Required in parent
Always boolean.
Allowed: "boolean"
Example: "boolean"
columns[].source string Required in parent
builtin or custom.
Allowed: "builtin", "custom"
Example: "builtin"
is_span_behaviors_enabled boolean Required in parent
Whether behaviors are turned on for the organization.
Example: true
max_selected_columns integer Required in parent
Most behaviors one spans list or summary request can ask counts for in behavior_columns.
Example: 20
true_probability_threshold number Required in parent
A behavior fires on a span when its latest score is at or above this value.
Example: 0.65

OpenAPI response schema

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

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." }

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": "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"
      }
    }
  }
}