Retrieve Job

Retrieve a job by ID.

Returns the current status, timestamps, and result (if completed) or error (if failed).

GET /v1/jobs/{job_id}

python

from retab import Retab

client = Retab()

# Retrieve a job by ID
job = client.jobs.retrieve("job_V1StGXR8_Z5jdHi6B-myT")

print(f"Status: {job.status}")

if job.status == "completed":
    print(f"Result: {job.response.body}")
elif job.status == "failed":
    print(f"Error: {job.error.message}")

200 (queued)

{
  "id": "job_V1StGXR8_Z5jdHi6B-myT",
  "object": "job",
  "status": "queued",
  "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": null,
  "expires_at": 1706025600,
  "organization_id": "org_abc123",
  "metadata": {"batch_id": "batch_001"}
}

python

from retab import Retab

client = Retab()

# Retrieve a job by ID
job = client.jobs.retrieve("job_V1StGXR8_Z5jdHi6B-myT")

print(f"Status: {job.status}")

if job.status == "completed":
    print(f"Result: {job.response.body}")
elif job.status == "failed":
    print(f"Error: {job.error.message}")

200 (queued)

{
  "id": "job_V1StGXR8_Z5jdHi6B-myT",
  "object": "job",
  "status": "queued",
  "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": null,
  "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 retrieve.

Response Fields

id · string

Unique identifier for the job.

object · string

Always "job".

status · string

Current status of the job:

• validating - Request is being validated
• queued - Waiting in the processing queue
• in_progress - Currently being processed
• completed - Successfully finished
• failed - Execution failed
• cancelled - Cancelled by user
• expired - Job data has expired

endpoint · string

The target endpoint for this job.

request · object

The original request body submitted.

response · object | null

Present when status is completed. Contains:

Show properties

status_code · integer

HTTP status code from the target endpoint.

body · object

The response body from the target endpoint.

error · object | null

Present when status is failed. Contains:

Show properties

code · string

Error code identifying the type of failure.

message · string

Human-readable error message.

details · object | null

Additional error details when available.

created_at · integer

Unix timestamp when the job was created.

started_at · integer | null

Unix timestamp when processing started (null if not yet started).

completed_at · integer | null

Unix timestamp when the job reached a terminal status.

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.

Polling for Completion

Use polling to wait for a job to complete:

Python

import time

job = client.jobs.retrieve(job_id)
terminal_statuses = ("completed", "failed", "cancelled", "expired")

while job.status not in terminal_statuses:
    time.sleep(2)  # Wait 2 seconds between polls
    job = client.jobs.retrieve(job_id)

# Or use the helper method
job = client.jobs.wait_for_completion(job_id, poll_interval=2.0, timeout=300)

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