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/extractions",
  "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,
  "metadata": {"batch_id": "batch_001"}
}

Documentation Index

Fetch the complete documentation index at: https://docs.retab.com/llms.txt

Use this file to discover all available pages before exploring further.

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/extractions",
  "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,
  "metadata": {"batch_id": "batch_001"}
}

​
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/extractions", 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.get(job.id)

Authorizations

​
Api-Key
string
header
required

Path Parameters

​
job_id
string
required

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/extractions,
/v1/parses,
/v1/splits,
/v1/partitions,
/v1/classifications,
/v1/schemas/generate,
/v1/edits,
/v1/edits/templates/generate,
/v1/evals/extract/process,
/v1/evals/extract/extract,
/v1/evals/extract/split
​
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
string | null
​
started_at
string | null
​
completed_at
string | null
​
expires_at
string | null
​
metadata
Metadata · object
​
cancelled
boolean
default:false
​
attempt_count
integer
default:0
​
last_attempt_at
string | null
​
last_failure_code
string | null
​
request
Request · object
​
response
JobResult · object

Public response returned when job completes successfully.