Job lifecycle and limits

A successful submission means the request was admitted, not necessarily completed. Save its ID and idempotency key before moving on. Poll the matching get endpoint or subscribe to webhooks.

Status	Next step
`queued`, `running`	Keep waiting; honor `Retry-After`.
`succeeded`	Inspect the receipt, then retrieve its artifacts.
`failed`	Inspect `error` and usage.
`cancelled`	Work has stopped; inspect its receipt.
`paused`	Prompt-only state. Inspect the reason and explicitly resume if appropriate.

Prompts and conversions have separate list/get endpoints. List endpoints return their server page and, where supported, next_cursor. Pass the cursor with the same filters for the next page. Date filters use RFC3339 strings. Metadata filters use query parameters such as metadata[customer]=acme.

Limits and cancellation

limits controls server work and cost thresholds. Dollar amounts in responses are exact decimal strings. Limits are soft: an active model response, tool, or export can finish beyond a threshold. A client timeout is a separate waiting budget and does not cap billing or issue a refund. Closing your connection or aborting a client request does not cancel the server job. Use POST /v1/prompt/{id}/cancel or POST /v1/convert/{id}/cancel explicitly, then inspect the returned status. Eligible paused prompts can resume through POST /v1/prompt/{id}/resume. Supply both max_platform_cost_usd and max_inference_cost_usd as new absolute limits, not increments. The resume body does not accept max_seconds.

TypeScript: wait on an existing request

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.artifacts);
} else {
  console.log(result.status, result.error);
}

wait returns paused/failed/cancelled receipts for inspection. run, edit, and convert require success and throw ReviseJobError for those outcomes. Successful partial prompts remain successful; inspect incomplete and stop_reason. The edit/convert helper 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 end-to-end deadline.

Getting started

Guides

REST reference

Limits and cancellation

TypeScript: wait on an existing request

​Limits and cancellation

​TypeScript: wait on an existing request

Limits and cancellation

TypeScript: wait on an existing request