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.

​
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/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.

​
error
JobError · object

Error details when job fails.

​
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