Skip to Content

List error groups

POSThttps://api.respan.ai/api/pulses/errors/

Lists failed spans grouped by fingerprint, most failures first, with each group’s reach and triage state. Counts come from a rollup refreshed every 10 minutes, so the range is widened to whole hours.

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
When a flat key and filters narrow the same field, filters wins.
Reference: #/components/schemas/ErrorGroupListRequest
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"
error_class string Optional
Only this error class. For several values or is not, use filters.
error_class (allOf 1) string Schema variant
Normalized cause of the failure, assigned when the span is stored.
Reference: #/components/schemas/ErrorClass
Allowed: "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 Optional
Only errors with this fault. none selects client cancellations.
Allowed: "user", "respan", "provider", "none"
Example: "provider"
provider string Optional
Only errors from this provider ID.
Example: "openai"
status integer Optional
Only errors with this HTTP status code.
Example: 429
filters object Optional
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.
Reference: #/components/schemas/ErrorGroupFilters
Additional properties are not allowed
Example: {"fault_domain":{"operator":"","value":["provider","respan"]}}
filters.error_class object Optional
Reference: #/components/schemas/ErrorGroupFilterCondition
filters.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
One value or a list. Required unless operator is empty or not_empty.
Example: ["provider_rate_limit","provider_overloaded"]
filters.error_class.value (oneOf 1) string Schema variant
-
filters.error_class.value (oneOf 2) integer Schema variant
-
filters.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 variant
-
filters.error_class.value (oneOf 3)[] (oneOf 2) integer Schema variant
-
filters.fault_domain object Optional
Reference: #/components/schemas/ErrorGroupFilterCondition
filters.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
One value or a list. Required unless operator is empty or not_empty.
Example: ["provider_rate_limit","provider_overloaded"]
filters.fault_domain.value (oneOf 1) string Schema variant
-
filters.fault_domain.value (oneOf 2) integer Schema variant
-
filters.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 variant
-
filters.fault_domain.value (oneOf 3)[] (oneOf 2) integer Schema variant
-
filters.provider_id object Optional
Reference: #/components/schemas/ErrorGroupFilterCondition
filters.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
One value or a list. Required unless operator is empty or not_empty.
Example: ["provider_rate_limit","provider_overloaded"]
filters.provider_id.value (oneOf 1) string Schema variant
-
filters.provider_id.value (oneOf 2) integer Schema variant
-
filters.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 variant
-
filters.provider_id.value (oneOf 3)[] (oneOf 2) integer Schema variant
-
filters.status_code object Optional
Reference: #/components/schemas/ErrorGroupFilterCondition
filters.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
One value or a list. Required unless operator is empty or not_empty.
Example: ["provider_rate_limit","provider_overloaded"]
filters.status_code.value (oneOf 1) string Schema variant
-
filters.status_code.value (oneOf 2) integer Schema variant
-
filters.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 variant
-
filters.status_code.value (oneOf 3)[] (oneOf 2) integer Schema variant
-

OpenAPI request schema

{
  "$ref": "#/components/schemas/ErrorGroupListRequest"
}
Example
JSON
{ "start_time": "2026-09-30T00:00:00Z", "end_time": "2026-10-01T00:00:00Z", "environment": "prod", "filters": { "fault_domain": { "operator": "", "value": [ "provider", "respan" ] } } }

Responses

200

Error groups for the range.

application/json

Field Type Requirement Description and constraints
$ object Body
Reference: #/components/schemas/ErrorGroupList
issues array<object> Required in parent
Up to 200 error groups, most failures first. There is no pagination.
issues[] object Array item
Failed spans that share one fingerprint.
Reference: #/components/schemas/ErrorGroup
issues[].fingerprint string Required in parent
Error group ID: a hash of error class, provider, endpoint and status code. 16 uppercase hex characters.
Example: "9F3B2C1D4E5A6B7C"
issues[].title string Required in parent
Readable name: error class, provider and endpoint, and status code.
Example: "provider_rate_limit · openai chat/completions · 429"
issues[].error_class string Required in parent
Normalized cause of the failure, assigned when the span is stored.
Reference: #/components/schemas/ErrorClass
Allowed: "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"
issues[].fault_domain string Required in parent
Whose fault the failure is, derived from error_class: user (your requests or your own provider keys), provider (the upstream provider), respan (Respan’s gateway or managed capacity), or none (client cancellations).
Reference: #/components/schemas/ErrorFaultDomain
Allowed: "user", "respan", "provider", "none"
Example: "respan"
issues[].level string Required in parent
Respan’s ops alert level for the error class: ops_page for errors Respan pages its on-call for, ops_log for the rest, none for cancellations.
Allowed: "none", "ops_log", "ops_page"
Example: "ops_page"
issues[].provider string Required in parent
Provider ID.
Example: "openai"
issues[].endpoint string Required in parent
Upstream operation, such as chat/completions, responses or embeddings.
Example: "chat/completions"
issues[].status integer Required in parent
HTTP status code.
Example: 429
issues[].count integer Required in parent
Failed spans in the group in the time range.
Example: 318
issues[].first_seen string Required in parent
First failure in the range. UTC, ISO 8601 without a timezone suffix.
Example: "2026-09-30T02:14:51.004112"
issues[].last_seen string Required in parent
Latest failure in the range. UTC, ISO 8601 without a timezone suffix.
Example: "2026-09-30T23:58:12.771045"
issues[].affected_customers integer Required in parent
Distinct customer_identifier values among the failures. Spans without one count as one value.
Example: 41
issues[].affected_models integer Required in parent
Distinct models among the failures.
Example: 2
issues[].resolution string Required in parent
Triage state. Groups you haven’t triaged are unresolved.
Reference: #/components/schemas/ErrorResolutionStatus
Allowed: "unresolved", "resolved", "ignored"
Example: "unresolved"
total_issues integer Required in parent
Error groups in the range, including any past the first 200.
Example: 12
total_errors integer Required in parent
Failed spans across all groups in the range.
Example: 1405

OpenAPI response schema

{
  "$ref": "#/components/schemas/ErrorGroupList"
}
Example
JSON
{ "issues": [ { "fingerprint": "9F3B2C1D4E5A6B7C", "title": "provider_rate_limit · openai chat/completions · 429", "error_class": "provider_rate_limit", "fault_domain": "respan", "level": "ops_page", "provider": "openai", "endpoint": "chat/completions", "status": 429, "count": 318, "first_seen": "2026-09-30T02:14:51.004112", "last_seen": "2026-09-30T23:58:12.771045", "affected_customers": 41, "affected_models": 2, "resolution": "unresolved" } ], "total_issues": 1, "total_errors": 318 }

400

A filters key is not supported, or its operator or value is invalid. The body maps the key to its error.

application/json

Field Type Requirement Description and constraints
$ object Body
-
$.<key> array<string> Map value
-
$.<key>[] string Array item
-

OpenAPI response schema

{
  "type": "object",
  "additionalProperties": {
    "type": "array",
    "items": {
      "type": "string"
    }
  }
}
Example
JSON
{ "provider": [ "Unsupported filter key for this resource." ] }

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 error groups",
  "operationId": "listErrorGroups",
  "tags": [
    "Error Groups"
  ],
  "description": "Lists failed spans grouped by fingerprint, most failures first, with each group's reach and triage state. Counts come from a rollup refreshed every 10 minutes, so the range is widened to whole hours.",
  "requestBody": {
    "required": false,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ErrorGroupListRequest"
        },
        "example": {
          "start_time": "2026-09-30T00:00:00Z",
          "end_time": "2026-10-01T00:00:00Z",
          "environment": "prod",
          "filters": {
            "fault_domain": {
              "operator": "",
              "value": [
                "provider",
                "respan"
              ]
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Error groups for the range.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorGroupList"
          },
          "example": {
            "issues": [
              {
                "fingerprint": "9F3B2C1D4E5A6B7C",
                "title": "provider_rate_limit · openai chat/completions · 429",
                "error_class": "provider_rate_limit",
                "fault_domain": "respan",
                "level": "ops_page",
                "provider": "openai",
                "endpoint": "chat/completions",
                "status": 429,
                "count": 318,
                "first_seen": "2026-09-30T02:14:51.004112",
                "last_seen": "2026-09-30T23:58:12.771045",
                "affected_customers": 41,
                "affected_models": 2,
                "resolution": "unresolved"
              }
            ],
            "total_issues": 1,
            "total_errors": 318
          }
        }
      }
    },
    "400": {
      "description": "A `filters` key is not supported, or its operator or value is invalid. The body maps the key to its error.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "example": {
            "provider": [
              "Unsupported filter key for this resource."
            ]
          }
        }
      }
    },
    "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"
    },
    "ErrorFaultDomain": {
      "type": "string",
      "enum": [
        "user",
        "respan",
        "provider",
        "none"
      ],
      "description": "Whose fault the failure is, derived from `error_class`: `user` (your requests or your own provider keys), `provider` (the upstream provider), `respan` (Respan's gateway or managed capacity), or `none` (client cancellations).",
      "example": "respan"
    },
    "ErrorGroup": {
      "type": "object",
      "description": "Failed spans that share one fingerprint.",
      "required": [
        "fingerprint",
        "title",
        "error_class",
        "fault_domain",
        "level",
        "provider",
        "endpoint",
        "status",
        "count",
        "first_seen",
        "last_seen",
        "affected_customers",
        "affected_models",
        "resolution"
      ],
      "properties": {
        "fingerprint": {
          "type": "string",
          "description": "Error group ID: a hash of error class, provider, endpoint and status code. 16 uppercase hex characters.",
          "example": "9F3B2C1D4E5A6B7C"
        },
        "title": {
          "type": "string",
          "description": "Readable name: error class, provider and endpoint, and status code.",
          "example": "provider_rate_limit · openai chat/completions · 429"
        },
        "error_class": {
          "$ref": "#/components/schemas/ErrorClass"
        },
        "fault_domain": {
          "$ref": "#/components/schemas/ErrorFaultDomain"
        },
        "level": {
          "type": "string",
          "enum": [
            "none",
            "ops_log",
            "ops_page"
          ],
          "description": "Respan's ops alert level for the error class: `ops_page` for errors Respan pages its on-call for, `ops_log` for the rest, `none` for cancellations.",
          "example": "ops_page"
        },
        "provider": {
          "type": "string",
          "description": "Provider ID.",
          "example": "openai"
        },
        "endpoint": {
          "type": "string",
          "description": "Upstream operation, such as `chat/completions`, `responses` or `embeddings`.",
          "example": "chat/completions"
        },
        "status": {
          "type": "integer",
          "description": "HTTP status code.",
          "example": 429
        },
        "count": {
          "type": "integer",
          "description": "Failed spans in the group in the time range.",
          "example": 318
        },
        "first_seen": {
          "type": "string",
          "description": "First failure in the range. UTC, ISO 8601 without a timezone suffix.",
          "example": "2026-09-30T02:14:51.004112"
        },
        "last_seen": {
          "type": "string",
          "description": "Latest failure in the range. UTC, ISO 8601 without a timezone suffix.",
          "example": "2026-09-30T23:58:12.771045"
        },
        "affected_customers": {
          "type": "integer",
          "description": "Distinct `customer_identifier` values among the failures. Spans without one count as one value.",
          "example": 41
        },
        "affected_models": {
          "type": "integer",
          "description": "Distinct models among the failures.",
          "example": 2
        },
        "resolution": {
          "$ref": "#/components/schemas/ErrorResolutionStatus"
        }
      }
    },
    "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"
          ]
        }
      }
    },
    "ErrorGroupList": {
      "type": "object",
      "required": [
        "issues",
        "total_issues",
        "total_errors"
      ],
      "properties": {
        "issues": {
          "type": "array",
          "description": "Up to 200 error groups, most failures first. There is no pagination.",
          "items": {
            "$ref": "#/components/schemas/ErrorGroup"
          }
        },
        "total_issues": {
          "type": "integer",
          "description": "Error groups in the range, including any past the first 200.",
          "example": 12
        },
        "total_errors": {
          "type": "integer",
          "description": "Failed spans across all groups in the range.",
          "example": 1405
        }
      }
    },
    "ErrorGroupListRequest": {
      "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"
        },
        "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"
        }
      }
    },
    "ErrorResolutionStatus": {
      "type": "string",
      "enum": [
        "unresolved",
        "resolved",
        "ignored"
      ],
      "description": "Triage state. Groups you haven't triaged are `unresolved`.",
      "example": "unresolved"
    }
  },
  "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"
      }
    }
  }
}