---
title: "POST /uploads/{id}/factor-agent/jobs/{documentJobId}/cancel"
method: POST
path: "/uploads/{id}/factor-agent/jobs/{documentJobId}/cancel"
tags: ["Uploads"]
---

# POST /uploads/{id}/factor-agent/jobs/{documentJobId}/cancel

`POST /uploads/{id}/factor-agent/jobs/{documentJobId}/cancel`

Cancel one of the upload's document jobs, with the job read's auth and scoping, whatever DOCUMENT_JOBS_ENABLED says. A queued job (or one backing off after a failure, which no delivery holds) ends cancelled at once; a running job is flagged (cancelRequested) and its delivery ends it cancelled between units, never inside one. A cancelled analysis ends "error" with the message "Cancelled", keeping the rows its finished units wrote; Re Analysis reads the document again. A cancelled submit keeps the records its committed chunks wrote and is settled exactly as a failed submit, so the upload records what remains. A GreenBot chat waiting on the job is told it was cancelled. Repeating the cancel answers the same way. A job already past its last unit (a submit whose chunks all committed, an analysis in its finish) is not stopped: its finish runs and it ends succeeded or failed (e.g. MONEY_UNRECONCILED), so a client polls until any terminal status.

## Path parameters

- `id` integer, required
- `documentJobId` string, required

## Response `202`

The job after the cancel: cancelled, or still queued or running with cancelRequested true until its delivery ends it.

- DocumentJobResponse
  - `data` DocumentJob, required
    - `cancelRequested` boolean — A cancel stands for this live job: its delivery ends it cancelled between units. Absent once the job has ended, and on a job never asked to stop.
    - `createdAt` string, date-time, required
    - `error` string
    - `errorCode` string — Why a failed job failed, e.g. ANALYSIS_ALREADY_STARTED, ANALYSIS_CHANGED, CONFIRMATION_REQUIRED, NOTHING_TO_SUBMIT, PROMPT_REQUIRED, PROMPT_TOO_LONG, FACTOR_AGENT_FAILED, ANALYSIS_FAILED, INVALID_STATE, NOT_FOUND, INTERRUPTED (three deliveries ended without a word), RETRIES_EXHAUSTED (six failures worth retrying in a row), DISPATCH_FAILED (no delivery came for 30 minutes), DOCUMENT_TOO_LARGE (an analysis of a document over 25,000 rows, or whose extracted data is over 64 MiB; the message says which), ROW_EXCLUDED (a submit job that met a row a reviewer excluded), SOURCE_TOTAL_UNRECONCILED (a submit of an analysis whose money does not tie, or of a ledger one of whose non-carbon records was deleted since its analysis: the message names how many; nothing is submitted), MONEY_UNRECONCILED (money that does not tie in a ledger: a ledger store whose stored rows do not hold the read's money, or a ledger submit whose records and unsubmitted rows do not add up to its total, the message naming any missing records; the committed rows stay, and the upload reads unsubmitted), LEDGER_CATEGORIES_OVER_LIMIT (a factor catalog over the 500 categories a ledger's account decisions take). A cancelled job's is CANCELLED, with the error "Cancelled".
    - `finishedAt` string, date-time
    - `jobId` string, required
    - `kind` 'analyze' | 'submit', required
    - `progress` DocumentJobProgress
      - `done` integer, required — Rows done.
      - `message` string
      - `phase` string, required
      - `total` integer, required — Rows to do.
    - `result` object — A finished job's result. A submit job's is the submit result, whose emission counts only the emission rows the job inserted (the synchronous submit's counts every row it submitted).
    - `startedAt` string, date-time
    - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled', required
    - `uploadId` integer, required

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `409` — The job succeeded or failed (DOCUMENT_JOB_FINISHED; details carry jobId and status)

## Changes

- **2026-10-02** `766c2a40e369` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/greentally/apis/esgai-api/changes/uploads/:id/factor-agent/jobs/:documentJobId/cancel/post.md)

---

[API](https://skmtc.dev/greentally/apis/esgai-api.md) · [All operations](https://skmtc.dev/greentally/apis/esgai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/greentally/apis/esgai-api/revisions/4189686230ca?raw)