---
title: "List jobs"
method: GET
path: "/api/v1/jobs"
tags: ["Job Management"]
---

# List jobs

`GET /api/v1/jobs`

## Request

- Base URL: `https://api.imagestep.dev`
- URL: `https://api.imagestep.dev/api/v1/jobs`
- Auth: API key in header `Authorization`

Your jobs, newest first, one page at a time. Every filter is optional and they combine; a missing
one filters nothing. A row carries the item counts and what ran, not `items` — read one job for
those.

To follow a job you just submitted, read it by id — `GET /api/v1/jobs/{id}?wait=` holds the answer
until it settles — or register a webhook. Polling this list is the slow way to watch one job.

USE THIS WHEN:
- Finding jobs by status, type, op, preset or date — last week's failures, say
- Reading every attempt of one job (`rootJobId`)

DO NOT USE WHEN:
- You have the job's id → `GET /api/v1/jobs/{id}`
- You only need how many → `GET /api/v1/jobs/counts`

## Query parameters

- `page` integer
- `perPage` integer
- `cursor` string
- `status` 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'CANCELLING'
- `type` 'ai-generate' | 'ai-edit' | 'parse' | 'process' | 'render' | 'chain'
- `preset` string
- `op` string
- `rootJobId` string
- `createdFrom` string
- `createdTo` string

## Response `200`

One page of rows, with `meta`

## Other responses

- `400`: `invalid_param` on `status` / `type` — not one of its values, which `details.allowed` lists (either case is taken); on `createdFrom` / `createdTo` — neither epoch milliseconds nor an ISO-8601 date or instant
- `404`: `preset_not_found` — the `preset` filter names no preset of yours, or no such version of it
- `429`: Rate limited — `error.code` is `rate_limited` and `retryable` is true. `Retry-After` says how many seconds to wait.

---

[API](https://skmtc.dev/imagestep/apis/imagestep-api.md) · [All operations](https://skmtc.dev/imagestep/apis/imagestep-api/llms.txt) · [OpenAPI document](https://skmtc.dev/imagestep/apis/imagestep-api/revisions/5e8e922a3085?raw)