Skip to main content
GET
/
v1
/
jobs
from retab import Retab

client = Retab()

# List all jobs
jobs_response = client.jobs.list()
for job in jobs_response.data:
    print(f"{job.id}: {job.status} - {job.endpoint}")

# List with filters and pagination
jobs_response = client.jobs.list(
    status="completed",
    limit=10
)

# Paginate through results
if jobs_response.has_more:
    next_page = client.jobs.list(
        after=jobs_response.last_id,
        limit=10
    )

{
  "object": "list",
  "data": [
    {
      "id": "job_V1StGXR8_Z5jdHi6B-myT",
      "object": "job",
      "status": "completed",
      "endpoint": "/v1/documents/extract",
      "request": { ... },
      "response": {
        "status_code": 200,
        "body": { ... }
      },
      "error": null,
      "created_at": 1705420810,
      "started_at": 1705420812,
      "completed_at": 1705420820,
      "expires_at": 1706025610,
      "organization_id": "org_abc123",
      "metadata": {"batch_id": "batch_001"}
    },
    {
      "id": "job_X2TuHYS9_A6keIj7C-nzU",
      "object": "job",
      "status": "queued",
      "endpoint": "/v1/documents/parse",
      "request": { ... },
      "response": null,
      "error": null,
      "created_at": 1705420800,
      "started_at": null,
      "completed_at": null,
      "expires_at": 1706025600,
      "organization_id": "org_abc123",
      "metadata": null
    }
  ],
  "first_id": "job_V1StGXR8_Z5jdHi6B-myT",
  "last_id": "job_X2TuHYS9_A6keIj7C-nzU",
  "has_more": true
}

from retab import Retab

client = Retab()

# List all jobs
jobs_response = client.jobs.list()
for job in jobs_response.data:
    print(f"{job.id}: {job.status} - {job.endpoint}")

# List with filters and pagination
jobs_response = client.jobs.list(
    status="completed",
    limit=10
)

# Paginate through results
if jobs_response.has_more:
    next_page = client.jobs.list(
        after=jobs_response.last_id,
        limit=10
    )

{
  "object": "list",
  "data": [
    {
      "id": "job_V1StGXR8_Z5jdHi6B-myT",
      "object": "job",
      "status": "completed",
      "endpoint": "/v1/documents/extract",
      "request": { ... },
      "response": {
        "status_code": 200,
        "body": { ... }
      },
      "error": null,
      "created_at": 1705420810,
      "started_at": 1705420812,
      "completed_at": 1705420820,
      "expires_at": 1706025610,
      "organization_id": "org_abc123",
      "metadata": {"batch_id": "batch_001"}
    },
    {
      "id": "job_X2TuHYS9_A6keIj7C-nzU",
      "object": "job",
      "status": "queued",
      "endpoint": "/v1/documents/parse",
      "request": { ... },
      "response": null,
      "error": null,
      "created_at": 1705420800,
      "started_at": null,
      "completed_at": null,
      "expires_at": 1706025600,
      "organization_id": "org_abc123",
      "metadata": null
    }
  ],
  "first_id": "job_V1StGXR8_Z5jdHi6B-myT",
  "last_id": "job_X2TuHYS9_A6keIj7C-nzU",
  "has_more": true
}

​
Query Parameters

​
after
string
Pagination cursor. Use the last_id from the previous response to get the next page.
​
limit
integer
default:"20"
Maximum number of jobs to return. Range: 1-100.
​
status
string
Filter by job status. Valid values:
  • validating
  • queued
  • in_progress
  • completed
  • failed
  • cancelled
  • expired

​
Response Fields

​
object
string
Always "list".
​
data
array
Array of Job objects, sorted by created_at descending (newest first).
​
first_id
string | null
ID of the first job in this page (null if empty).
​
last_id
string | null
ID of the last job in this page. Use as the after parameter for pagination.
​
has_more
boolean
Whether there are more results available.

​
Pagination

Jobs are returned in descending order by creation time (newest first). Use cursor-based pagination to iterate through all results: 
all_jobs = []
after = None

while True:
    response = client.jobs.list(after=after, limit=100)
    all_jobs.extend(response.data)

    if not response.has_more:
        break
    after = response.last_id

print(f"Total jobs: {len(all_jobs)}")

​
Filtering Examples

​
Monitor Active Jobs

# Get all jobs currently processing
in_progress = client.jobs.list(status="in_progress")
queued = client.jobs.list(status="queued")

print(f"In progress: {len(in_progress.data)}")
print(f"Queued: {len(queued.data)}")

​
Find Failed Jobs

# List failed jobs to investigate errors
failed_jobs = client.jobs.list(status="failed", limit=50)

for job in failed_jobs.data:
    print(f"{job.id}: {job.error.code} - {job.error.message}")

​
Filter by Metadata

While the API doesn’t support direct metadata filtering, you can filter client-side: 
# Find jobs from a specific batch
batch_id = "batch_001"
batch_jobs = []

response = client.jobs.list(limit=100)
for job in response.data:
    if job.metadata and job.metadata.get("batch_id") == batch_id:
        batch_jobs.append(job)

print(f"Jobs in {batch_id}: {len(batch_jobs)}")

Authorizations

​
Api-Key
string
header
required

Query Parameters

​
after
string | null

Pagination cursor (last ID from previous page)

​
limit
integer
default:20

Number of jobs to return

Required range: 1 <= x <= 100
​
status
enum<string> | null

Filter by status

Available options:
validating,
queued,
in_progress,
completed,
failed,
cancelled,
expired
​
access_token
string | null

Response

Successful Response

Response for GET /v1/jobs.

​
data
Job · object[]
required
​
object
string
default:list
Allowed value: "list"
​
first_id
string | null
​
last_id
string | null
​
has_more
boolean
default:false