---
title: "List jobs"
method: GET
path: "/api/v2/jobs"
tags: ["jobs"]
---

# List jobs

`GET /api/v2/jobs`

List jobs visible to the caller, newest first.

Cursor-paginated. Optionally filter by lifecycle ``status`` and/or by
``workflow_id`` (matches all jobs for that workflow).

Visibility is role-scoped within the active organization: ADMIN and
OWNER see every job in the org; VIEWER and MEMBER see only their own.

## Query parameters

- `cursor` string, nullable
- `limit` integer, nullable
- `status` 'in_progress' | 'analysing' | 'completed' | 'completed_with_errors' | 'abandoned'
- `workflow_id` string, nullable — Filter to jobs of this workflow family.

## Response `200`

Successful Response

- PaginatedJobSummary
  - `items` JobSummary[], required — Page of items in the order the endpoint defines; see the endpoint's order_by for the sort.
    - `id` string, required — Stable job id.
    - `workflow_id` string, required — Id of the workflow this job is running against.
    - `workflow_name` string, nullable — Display name of the workflow this job runs against. Null when the workflow row is unavailable. Additive convenience field so clients need not resolve the name from workflow_id separately.
    - `user_id` string, required — Id of the user who started the job.
    - `is_adhoc` boolean — True when this job runs against a synthetic ad-hoc workflow (no predefined steps). Clients render the workflow column as an ad-hoc placeholder rather than the synthetic workflow name.
    - `organization_id` string, nullable — Owning organization id. Null for personal jobs.
    - `status` 'in_progress' | 'analysing' | 'completed' | 'completed_with_errors' | 'abandoned', required
    - `result` 'pending' | 'passed' | 'failed' — The pass/fail outcome of a job, distinct from its lifecycle status. Lifecycle (``JobLifecycleStatus``) answers "did the run finish, and did any step technically error?". Result answers "did the run pass its checks?". The two are independent: a run can finish cleanly (``COMPLETED``) yet still ``FAILED`` because too few steps passed for the workflow's pass policy. The pass policy is driven by ``allow_step_failure``: - Off: strict. Any errored or failing step makes the result ``FAILED``. - On: threshold. Failures are tolerated until the percentage of evaluable steps that failed exceeds ``fail_threshold_percent``; errored steps count as failures. - ``PENDING``: not yet determined (job still in progress / analysing). - ``PASSED``: the workflow's pass policy is satisfied. - ``FAILED``: the workflow's pass policy is not satisfied.
    - `started_at` string, date-time, required — When the job was created.
    - `analysing_started_at` string, date-time, nullable — When the job transitioned to ANALYSING. Null while still IN_PROGRESS. Used by the stale-analysis recovery sweep to time out crashed analysis tasks.
    - `completed_at` string, date-time, nullable — When the job was completed. Null while in progress.
  - `next_cursor` string, nullable — Opaque cursor to fetch the next page. Null when this is the last page.
  - `limit` integer, required — Page size that was applied.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/tiliter/apis/tiliter-vision-ai-public-api.md) · [All operations](https://skmtc.net/tiliter/apis/tiliter-vision-ai-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tiliter/tiliter-vision-ai-public-api/revisions/eef1814ea815/schema)