> ## Documentation Index
> Fetch the complete documentation index at: https://revise.io/developer/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Job lifecycle and limits

> Poll, cancel, and resume work, and control execution budgets.

A `202` response confirms submission, not completion. Save the job ID and idempotency key. Poll the matching get endpoint or subscribe to [webhooks](/developer/docs/developer/docs/revise-api/webhooks).

| Status | Next step |
| - | - |
| `queued`, `running` | Keep polling, at least one second apart. Honor `Retry-After` when present. |
| `succeeded` | Inspect the receipt and download its artifacts before expiry. Prompts can still report partial completion. |
| `failed`, `cancelled` | Work has stopped. Inspect `error` and settled usage. |
| `paused` | Prompt-only state. Resume with higher budgets or cancel. |

## Work and spending limits

Both creation endpoints accept `limits`:

| Field | Default | Meaning |
| - | - | - |
| `max_platform_cost_usd` | No cap | Positive amount only. Prompt base fee plus tool CPU, or conversion flat/page fees. |
| `max_inference_cost_usd` | No cap | Positive amount only. Observed inference spending threshold. With your provider key, it measures provider spend even though Revise does not bill that inference. |
| `max_seconds` | `900` | Work budget in seconds; accepted range 120–3600. Starts when a worker begins the job, excluding queue time. |

Use decimal strings for money. Platform limits must cover at least the applicable base fee, conversion fee, or one scan page. Scans also check that the complete document's page fee fits before inference.

Prompt thresholds stop new model calls based on observed usage. They are **soft limits**. An active response, tool, or export can finish past a threshold. Inspect `incomplete` and `stop_reason` for successful partial prompts. Client timeouts are separate waiting budgets and do not cap billing.

## Queue and concurrency

Prompts and conversions share the account's queue and worker allocation. New console accounts default to one running job and up to 100 queued jobs; account settings can differ. Additional jobs wait for a slot. A paused prompt holds an account slot until resumed, cancelled, or expired.

A full queue returns `429 account_queue_full`. Transfer/API capacity can return `503 server_busy`. Apply bounded backoff with the same idempotency key. Jobs need a positive account balance both for admission and to start running; existing queued work can wait for a top-up. Contact [support](mailto:support@revise.io) for capacity requirements.

## Cancel and resume

Closing the connection or aborting a client request does **not** cancel a server job. Call `POST /v1/prompt/{id}/cancel` or `POST /v1/convert/{id}/cancel` with no body. Cancellation can return `running` at first. Keep polling until the job stops. Cancellation does not undo completed work.

A paused prompt expires after 24 hours if not resumed. To resume, send new **absolute** limits. Omit a spending limit to remove that cap. Neither may decrease, and at least one must increase or be removed. The job keeps its ID and incurs no second base fee. The resume body does not accept `max_seconds`. Conversions cannot be resumed.

## Wait for an existing job

```ts theme={null}
import { ReviseClient } from "@reviseio/api";

const revise = new ReviseClient({ apiKey: process.env.REVISE_API_KEY! });
const result = await revise.prompts.wait("prompt_REPLACE_ME", {
  timeoutMs: 120_000,
  pollIntervalMs: 1_000,
});
if (result.status === "succeeded") {
  console.log(result.incomplete, result.artifacts);
} else {
  console.log(result.status, result.error);
}
```

`wait` returns paused, failed, and cancelled receipts. `run`, `edit`, and `convert` require success and throw `ReviseJobError` for those outcomes. All still require checking partial-completion fields on successful prompts.

The `edit`/`convert` deadline covers source resolution, upload, submission, and polling. A returned `Source` downloads later with its own signal. Pass the same external signal to both operations when you need one deadline for the whole workflow.

## Request history

Prompt and conversion lists return newest-first pages with `data` and `next_cursor`. The default page size is 20, maximum 100; `next_cursor: null` ends pagination. Repeat the same filters on each page. Status is live, so pages are not a frozen snapshot.

Prompt lists support status, conversation, submitting key, creation-time, and metadata filters. Conversion lists support status only, plus pagination. Use [usage reports](/developer/docs/developer/docs/revise-api/pricing#usage-reports) for settled cost aggregation by completion time.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.