Skip to main content
POST
/
v1
/
jobs
/
{job_id}
/
cancel
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

{
  "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"}
}

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

{
  "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 StatusBehavior
validatingImmediately cancelled
queuedRemoved from queue and cancelled
in_progressMarked for cancellation; processing may complete if already finishing
completedReturns 400 error - cannot cancel
failedReturns 400 error - cannot cancel
cancelledReturns 400 error - already cancelled
expiredReturns 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.
If cancellation races with a concurrent state transition, Retab may return 409. In that case, retrieve the job again and decide whether another cancel attempt is still needed.

​
Use Cases

​
Cancel a Batch of Jobs

# 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

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

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/evals/extract/process,
/v1/evals/split/process,
/v1/evals/classify/process,
/v1/evals/extract/extract,
/v1/evals/extract/split
​
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
​
error
JobError · object

Error details when job fails.

​
warnings
JobWarning · object[] | null
​
created_at
integer
​
started_at
integer | null
​
completed_at
integer | null
​
expires_at
integer
​
metadata
Metadata · object
​
cloud_task_name
string | null
​
cancelled
boolean
default:false
​
attempt_count
integer
default:0
​
last_attempt_at
integer | null
​
last_failure_code
string | null
​
request
Request · object
​
response
JobResponse · object

Response stored when job completes successfully.

​
request_gcs_paths
null