---
title: "List connector dead letters"
method: GET
path: "/runs/{runId}/deadletters"
tags: ["Runs"]
---

# List connector dead letters

`GET /runs/{runId}/deadletters`

Lists failed items captured for a run after validation, transformation, or destination
delivery failure. Dead letters should reference retained payloads rather than embedding
them by default so retention and sensitivity policy can control access.

## Path parameters

- `runId` string, uuid, required — Stable identifier for a connector route or operation run.

## Query parameters

- `page` integer
- `size` integer

## Response `200`

Paged connector dead letters.

- ConnectorDeadLetterPage — Page of connector dead letters.
  - `data` ConnectorDeadLetter[], required
    - `deadLetterId` string, uuid, required — Stable dead-letter identifier.
    - `runId` string, uuid, required — Stable identifier for a connector route or operation run.
    - `routeId` string, uuid — Stable identifier for a connector route.
    - `connectorInstanceId` string, uuid — Stable platform identifier for a configured connector instance.
    - `bindingId` string, uuid — Stable identifier for a connector operation binding.
    - `connectorResourceId` string, uuid — Stable identifier for a resource attached to a connector instance.
    - `operationKind` 'READ' | 'WRITE' | 'UPDATE' | 'DELETE' | 'UPSERT' | 'QUERY' | 'SEARCH' | 'IMPORT' | 'EXPORT' | 'INVOKE' | 'DISCOVER' | 'VALIDATE' — Reusable operation taxonomy shared by connectors, inventory, policy, and workflows. The operation kind is logical; connector-local details live in operationName.
    - `reason` string, required — Failure reason captured by the connector runtime.
    - `payloadRef` string — Reference to a retained failed payload, if storage policy allows it.
    - `createdAt` string, date-time, required — Dead-letter creation timestamp.
    - `metadata` StringMap — Small string-only metadata map for labels, ownership, routing hints, and implementation-specific annotations. Use first-class fields for contractually significant data.
    - `createdByUserId` string — Optional user id associated with the failed item capture.
    - `deletedAt` string, date-time — Soft-delete timestamp, if the dead letter is hidden after retention handling.
  - `pagination` Page, required — Pagination metadata emitted with each paged response under the `pagination` property.
    - `limit` integer, required — Maximum number of records requested for this page.
    - `offset` integer, required — Zero-based offset of the first record in this page.
    - `page` integer, required — Zero-based page index derived from offset and limit.
    - `size` integer, required — Effective page size.
    - `total` integer, required — Total number of matching records.
    - `totalPages` integer, required — Total number of available pages.
    - `hasMore` boolean, required — Whether another page is available after this page.

## Other responses

- `401` — Authentication is required.
- `404` — The requested resource was not found.

---

[API](https://skmtc.net/sphereon-opensource/apis/connector-integration-profile-api.md) · [All operations](https://skmtc.net/sphereon-opensource/apis/connector-integration-profile-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sphereon-opensource/connector-integration-profile-api/revisions/60cb8c70871b/schema)