> ## Documentation Index
> Fetch the complete documentation index at: https://docs.okrapdf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Jobs

> Inspect, wait on, and control parse, render, and workflow jobs.

`okra jobs` inspects the parse, render, and workflow jobs your other commands create. Jobs are created implicitly — `okra upload`, `okra extract`, `okra parse`, `okra render`, and the workflow commands all enqueue a job — so the `jobs` surface is for **listing, waiting, and controlling** them, not creating them.

## Recommended flow

```bash theme={null}
# 1) Kick off work that enqueues a job (e.g. a fire-and-forget parse)
okra upload ./report.pdf --no-wait

# 2) Wait for the latest parse job for that document
okra jobs wait <docId> --timeout 600

# 3) Inspect the job and its result
okra jobs get <jobId>
```

<Tip>
  `okra jobs wait` accepts **either** a job ID **or** a document ID. Given a document ID, it waits for that document's latest `document.parse` job.
</Tip>

## Commands

```bash theme={null}
okra jobs list                       # list your jobs (newest first)
okra jobs list --status completed    # filter by status
okra jobs list --type document.parse # filter by job type
okra jobs list --doc <docId>         # filter by document
okra jobs get <jobId>                # job status + result (alias: show)
okra jobs wait <jobOrDocId>          # block until a job finishes
okra jobs events <jobId>             # print the job event-stream URL
okra jobs cancel <jobId>             # cancel a queued or running job
okra jobs retry <jobId>              # retry a failed job
okra jobs resume <jobId>             # resume a paused job
```

### `jobs list` flags

| Flag                | Description                                                   |
| ------------------- | ------------------------------------------------------------- |
| `--limit <n>`       | Max jobs to return                                            |
| `--type <type>`     | Filter by job type (e.g. `document.parse`, `document.render`) |
| `--status <status>` | Filter by job status                                          |
| `--doc <docId>`     | Filter to jobs for one document                               |

Combine with the global `--json` flag for machine-readable output:

```bash theme={null}
okra jobs list --status completed --limit 5 --json
```

When stdout is not a TTY, `okra jobs` commands emit the standard envelope. For example, `okra jobs list --json` returns:

```json theme={null}
{
  "ok": true,
  "command": "jobs list",
  "result": { "jobs": [] },
  "cost": { "usd": null },
  "citations": [],
  "next_actions": []
}
```

### `jobs wait`

```bash theme={null}
okra jobs wait <jobId>
okra jobs wait <docId>               # waits for the latest document.parse job
okra jobs wait <jobOrDocId> --timeout 600
```

| Flag                  | Description                              |
| --------------------- | ---------------------------------------- |
| `--timeout <seconds>` | Maximum seconds to wait (default: `300`) |

### `jobs cancel`, `retry`, and `resume`

```bash theme={null}
okra jobs cancel <jobId>             # cancel a queued or running job
okra jobs retry <jobId>              # retry a failed job
okra jobs resume <jobId>             # resume a paused job
```

Only non-terminal jobs can be cancelled; only failed jobs can be retried; only paused jobs can be resumed.

<Info>
  To create work, use a verb command (`okra upload`, `okra extract`, `okra parse`, `okra render`) rather than `okra jobs`. Those commands enqueue the job and, by default, wait for it — add `--no-wait` to queue and follow up with `okra jobs wait`.
</Info>