Skip to Content

List custom behaviors

GEThttps://api.respan.ai/api/pulses/behaviors/custom/

Lists your organization’s custom behaviors, most recently updated first.

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

Query parameters

Parameter Type Required Description and constraints
page integer Optional
Page number.
Default: 1
Minimum: 1
page_size integer Optional
Behaviors per page. Values above 1000 are capped at 1000.
Default: 100
Minimum: 1
Maximum: 1000
tags string Optional
Only behaviors with any of these tag IDs. Comma-separated, or repeat the parameter.
Example: "0b7e5f0c-2a61-4d3e-9a47-5c8f1e2d3b4a"

Responses

200

A page of custom behaviors.

application/json

Field Type Requirement Description and constraints
$ object Body
Reference: #/components/schemas/CustomBehaviorList
results array<object and object> Required in parent
Custom behaviors, most recently updated first.
results[] object and object Array item
Reference: #/components/schemas/CustomBehaviorWithTags
results[] (allOf 1) object Schema variant
Reference: #/components/schemas/CustomBehavior
results[] (allOf 1).id string Required in parent
Custom behavior ID. It is also the behavior’s key in analytics, filters and span verdicts.
Example: "6f1c2a9e-3b7d-4c55-9a0e-2d8f4b1c7e93"
results[] (allOf 1).name string or null Required in parent
Display name. Optional and not unique; behaviors are identified by id.
Maximum length: 128
Example: "Refund promise"
results[] (allOf 1).description string Required in parent
The plain-language definition span-01 scores each span against. Say what counts and what doesn’t. At least 3 characters after trimming.
Example: "The assistant promises a refund, credit, or compensation that the policy in the system prompt does not allow."
results[] (allOf 1).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"
results[] (allOf 1).created_at string Required in parent
Format: date-time
Example: "2026-09-28T17:41:09.512340Z"
results[] (allOf 1).updated_at string Required in parent
Format: date-time
Example: "2026-09-28T17:41:09.512340Z"
results[] (allOf 2) object Schema variant
-
results[] (allOf 2).tags array<object> Required in parent
Tags on the behavior.
results[] (allOf 2).tags[] object Array item
Reference: #/components/schemas/BehaviorTag
results[] (allOf 2).tags[].id string Required in parent
Tag ID.
Example: "0b7e5f0c-2a61-4d3e-9a47-5c8f1e2d3b4a"
results[] (allOf 2).tags[].name string Required in parent
Tag name.
Example: "Support"
results[] (allOf 2).tags[].color string Required in parent
Tag color.
Example: "#2563EB"
results[] (allOf 2).tags[].created_at string Required in parent
Format: date-time
Example: "2026-09-12T09:30:00Z"
results[] (allOf 2).tags[].updated_at string Required in parent
Format: date-time
Example: "2026-09-12T09:30:00Z"
count integer Required in parent
Number of behaviors on this page (not the total).
Example: 3
next string or null Required in parent
URL of the next page, or null on the last page.
Format: uri
Example: null
previous string or null Required in parent
URL of the previous page, or null on the first page.
Format: uri
Example: null
current_filters object Optional
Always empty for this endpoint.
Additional properties are allowed
Example: {}

OpenAPI response schema

{
  "$ref": "#/components/schemas/CustomBehaviorList"
}
Example
JSON
{ "results": [ { "id": "6f1c2a9e-3b7d-4c55-9a0e-2d8f4b1c7e93", "name": "Refund promise", "description": "The assistant promises a refund, credit, or compensation that the policy in the system prompt does not allow.", "polarity": "negative", "created_at": "2026-09-28T17:41:09.512340Z", "updated_at": "2026-09-28T17:41:09.512340Z", "tags": [ { "id": "0b7e5f0c-2a61-4d3e-9a47-5c8f1e2d3b4a", "name": "Support", "color": "#2563EB", "created_at": "2026-09-12T09:30:00Z", "updated_at": "2026-09-12T09:30:00Z" } ] } ], "count": 1, "previous": null, "next": null, "current_filters": {} }

403

Forbidden: the API key is missing, invalid or expired; the key doesn’t grant custom_behaviors: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 'custom_behaviors:read' permission." }
Behaviors are off for the organization
JSON
{ "detail": "Span Behaviors is not enabled for this organization." }

429

Rate limited. This endpoint allows 30 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 custom behaviors",
  "operationId": "listCustomBehaviors",
  "tags": [
    "Behaviors"
  ],
  "description": "Lists your organization's custom behaviors, most recently updated first.",
  "parameters": [
    {
      "name": "page",
      "in": "query",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "default": 1
      },
      "description": "Page number."
    },
    {
      "name": "page_size",
      "in": "query",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 1000,
        "default": 100
      },
      "description": "Behaviors per page. Values above 1000 are capped at 1000."
    },
    {
      "name": "tags",
      "in": "query",
      "schema": {
        "type": "string"
      },
      "description": "Only behaviors with any of these tag IDs. Comma-separated, or repeat the parameter.",
      "example": "0b7e5f0c-2a61-4d3e-9a47-5c8f1e2d3b4a"
    }
  ],
  "responses": {
    "200": {
      "description": "A page of custom behaviors.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CustomBehaviorList"
          },
          "example": {
            "results": [
              {
                "id": "6f1c2a9e-3b7d-4c55-9a0e-2d8f4b1c7e93",
                "name": "Refund promise",
                "description": "The assistant promises a refund, credit, or compensation that the policy in the system prompt does not allow.",
                "polarity": "negative",
                "created_at": "2026-09-28T17:41:09.512340Z",
                "updated_at": "2026-09-28T17:41:09.512340Z",
                "tags": [
                  {
                    "id": "0b7e5f0c-2a61-4d3e-9a47-5c8f1e2d3b4a",
                    "name": "Support",
                    "color": "#2563EB",
                    "created_at": "2026-09-12T09:30:00Z",
                    "updated_at": "2026-09-12T09:30:00Z"
                  }
                ]
              }
            ],
            "count": 1,
            "previous": null,
            "next": null,
            "current_filters": {}
          }
        }
      }
    },
    "403": {
      "description": "Forbidden: the API key is missing, invalid or expired; the key doesn't grant `custom_behaviors: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 'custom_behaviors: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 30 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"
    },
    "BehaviorTag": {
      "type": "object",
      "required": [
        "id",
        "name",
        "color",
        "created_at",
        "updated_at"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Tag ID.",
          "example": "0b7e5f0c-2a61-4d3e-9a47-5c8f1e2d3b4a"
        },
        "name": {
          "type": "string",
          "description": "Tag name.",
          "example": "Support"
        },
        "color": {
          "type": "string",
          "description": "Tag color.",
          "example": "#2563EB"
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "example": "2026-09-12T09:30:00Z"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "example": "2026-09-12T09:30:00Z"
        }
      }
    },
    "CustomBehavior": {
      "type": "object",
      "required": [
        "id",
        "name",
        "description",
        "polarity",
        "created_at",
        "updated_at"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Custom behavior ID. It is also the behavior's key in analytics, filters and span verdicts.",
          "example": "6f1c2a9e-3b7d-4c55-9a0e-2d8f4b1c7e93"
        },
        "name": {
          "type": "string",
          "nullable": true,
          "maxLength": 128,
          "description": "Display name. Optional and not unique; behaviors are identified by `id`.",
          "example": "Refund promise"
        },
        "description": {
          "type": "string",
          "description": "The plain-language definition span-01 scores each span against. Say what counts and what doesn't. At least 3 characters after trimming.",
          "example": "The assistant promises a refund, credit, or compensation that the policy in the system prompt does not allow."
        },
        "polarity": {
          "$ref": "#/components/schemas/BehaviorPolarity"
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "example": "2026-09-28T17:41:09.512340Z"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "example": "2026-09-28T17:41:09.512340Z"
        }
      }
    },
    "CustomBehaviorList": {
      "type": "object",
      "required": [
        "results",
        "count",
        "next",
        "previous"
      ],
      "properties": {
        "results": {
          "type": "array",
          "description": "Custom behaviors, most recently updated first.",
          "items": {
            "$ref": "#/components/schemas/CustomBehaviorWithTags"
          }
        },
        "count": {
          "type": "integer",
          "description": "Number of behaviors on this page (not the total).",
          "example": 3
        },
        "next": {
          "type": "string",
          "nullable": true,
          "format": "uri",
          "description": "URL of the next page, or `null` on the last page.",
          "example": null
        },
        "previous": {
          "type": "string",
          "nullable": true,
          "format": "uri",
          "description": "URL of the previous page, or `null` on the first page.",
          "example": null
        },
        "current_filters": {
          "type": "object",
          "additionalProperties": true,
          "description": "Always empty for this endpoint.",
          "example": {}
        }
      }
    },
    "CustomBehaviorWithTags": {
      "allOf": [
        {
          "$ref": "#/components/schemas/CustomBehavior"
        },
        {
          "type": "object",
          "required": [
            "tags"
          ],
          "properties": {
            "tags": {
              "type": "array",
              "description": "Tags on the behavior.",
              "items": {
                "$ref": "#/components/schemas/BehaviorTag"
              }
            }
          }
        }
      ]
    }
  },
  "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"
      }
    }
  }
}