Get error signals over time
https://api.respan.ai/api/pulses/errors/timeseries/Returns failed spans per time bucket, split by a field such as error class, provider or error group. Reads spans directly, so range edges are exact.
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_KEYRequest body
The request body is optional.
application/json
$ object Optional body
filters narrow the same field, filters wins.Reference:
#/components/schemas/ErrorTimeSeriesRequeststart_time string OptionalFormat:
date-timeExample:
"2026-09-24T00:00:00Z"end_time string OptionalFormat:
date-timeExample:
"2026-10-01T00:00:00Z"environment string Optionalprod or test. Omit it to include every environment.Example:
"prod"granularity string OptionalAllowed:
"minute", "hour", "day", "week"Default:
dayExample:
"hour"group_by string Optionalissue groups by error group fingerprint, provider by provider ID, and status by HTTP status code.Allowed:
"customer_identifier", "deployment_name", "endpoint", "error_class", "fault_domain", "issue", "model", "provider", "status"Default:
error_classExample:
"error_class"error_class string Optional
is not, use filters.error_class (allOf 1) string Schema variantReference:
#/components/schemas/ErrorClassAllowed:
"user_invalid_request", "user_auth_byok", "user_quota", "user_rate_limit", "user_content_policy", "user_context_window", "user_payload_too_large", "provider_down", "provider_overloaded", "provider_timeout", "provider_rate_limit", "respan_managed_auth", "respan_managed_billing", "respan_config", "respan_internal", "network_transient", "client_cancelled", "unknown"Example:
"provider_rate_limit"fault_domain string Optionalnone selects client cancellations.Allowed:
"user", "respan", "provider", "none"Example:
"provider"provider string OptionalExample:
"openai"status integer OptionalExample:
429filters object Optional
Reference:
#/components/schemas/ErrorGroupFiltersAdditional properties are not allowed
Example:
{"fault_domain":{"operator":"","value":["provider","respan"]}}filters.error_class object Optional
#/components/schemas/ErrorGroupFilterConditionfilters.error_class.operator string Optional"" (is any of), not (is none of), in, empty or not_empty. Allowed operators per key: error_class and fault_domain take "", not, in; provider_id takes "", not, empty, not_empty; status_code takes "", not.Allowed:
"", "not", "in", "empty", "not_empty"Default: “
Example:
""filters.error_class.value string or integer or array<string or integer> Optional
operator is empty or not_empty.Example:
["provider_rate_limit","provider_overloaded"]filters.error_class.value (oneOf 1) string Schema variantfilters.error_class.value (oneOf 2) integer Schema variantfilters.error_class.value (oneOf 3) array<string or integer> Schema variant
filters.error_class.value (oneOf 3)[] string or integer Array item
filters.error_class.value (oneOf 3)[] (oneOf 1) string Schema variantfilters.error_class.value (oneOf 3)[] (oneOf 2) integer Schema variantfilters.fault_domain object Optional
#/components/schemas/ErrorGroupFilterConditionfilters.fault_domain.operator string Optional"" (is any of), not (is none of), in, empty or not_empty. Allowed operators per key: error_class and fault_domain take "", not, in; provider_id takes "", not, empty, not_empty; status_code takes "", not.Allowed:
"", "not", "in", "empty", "not_empty"Default: “
Example:
""filters.fault_domain.value string or integer or array<string or integer> Optional
operator is empty or not_empty.Example:
["provider_rate_limit","provider_overloaded"]filters.fault_domain.value (oneOf 1) string Schema variantfilters.fault_domain.value (oneOf 2) integer Schema variantfilters.fault_domain.value (oneOf 3) array<string or integer> Schema variant
filters.fault_domain.value (oneOf 3)[] string or integer Array item
filters.fault_domain.value (oneOf 3)[] (oneOf 1) string Schema variantfilters.fault_domain.value (oneOf 3)[] (oneOf 2) integer Schema variantfilters.provider_id object Optional
#/components/schemas/ErrorGroupFilterConditionfilters.provider_id.operator string Optional"" (is any of), not (is none of), in, empty or not_empty. Allowed operators per key: error_class and fault_domain take "", not, in; provider_id takes "", not, empty, not_empty; status_code takes "", not.Allowed:
"", "not", "in", "empty", "not_empty"Default: “
Example:
""filters.provider_id.value string or integer or array<string or integer> Optional
operator is empty or not_empty.Example:
["provider_rate_limit","provider_overloaded"]filters.provider_id.value (oneOf 1) string Schema variantfilters.provider_id.value (oneOf 2) integer Schema variantfilters.provider_id.value (oneOf 3) array<string or integer> Schema variant
filters.provider_id.value (oneOf 3)[] string or integer Array item
filters.provider_id.value (oneOf 3)[] (oneOf 1) string Schema variantfilters.provider_id.value (oneOf 3)[] (oneOf 2) integer Schema variantfilters.status_code object Optional
#/components/schemas/ErrorGroupFilterConditionfilters.status_code.operator string Optional"" (is any of), not (is none of), in, empty or not_empty. Allowed operators per key: error_class and fault_domain take "", not, in; provider_id takes "", not, empty, not_empty; status_code takes "", not.Allowed:
"", "not", "in", "empty", "not_empty"Default: “
Example:
""filters.status_code.value string or integer or array<string or integer> Optional
operator is empty or not_empty.Example:
["provider_rate_limit","provider_overloaded"]filters.status_code.value (oneOf 1) string Schema variantfilters.status_code.value (oneOf 2) integer Schema variantfilters.status_code.value (oneOf 3) array<string or integer> Schema variant
filters.status_code.value (oneOf 3)[] string or integer Array item
filters.status_code.value (oneOf 3)[] (oneOf 1) string Schema variantfilters.status_code.value (oneOf 3)[] (oneOf 2) integer Schema variantOpenAPI request schema
{
"$ref": "#/components/schemas/ErrorTimeSeriesRequest"
}Example
{
"start_time": "2026-09-30T00:00:00Z",
"end_time": "2026-10-01T00:00:00Z",
"granularity": "hour",
"group_by": "error_class"
}Responses
200
Failed spans per bucket.
application/json
$ object Body
#/components/schemas/ErrorTimeSeriesgranularity string Required in parent"minute", "hour", "day", "week"Example:
"hour"group_by string Required in parent"customer_identifier", "deployment_name", "endpoint", "error_class", "fault_domain", "issue", "model", "provider", "status"Example:
"error_class"series array<object> Required in parent
bucket. Buckets with no failures are missing.series[] object Array item
#/components/schemas/ErrorTimeSeriesPointseries[].bucket string Required in parentYYYY-MM-DD) for week buckets. UTC, ISO 8601 without a timezone suffix.Example:
"2026-09-30T14:00:00"series[].series string or integer Required in parent
group_by field: an integer for status, else a string. Missing values are an empty string.Example:
"provider_rate_limit"series[].series (oneOf 1) string Schema variantseries[].series (oneOf 2) integer Schema variantseries[].count integer Required in parentExample:
27OpenAPI response schema
{
"$ref": "#/components/schemas/ErrorTimeSeries"
}Example
{
"granularity": "hour",
"group_by": "error_class",
"series": [
{
"bucket": "2026-09-30T14:00:00",
"series": "provider_rate_limit",
"count": 27
},
{
"bucket": "2026-09-30T14:00:00",
"series": "user_context_window",
"count": 4
},
{
"bucket": "2026-09-30T15:00:00",
"series": "provider_rate_limit",
"count": 31
}
]
}400
Invalid granularity, group_by or filters.
application/json
$ object BodyOpenAPI response schema
{
"type": "object",
"additionalProperties": true
}Example
{
"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).
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": "Get error signals over time",
"operationId": "getErrorTimeSeries",
"tags": [
"Error Groups"
],
"description": "Returns failed spans per time bucket, split by a field such as error class, provider or error group. Reads spans directly, so range edges are exact.",
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorTimeSeriesRequest"
},
"example": {
"start_time": "2026-09-30T00:00:00Z",
"end_time": "2026-10-01T00:00:00Z",
"granularity": "hour",
"group_by": "error_class"
}
}
}
},
"responses": {
"200": {
"description": "Failed spans per bucket.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorTimeSeries"
},
"example": {
"granularity": "hour",
"group_by": "error_class",
"series": [
{
"bucket": "2026-09-30T14:00:00",
"series": "provider_rate_limit",
"count": 27
},
{
"bucket": "2026-09-30T14:00:00",
"series": "user_context_window",
"count": 4
},
{
"bucket": "2026-09-30T15:00:00",
"series": "provider_rate_limit",
"count": 31
}
]
}
}
}
},
"400": {
"description": "Invalid `granularity`, `group_by` or `filters`.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
},
"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).",
"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": {
"ErrorClass": {
"type": "string",
"enum": [
"user_invalid_request",
"user_auth_byok",
"user_quota",
"user_rate_limit",
"user_content_policy",
"user_context_window",
"user_payload_too_large",
"provider_down",
"provider_overloaded",
"provider_timeout",
"provider_rate_limit",
"respan_managed_auth",
"respan_managed_billing",
"respan_config",
"respan_internal",
"network_transient",
"client_cancelled",
"unknown"
],
"description": "Normalized cause of the failure, assigned when the span is stored.",
"example": "provider_rate_limit"
},
"ErrorGroupFilterCondition": {
"type": "object",
"properties": {
"operator": {
"type": "string",
"enum": [
"",
"not",
"in",
"empty",
"not_empty"
],
"default": "",
"description": "`\"\"` (is any of), `not` (is none of), `in`, `empty` or `not_empty`. Allowed operators per key: `error_class` and `fault_domain` take `\"\"`, `not`, `in`; `provider_id` takes `\"\"`, `not`, `empty`, `not_empty`; `status_code` takes `\"\"`, `not`.",
"example": ""
},
"value": {
"description": "One value or a list. Required unless `operator` is `empty` or `not_empty`.",
"oneOf": [
{
"type": "string"
},
{
"type": "integer"
},
{
"type": "array",
"items": {
"oneOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
}
}
],
"example": [
"provider_rate_limit",
"provider_overloaded"
]
}
}
},
"ErrorGroupFilters": {
"type": "object",
"description": "Narrow the errors with the same filter shape as the Logs filter bar. Only these four keys are accepted; any other key is a 400.",
"properties": {
"error_class": {
"$ref": "#/components/schemas/ErrorGroupFilterCondition"
},
"fault_domain": {
"$ref": "#/components/schemas/ErrorGroupFilterCondition"
},
"provider_id": {
"$ref": "#/components/schemas/ErrorGroupFilterCondition"
},
"status_code": {
"$ref": "#/components/schemas/ErrorGroupFilterCondition"
}
},
"additionalProperties": false,
"example": {
"fault_domain": {
"operator": "",
"value": [
"provider",
"respan"
]
}
}
},
"ErrorTimeSeries": {
"type": "object",
"required": [
"granularity",
"group_by",
"series"
],
"properties": {
"granularity": {
"type": "string",
"enum": [
"minute",
"hour",
"day",
"week"
],
"example": "hour"
},
"group_by": {
"type": "string",
"enum": [
"customer_identifier",
"deployment_name",
"endpoint",
"error_class",
"fault_domain",
"issue",
"model",
"provider",
"status"
],
"example": "error_class"
},
"series": {
"type": "array",
"description": "Points ordered by `bucket`. Buckets with no failures are missing.",
"items": {
"$ref": "#/components/schemas/ErrorTimeSeriesPoint"
}
}
}
},
"ErrorTimeSeriesPoint": {
"type": "object",
"required": [
"bucket",
"series",
"count"
],
"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"
},
"series": {
"description": "Value of the `group_by` field: an integer for `status`, else a string. Missing values are an empty string.",
"oneOf": [
{
"type": "string"
},
{
"type": "integer"
}
],
"example": "provider_rate_limit"
},
"count": {
"type": "integer",
"description": "Failed spans in the bucket for this value.",
"example": 27
}
}
},
"ErrorTimeSeriesRequest": {
"type": "object",
"description": "When a flat key and `filters` narrow the same field, `filters` wins.",
"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": [
"customer_identifier",
"deployment_name",
"endpoint",
"error_class",
"fault_domain",
"issue",
"model",
"provider",
"status"
],
"default": "error_class",
"description": "Field to group by. `issue` groups by error group fingerprint, `provider` by provider ID, and `status` by HTTP status code.",
"example": "error_class"
},
"error_class": {
"allOf": [
{
"$ref": "#/components/schemas/ErrorClass"
}
],
"description": "Only this error class. For several values or `is not`, use `filters`."
},
"fault_domain": {
"type": "string",
"enum": [
"user",
"respan",
"provider",
"none"
],
"description": "Only errors with this fault. `none` selects client cancellations.",
"example": "provider"
},
"provider": {
"type": "string",
"description": "Only errors from this provider ID.",
"example": "openai"
},
"status": {
"type": "integer",
"description": "Only errors with this HTTP status code.",
"example": 429
},
"filters": {
"$ref": "#/components/schemas/ErrorGroupFilters"
}
}
}
},
"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"
}
}
}
}