# Jobs

Source: https://www.hotdata.dev/docs/api-reference/jobs
Site index: https://www.hotdata.dev/llms.txt

Track background jobs. Jobs are submitted internally by other APIs when async execution is requested. Poll job status by ID or list all jobs.

## List jobs

`GET /v1/jobs`

List background jobs with optional filters by type and status.

**Query parameters**

- `job_type` `JobType` — Filter by job type
- `status` `string` — Filter by status (comma-separated, e.g. status=pending,running)
- `limit` `integer` — Max results (default 50)
- `offset` `integer` — Offset for pagination

**Response** `200` — List of jobs

- `jobs` `JobStatusResponse`[] — **required**
  - `attempts` `integer` — **required**. Number of execution attempts (including the current one).
  - `completed_at` `string,null`
  - `created_at` `string` — **required**
  - `error_message` `string,null` — Error or warning message. Set when status is `failed` or `partially_succeeded`.
  - `id` `string` — **required**
  - `job_type` `JobType` — **required**. Background job types returned by the API.
  - `result` `null` | `JobResult`
  - `status` `JobStatus` — **required**. Current status of a background job.

```json
{
  "jobs": [
    {
      "attempts": 0,
      "completed_at": "2026-01-01T00:00:00Z",
      "created_at": "2026-01-01T00:00:00Z",
      "error_message": "string",
      "id": "string",
      "job_type": "noop",
      "result": null,
      "status": "pending"
    }
  ]
}
```

## Get job status

`GET /v1/jobs/{id}`

Get the current status of a background job. Poll this endpoint to track job progress.

**Path parameters**

- `id` `string` — **required**. Job ID

**Response** `200` — Job status

- `attempts` `integer` — **required**. Number of execution attempts (including the current one).
- `completed_at` `string,null`
- `created_at` `string` — **required**
- `error_message` `string,null` — Error or warning message. Set when status is `failed` or `partially_succeeded`.
- `id` `string` — **required**
- `job_type` `JobType` — **required**. Background job types returned by the API.
- `result` `null` | `JobResult`
- `status` `JobStatus` — **required**. Current status of a background job.

```json
{
  "attempts": 0,
  "completed_at": "2026-01-01T00:00:00Z",
  "created_at": "2026-01-01T00:00:00Z",
  "error_message": "string",
  "id": "string",
  "job_type": "noop",
  "result": null,
  "status": "pending"
}
```

**Errors**

| Status | Description |
| ------ | ----------- |
| `404` | Job not found |