Jobs

Job management. Check status, get results, and list processing jobs.

Get job status

get

Get the current status and results of a processing job.

Status Values

Status	Description
pending	Job created, waiting to start
queued	Job in queue, waiting for GPU worker
processing	Job is being processed
completed	Job finished successfully
failed	Job failed with error

Response Fields

• status: Current job status

• result: Download URLs (when completed)

• error: Error message (when failed)

• progress: Processing progress 0-100 (when processing)

• cost: Credits charged for this job

Polling Recommendation

Poll every 5-10 seconds until status is completed or failed.

Authorizations

BearerAuth

AuthorizationstringRequired

How to Authenticate

1. Get your token from Timbr Dashboard
2. Click the Authorize button above
3. Enter only the token (e.g., TBR_abc123def456)
4. Click Authorize then Close

Important

• ✅ Correct: TBR_8b3364b5a772328a
• ❌ Wrong: Bearer TBR_8b3364b5a772328a

The 'Bearer ' prefix is added automatically by Swagger UI.

Path parameters

job_idstringRequired

Responses

200

Job status retrieved

application/json

401

Unauthorized - Invalid or missing Timbr token

403

Access denied

application/json

404

Job not found

application/json

422

Validation Error

application/json

get

/v1/jobs/{job_id}

HTTPcURLJavaScriptPython

GET /v1/jobs/{job_id} HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "job_id": "sep_a1b2c3d4e5f6",
  "status": "pending",
  "created_at": "2026-01-05T10:00:00Z",
  "cost": 30
}

List jobs

get

List all jobs for the authenticated user with pagination and optional filtering.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number (1-indexed)
page_size	integer	20	Jobs per page (max 100)
status	string	null	Filter by status

Status Filter Values

• pending - Jobs waiting to start

• queued - Jobs waiting for GPU worker

• processing - Jobs currently running

• completed - Successfully finished jobs

• failed - Jobs that encountered errors

Pagination

Response includes has_more field to indicate if more pages exist.

Authorizations

BearerAuth

AuthorizationstringRequired

How to Authenticate

1. Get your token from Timbr Dashboard
2. Click the Authorize button above
3. Enter only the token (e.g., TBR_abc123def456)
4. Click Authorize then Close

Important

• ✅ Correct: TBR_8b3364b5a772328a
• ❌ Wrong: Bearer TBR_8b3364b5a772328a

The 'Bearer ' prefix is added automatically by Swagger UI.

Query parameters

pageinteger · min: 1Optional

Page number (1-indexed)

Default: 1

page_sizeinteger · min: 1 · max: 100Optional

Jobs per page (max 100)

Default: 20

statusany ofOptional

Filter by job status

string · enumOptional

Valid job status filter values for list_jobs endpoint.

SECURITY: Using enum prevents SQL injection via status parameter by ensuring only known, safe values can be passed to database queries.

Possible values:

or

nullOptional

Responses

200

Job list retrieved

application/json

401

Unauthorized - Invalid or missing Timbr token

422

Validation Error

application/json

get

/v1/jobs

HTTPcURLJavaScriptPython

GET /v1/jobs HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "jobs": [
    {
      "job_id": "sep_a1b2c3d4e5f6",
      "status": "completed",
      "created_at": "2026-01-05T10:00:00Z",
      "completed_at": "2026-01-05T10:01:05Z",
      "cost": 30
    },
    {
      "job_id": "enh_b2c3d4e5f678",
      "status": "processing",
      "created_at": "2026-01-05T10:05:00Z",
      "cost": 15
    }
  ],
  "total": 42,
  "page": 1,
  "page_size": 20,
  "has_more": true
}