> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # List dead-letter observations > Cross-tenant operator forensics: returns a keyset-paginated, reverse-chronological page of dead-letter observations captured from the delivery pipeline. This is an operator surface — it authorizes against an operator scope and carries no tenant context. The projection carries no secret, no customer endpoint URL, and no signing material. The `tenant_id_raw` field is an untrusted, best-effort capture surfaced for forensic value only. ## OpenAPI ````yaml en/openapi/v3-current/streaming-hub.yaml get /admin/dlq openapi: 3.1.0 info: title: Lerian Streaming Hub API version: v1.0.0 contact: email: contact@lerian.studio name: Lerian Studio url: https://lerian.studio license: name: Lerian Studio General License description: >- The Streaming Hub control-plane API. Streaming Hub is Lerian's managed event-delivery edge: it consumes CloudEvents from the platform's internal streaming backbone and fans them out to a tenant's own external destinations — webhooks, Amazon SQS, RabbitMQ, Amazon EventBridge, or a pull inbox. This API lets a tenant browse the manifest-fed event catalog, create and manage delivery subscriptions, verify and rotate their credentials, read delivery health, and pull entitled events. Errors use a flat `{"error":""}` envelope (a low-cardinality, machine-readable token — never RFC 9457 problem+json). Mutating operations require an `X-Idempotency` header for at-most-once semantics; a replayed request returns the original response byte-for-byte with `X-Idempotency-Replayed: true`. The catalog and the pull events surface are tenant-scoped through the bearer JWT; the operational probe endpoints (`/healthz`, `/readyz`, `/version`, `/runtime`, `/metrics`) are unauthenticated. Streaming Hub is closed source under the Lerian Studio General License. servers: - url: https://streaming-hub.sandbox.lerian.net security: - BearerAuth: [] tags: - name: Catalog description: Browse the manifest-fed catalog of event types available for subscription. - name: Subscriptions description: >- Create, read, update, and delete delivery subscriptions, and drive the destination verification lifecycle (ping, verify, credential, delegated grant, secret rotation, health). - name: Event Delivery description: >- Pull entitled events for a pull-sink subscription (cursor-as-acknowledgment read). - name: Admin description: Cross-tenant operator forensics. Requires an operator authorization scope. - name: Operational description: Unauthenticated liveness, readiness, build, runtime, and metrics probes. paths: /admin/dlq: get: tags: - Admin summary: List dead-letter observations description: >- Cross-tenant operator forensics: returns a keyset-paginated, reverse-chronological page of dead-letter observations captured from the delivery pipeline. This is an operator surface — it authorizes against an operator scope and carries no tenant context. The projection carries no secret, no customer endpoint URL, and no signing material. The `tenant_id_raw` field is an untrusted, best-effort capture surfaced for forensic value only. operationId: listDeadLetters parameters: - name: source_topic in: query required: false description: >- Optional filter on the source topic the failed delivery originated from. schema: type: string - name: error_class in: query required: false description: >- Optional filter on the transport error class. An unrecognized value returns `400 invalid_error_class`. schema: $ref: '#/components/schemas/DLQErrorClass' - name: after in: query required: false description: >- Keyset cursor — the `id` (UUIDv7) of the last row from the previous page. A malformed value returns `400 invalid_cursor`. schema: type: string format: uuid responses: '200': description: A page of dead-letter observations. content: application/json: schema: $ref: '#/components/schemas/DLQResponse' '400': description: >- A filter value was invalid. `error` is `invalid_error_class` (an unrecognized `error_class`) or `invalid_cursor` (a malformed `after`). content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: >- Authentication failed. On this operator surface the body is plain text (not the JSON error envelope) — unlike the `/v1` surface, the `/admin` group emits the 401 directly from the authorization middleware. content: text/plain: schema: type: string '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalError' security: - BearerAuth: [] components: schemas: DLQErrorClass: type: string description: The transport error class a dead-letter observation may be filtered on. enum: - serialization - validation - auth - topic_not_found - broker_unavailable - network_timeout - broker_overloaded - context_canceled - unknown DLQResponse: type: object additionalProperties: false properties: observations: type: array description: A page of dead-letter observations, reverse-chronological. items: $ref: '#/components/schemas/DLQObservation' nextCursor: type: string description: >- Keyset cursor for the next (older) page — the id of the last row. Empty when there are no further pages. examples: - 0192f1a0-0000-7000-8000-00000000d017 required: - observations - nextCursor Error: type: object additionalProperties: false description: >- The flat error envelope used across the `/v1` and `/admin` surfaces. It carries a single low-cardinality, machine-readable token and never leaks secret material or internal detail. (A `403` from the authorization decision point is the one exception — its body is plain text.) properties: error: type: string description: The machine-readable error token. examples: - not_found required: - error DLQObservation: type: object additionalProperties: false description: >- One dead-letter observation. Carries no secret, no customer endpoint URL, and no signing material. `tenant_id_raw` is an untrusted, best-effort capture surfaced for forensic value only. properties: source_topic: type: string description: The source topic the failed delivery originated from. examples: - lerian.streaming.transaction.created error_class: type: string description: The transport error class captured for the failed delivery. examples: - broker_unavailable error_message: type: string description: >- A sanitized error message (redacted at capture; never a secret or host:port). examples: - connection refused retry_count: type: integer description: The number of delivery attempts recorded before dead-lettering. examples: - 8 first_failure_at: type: string format: date-time description: When the first failure was observed (UTC, RFC 3339). examples: - '2026-06-05T09:00:00Z' producer_id: type: string description: The producer identity captured for the source event. examples: - midaz observed_at: type: string format: date-time description: When the dead-letter observation was recorded (UTC, RFC 3339). examples: - '2026-06-05T09:30:00Z' tenant_id_raw: type: string description: >- The untrusted captured tenant id. Forensic only — never an authorization or scoping input. examples: - tenant-acme required: - source_topic - error_class - error_message - retry_count - first_failure_at - producer_id - observed_at - tenant_id_raw responses: Forbidden: description: >- The authorization decision point denied the request. The body is plain text (not the JSON error envelope). content: text/plain: schema: type: string InternalError: description: >- An infrastructure fault. `error` is `internal_error` (sanitized; detail is logged, never returned). content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- A bearer JWT issued by plugin-auth (lib-auth). The tenant identity is resolved from the validated token claims; the `/v1` surface never reads a tenant from the body, path, or query. Machine callers obtain a token via the plugin-auth client-credentials flow. The `/admin` surface authorizes against an operator scope and carries no tenant context. ````