---
title: "Process dead letters"
method: POST
path: "/v2/pipelines/{pipeline_key}/dead_letters/process"
tags: ["Pipeline Dead Letters"]
---

# Process dead letters

`POST /v2/pipelines/{pipeline_key}/dead_letters/process`

Processes dead letters by creating a new pipeline run. The run re-fetches the specified records from the source and sends them through the agent. A request without filters processes all pending dead letters.

## Path parameters

- `pipeline_key` string, required — The unique key for the pipeline. You can provide the key, or the platform generates one.

## Headers

- `Request-Timeout` integer
- `Request-Timeout-Millis` integer

## Request body

- ProcessPipelineDeadLetterEntriesRequest — Request to process dead letters. Filters select which dead letters to process. If no filters are provided, all pending dead letters are processed.
  - `source_record_ids` string[] — Specific source record IDs to process. If omitted, processes all matching dead letters.
  - `last_run_id` string — The unique identifier for a pipeline run.
  - `origin` 'pipeline' | 'manual' — How this dead letter was created.

## Response `201`

The created retry run.

- PipelineRun — A single execution of a pipeline. Each run fetches data from the source and creates one agent session per record. Each record is mapped 1:1 to a session.
  - `id` string, required — The unique identifier for a pipeline run.
  - `pipeline_key` string, required — The unique key for the pipeline. You can provide the key, or the platform generates one.
  - `agent_key` string, required — A unique key that identifies an agent.
  - `status` 'running' | 'completed' | 'failed' | 'cancelled', required — The status of a pipeline run.
  - `trigger_type` 'scheduled' | 'manual' | 'retry', required — What initiated the pipeline run.
  - `records_fetched` integer, required — Number of records discovered from the source in this run.
  - `records_processed` integer, required — Number of records successfully processed by the agent.
  - `records_failed` integer, required — Number of records that failed processing.
  - `error` string, nullable — Error details if the run failed.
  - `started_at` string, date-time, nullable — When the run started executing.
  - `completed_at` string, date-time, nullable — When the run finished.
  - `created_at` string, date-time, required — When the run was created.

## Other responses

- `400` — The request is malformed.
- `403` — Permissions do not allow processing dead letters for this pipeline.
- `404` — Pipeline not found.
- `409` — A run is already in progress for this pipeline.

---

[API](https://skmtc.net/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.net/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vectara/vectara-rest-api-v2/revisions/fca567a46b3a/schema)