Skip to Content

Get behavior signals over time

POSThttps://api.respan.ai/api/pulses/behaviors/timeseries/

Returns how many spans fired each behavior per time bucket, or per polarity with group_by: polarity. minute buckets use exact range edges; larger buckets read the hourly rollup.

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
Reference: #/components/schemas/BehaviorTimeSeriesRequest
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"
granularity string Optional
Bucket size.
Allowed: "minute", "hour", "day", "week"
Default: day
Example: "hour"
group_by string Optional
behavior returns one series per behavior. polarity sums them into one series per polarity.
Allowed: "behavior", "polarity"
Default: behavior
Example: "behavior"
behaviors array<string> Optional
Only include these behavior keys (built-in names or custom behavior IDs). Omit for every behavior.
Example: ["refusal","instruction_miss"]
behaviors[] string Array item
-

OpenAPI request schema

{
  "$ref": "#/components/schemas/BehaviorTimeSeriesRequest"
}
Example
JSON
{ "start_time": "2026-09-30T00:00:00Z", "end_time": "2026-10-01T00:00:00Z", "granularity": "hour", "group_by": "behavior", "behaviors": [ "refusal", "instruction_miss" ] }

Responses

200

Fired counts per bucket.

application/json

Field Type Requirement Description and constraints
$ object Body
Reference: #/components/schemas/BehaviorTimeSeries
granularity string Required in parent
Allowed: "minute", "hour", "day", "week"
Example: "hour"
group_by string Required in parent
Allowed: "behavior", "polarity"
Example: "behavior"
series array<object> Required in parent
Points ordered by bucket. A point appears only where the behavior fired, so empty buckets are missing.
series[] object Array item
Reference: #/components/schemas/BehaviorTimeSeriesPoint
series[].bucket string Required in parent
Start of the bucket. A date (YYYY-MM-DD) for week buckets. UTC, ISO 8601 without a timezone suffix.
Example: "2026-09-30T14:00:00"
series[].behavior string Optional
Behavior key: a built-in behavior’s name (for example refusal) or a custom behavior’s id. Present when group_by is behavior.
Example: "instruction_miss"
series[].polarity string Optional
Present when group_by is polarity.
series[].polarity (allOf 1) string Schema variant
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"
series[].fired_spans integer Required in parent
Spans where the behavior (or any behavior of the polarity) fired in the bucket.
Example: 12

OpenAPI response schema

{
  "$ref": "#/components/schemas/BehaviorTimeSeries"
}
Example
JSON
{ "granularity": "hour", "group_by": "behavior", "series": [ { "bucket": "2026-09-30T13:00:00", "behavior": "instruction_miss", "fired_spans": 9 }, { "bucket": "2026-09-30T14:00:00", "behavior": "instruction_miss", "fired_spans": 12 }, { "bucket": "2026-09-30T14:00:00", "behavior": "refusal", "fired_spans": 3 } ] }

400

Invalid granularity or group_by.

application/json

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

OpenAPI response schema

{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string"
    }
  }
}
Example
JSON
{ "error": "granularity must be one of ['day', 'hour', 'minute', 'week']" }

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 signals over time",
  "operationId": "getBehaviorTimeSeries",
  "tags": [
    "Behaviors"
  ],
  "description": "Returns how many spans fired each behavior per time bucket, or per polarity with `group_by: polarity`. `minute` buckets use exact range edges; larger buckets read the hourly rollup.",
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/BehaviorTimeSeriesRequest"
        },
        "example": {
          "start_time": "2026-09-30T00:00:00Z",
          "end_time": "2026-10-01T00:00:00Z",
          "granularity": "hour",
          "group_by": "behavior",
          "behaviors": [
            "refusal",
            "instruction_miss"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Fired counts per bucket.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/BehaviorTimeSeries"
          },
          "example": {
            "granularity": "hour",
            "group_by": "behavior",
            "series": [
              {
                "bucket": "2026-09-30T13:00:00",
                "behavior": "instruction_miss",
                "fired_spans": 9
              },
              {
                "bucket": "2026-09-30T14:00:00",
                "behavior": "instruction_miss",
                "fired_spans": 12
              },
              {
                "bucket": "2026-09-30T14:00:00",
                "behavior": "refusal",
                "fired_spans": 3
              }
            ]
          }
        }
      }
    },
    "400": {
      "description": "Invalid `granularity` or `group_by`.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "error"
            ],
            "properties": {
              "error": {
                "type": "string"
              }
            }
          },
          "example": {
            "error": "granularity must be one of ['day', 'hour', 'minute', 'week']"
          }
        }
      }
    },
    "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"
    },
    "BehaviorTimeSeries": {
      "type": "object",
      "required": [
        "granularity",
        "group_by",
        "series"
      ],
      "properties": {
        "granularity": {
          "type": "string",
          "enum": [
            "minute",
            "hour",
            "day",
            "week"
          ],
          "example": "hour"
        },
        "group_by": {
          "type": "string",
          "enum": [
            "behavior",
            "polarity"
          ],
          "example": "behavior"
        },
        "series": {
          "type": "array",
          "description": "Points ordered by `bucket`. A point appears only where the behavior fired, so empty buckets are missing.",
          "items": {
            "$ref": "#/components/schemas/BehaviorTimeSeriesPoint"
          }
        }
      }
    },
    "BehaviorTimeSeriesPoint": {
      "type": "object",
      "required": [
        "bucket",
        "fired_spans"
      ],
      "properties": {
        "bucket": {
          "type": "string",
          "description": "Start of the bucket. A date (`YYYY-MM-DD`) for `week` buckets. UTC, ISO 8601 without a timezone suffix.",
          "example": "2026-09-30T14:00:00"
        },
        "behavior": {
          "type": "string",
          "description": "Behavior key: a built-in behavior's name (for example `refusal`) or a custom behavior's `id`. Present when `group_by` is `behavior`.",
          "example": "instruction_miss"
        },
        "polarity": {
          "allOf": [
            {
              "$ref": "#/components/schemas/BehaviorPolarity"
            }
          ],
          "description": "Present when `group_by` is `polarity`."
        },
        "fired_spans": {
          "type": "integer",
          "description": "Spans where the behavior (or any behavior of the polarity) fired in the bucket.",
          "example": 12
        }
      }
    },
    "BehaviorTimeSeriesRequest": {
      "type": "object",
      "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"
        },
        "granularity": {
          "type": "string",
          "enum": [
            "minute",
            "hour",
            "day",
            "week"
          ],
          "default": "day",
          "description": "Bucket size.",
          "example": "hour"
        },
        "group_by": {
          "type": "string",
          "enum": [
            "behavior",
            "polarity"
          ],
          "default": "behavior",
          "description": "`behavior` returns one series per behavior. `polarity` sums them into one series per polarity.",
          "example": "behavior"
        },
        "behaviors": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Only include these behavior keys (built-in names or custom behavior IDs). Omit for every behavior.",
          "example": [
            "refusal",
            "instruction_miss"
          ]
        }
      }
    }
  },
  "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"
      }
    }
  }
}