Cancel Job

Cancel an in-progress or queued job.

Returns the updated job with status ‘cancelled’.

POST /v1/jobs/{job_id}/cancel

python

from retab import Retab

client = Retab()

# Cancel a queued or in-progress job
cancelled_job = client.jobs.cancel("job_V1StGXR8_Z5jdHi6B-myT")

print(f"Status: {cancelled_job.status}")  # cancelled

200

{
  "id": "job_V1StGXR8_Z5jdHi6B-myT",
  "object": "job",
  "status": "cancelled",
  "endpoint": "/v1/documents/extract",
  "request": {
    "document": {
      "filename": "invoice.pdf",
      "url": "data:application/pdf;base64,..."
    },
    "json_schema": { ... },
    "model": "retab-small"
  },
  "response": null,
  "error": null,
  "created_at": 1705420800,
  "started_at": null,
  "completed_at": 1705420850,
  "expires_at": 1706025600,
  "organization_id": "org_abc123",
  "metadata": {"batch_id": "batch_001"}
}

python

from retab import Retab

client = Retab()

# Cancel a queued or in-progress job
cancelled_job = client.jobs.cancel("job_V1StGXR8_Z5jdHi6B-myT")

print(f"Status: {cancelled_job.status}")  # cancelled

200

{
  "id": "job_V1StGXR8_Z5jdHi6B-myT",
  "object": "job",
  "status": "cancelled",
  "endpoint": "/v1/documents/extract",
  "request": {
    "document": {
      "filename": "invoice.pdf",
      "url": "data:application/pdf;base64,..."
    },
    "json_schema": { ... },
    "model": "retab-small"
  },
  "response": null,
  "error": null,
  "created_at": 1705420800,
  "started_at": null,
  "completed_at": 1705420850,
  "expires_at": 1706025600,
  "organization_id": "org_abc123",
  "metadata": {"batch_id": "batch_001"}
}

Path Parameters

job_id · string · required

The unique identifier of the job to cancel.

Response Fields

id · string

Unique identifier for the job.

object · string

Always "job".

status · string

Will be "cancelled" on success.

endpoint · string

The target endpoint for this job.

request · object

The original request body submitted.

response · null

Always null for cancelled jobs.

error · null

Always null for cancelled jobs.

created_at · integer

Unix timestamp when the job was created.

started_at · integer | null

Unix timestamp when processing started (if it had started).

completed_at · integer

Unix timestamp when the job was cancelled.

expires_at · integer

Unix timestamp when the job data will expire.

organization_id · string

The organization that owns this job.

metadata · object | null

User-provided metadata from job creation.

Cancellation Behavior

The cancellation behavior depends on the job’s current status:

Current Status	Behavior
validating	Immediately cancelled
queued	Removed from queue and cancelled
in_progress	Marked for cancellation; processing may complete if already finishing
completed	Returns 400 error - cannot cancel
failed	Returns 400 error - cannot cancel
cancelled	Returns 400 error - already cancelled
expired	Returns 400 error - cannot cancel

Jobs that are in_progress may still complete if the cancellation request arrives after processing has finished but before the status is updated. Always check the final status of the returned job object.

Use Cases

Cancel a Batch of Jobs

Python

# Cancel all queued jobs from a specific batch
jobs = client.jobs.list(status="queued")
for job in jobs.data:
    if job.metadata and job.metadata.get("batch_id") == "batch_001":
        try:
            client.jobs.cancel(job.id)
            print(f"Cancelled {job.id}")
        except Exception as e:
            print(f"Failed to cancel {job.id}: {e}")

Timeout-based Cancellation

Python

import time

job = client.jobs.create(endpoint="/v1/documents/extract", request={...})
start_time = time.time()
timeout = 60  # 60 seconds

while job.status not in ("completed", "failed", "cancelled", "expired"):
    if time.time() - start_time > timeout:
        job = client.jobs.cancel(job.id)
        print("Job cancelled due to timeout")
        break
    time.sleep(2)
    job = client.jobs.retrieve(job.id)

Authorizations

Api-Key · string · header · required

Path Parameters

job_id · string · required

Query Parameters

access_token · string | null

Response

200

application/json

Successful Response

Core Job object following OpenAI-style specification.

Represents a single asynchronous job that can be polled for status and result retrieval.

endpoint · enum<string> · required

Available options: /v1/documents/extract, /v1/documents/parse, /v1/documents/split, /v1/documents/classify, /v1/schemas/generate, /v1/edit/agent/fill, /v1/edit/templates/fill, /v1/edit/templates/generate, /v1/projects/extract

request · Request · object · required

organization_id · string · required

id · string

object · string · default: job

Allowed value: "job"

status · enum<string> · default: validating

Available options: validating, queued, in_progress, completed, failed, cancelled, expired

response · JobResponse · object

Response stored when job completes successfully.

Show child attributes

error · JobError · object

Error details when job fails.

Show child attributes

created_at · integer

started_at · integer | null

completed_at · integer | null

expires_at · integer

metadata · Metadata · object

Show child attributes

cloud_task_name · string | null

cancelled · boolean · default: false