List custom behaviors
https://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.
Authorization: Bearer $RESPAN_API_KEYQuery parameters
page integer OptionalDefault:
1Minimum:
1page_size integer OptionalDefault:
100Minimum:
1Maximum:
1000tags string OptionalExample:
"0b7e5f0c-2a61-4d3e-9a47-5c8f1e2d3b4a"Responses
200
A page of custom behaviors.
application/json
$ object Body
#/components/schemas/CustomBehaviorListresults array<object and object> Required in parent
results[] object and object Array item
#/components/schemas/CustomBehaviorWithTagsresults[] (allOf 1) object Schema variant
#/components/schemas/CustomBehaviorresults[] (allOf 1).id string Required in parentExample:
"6f1c2a9e-3b7d-4c55-9a0e-2d8f4b1c7e93"results[] (allOf 1).name string or null Required in parentid.Maximum length:
128Example:
"Refund promise"results[] (allOf 1).description string Required in parentExample:
"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 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"results[] (allOf 1).created_at string Required in parentdate-timeExample:
"2026-09-28T17:41:09.512340Z"results[] (allOf 1).updated_at string Required in parentdate-timeExample:
"2026-09-28T17:41:09.512340Z"results[] (allOf 2) object Schema variant
results[] (allOf 2).tags array<object> Required in parent
results[] (allOf 2).tags[] object Array item
#/components/schemas/BehaviorTagresults[] (allOf 2).tags[].id string Required in parentExample:
"0b7e5f0c-2a61-4d3e-9a47-5c8f1e2d3b4a"results[] (allOf 2).tags[].name string Required in parentExample:
"Support"results[] (allOf 2).tags[].color string Required in parentExample:
"#2563EB"results[] (allOf 2).tags[].created_at string Required in parentdate-timeExample:
"2026-09-12T09:30:00Z"results[] (allOf 2).tags[].updated_at string Required in parentdate-timeExample:
"2026-09-12T09:30:00Z"count integer Required in parentExample:
3next string or null Required in parentnull on the last page.Format:
uriExample:
nullprevious string or null Required in parentnull on the first page.Format:
uriExample:
nullcurrent_filters object OptionalAdditional properties are allowed
Example:
{}OpenAPI response 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
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
$ 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 'custom_behaviors:read' permission."
}Behaviors are off for the organization
{
"detail": "Span Behaviors is not enabled for this organization."
}429
Rate limited. This endpoint allows 30 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 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"
}
}
}
}