Skip to main content
GET
/
v1
/
jobs
/
{job_id}
/
status
import httpx
import os

job_id = "job_V1StGXR8_Z5jdHi6B-myT"

response = httpx.get(
    f"https://api.retab.com/v1/jobs/{job_id}/status",
    headers={"Api-Key": os.environ["RETAB_API_KEY"]},
    timeout=30.0,
)
response.raise_for_status()
job = response.json()

print(job["status"])

{
  "id": "job_V1StGXR8_Z5jdHi6B-myT",
  "object": "job",
  "status": "in_progress",
  "endpoint": "/v1/documents/extract",
  "error": null,
  "created_at": 1705420800,
  "started_at": 1705420802,
  "completed_at": null,
  "expires_at": 1706025600,
  "organization_id": "org_abc123",
  "metadata": {
    "batch_id": "batch_001"
  }
}

import httpx
import os

job_id = "job_V1StGXR8_Z5jdHi6B-myT"

response = httpx.get(
    f"https://api.retab.com/v1/jobs/{job_id}/status",
    headers={"Api-Key": os.environ["RETAB_API_KEY"]},
    timeout=30.0,
)
response.raise_for_status()
job = response.json()

print(job["status"])

{
  "id": "job_V1StGXR8_Z5jdHi6B-myT",
  "object": "job",
  "status": "in_progress",
  "endpoint": "/v1/documents/extract",
  "error": null,
  "created_at": 1705420800,
  "started_at": 1705420802,
  "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.

​
When to Use This Endpoint

Use /v1/jobs/{job_id}/status for high-frequency polling when you only need lifecycle fields like status, timestamps, error, and metadata. Use GET /v1/jobs/{job_id} when you need the original request payload or the completed response body.

​
Response Fields

​
id
string
Unique identifier for the job.
​
object
string
Always "job".
​
status
string
Current job status: validating, queued, in_progress, completed, failed, cancelled, or expired.
​
endpoint
string
The target endpoint for this job.
​
error
object | null
Error details when the job failed.
​
created_at
integer
Unix timestamp when the job was created.
​
started_at
integer | null
Unix timestamp when processing 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.

Authorizations

​
Api-Key
string
header
required

Path Parameters

​
job_id
string
required

Query Parameters

​
access_token
string | null

Response

Successful Response

Minimal status payload for low-latency polling.

​
id
string
required
​
status
enum<string>
required
Available options:
validating,
queued,
in_progress,
completed,
failed,
cancelled,
expired
​
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
​
created_at
integer
required
​
expires_at
integer
required
​
organization_id
string
required
​
object
string
default:job
Allowed value: "job"
​
error
JobError · object

Error details when job fails.

​
warnings
JobWarning · object[] | null
​
started_at
integer | null
​
completed_at
integer | null
​
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