Job lifecycle and limits

A 202 response confirms submission, not completion. Save the job ID and idempotency key. Poll the matching get endpoint or subscribe to 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 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

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 for settled cost aggregation by completion time.

Getting started

Guides

REST reference

Work and spending limits

Queue and concurrency

Cancel and resume

Wait for an existing job

Request history

​Work and spending limits

​Queue and concurrency

​Cancel and resume

​Wait for an existing job

​Request history

Work and spending limits

Queue and concurrency

Cancel and resume

Wait for an existing job

Request history