---
title: "Retry extraction for a failed/stuck document"
method: POST
path: "/internal/api/document/{document_id}/retry"
tags: ["DOCUMENT"]
---

# Retry extraction for a failed/stuck document

`POST /internal/api/document/{document_id}/retry`

## Request

- Base URL: `https://api.signalshq.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.signalshq.io/internal/api/document/{document_id}/retry`
- Auth: OAuth 2
  - Password
  - Token URL: `/auth/login`

Re-run extraction for a document whose extraction FAILED or got stuck (no review workflow / no editable fields). Creates a NEW extraction job for the document and re-extracts with its canonical type (or re-classifies if it was never classified). Idempotent under concurrency: a genuinely in-flight job is not duplicated, and a job left non-terminal by a killed worker stops blocking once it ages out. Does NOT change the document's type or supersede a prior review.

**Read the response body, not just the status.** This returns 202 whether or not work was enqueued; `status: SKIPPED` with the pre-existing `extraction_job_id` means the guard considered a job already in flight and nothing was queued.

`force=true` bypasses that guard outright — for a document an operator knows is dead but which has not yet aged out. Safe under concurrency: the extract task's execution claim makes a second dispatch skip rather than double-extract.

## Path parameters

- `document_id` string, uuid, required: Document ID to retry extraction for

## Query parameters

- `force` boolean: Bypass the in-flight guard and always create a new job. Use when a document is stuck behind a job whose worker died and the normal retry returns SKIPPED.

## Request body

- DocumentExtractionRequest: Request schema for document extraction response
  - `client_id` string, uuid, required: Client ID for the document

## Response `202`

Successful Response

- ReextractWithDocumentTypeResponse: Response schema for reextract-with-document-type (202 Accepted).
  - `document_id` string, uuid, required: Document ID
  - `extraction_job_id` string, uuid, required: Extraction job ID for polling status
  - `status` string, required: Initial job status (e.g. ACCEPTED)

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/signalshq/apis/signals-api.md) - [All operations](https://skmtc.dev/signalshq/apis/signals-api/llms.txt) - [OpenAPI document](https://skmtc.dev/signalshq/apis/signals-api/revisions/2c22af3b5576?raw)