---
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``, by
``workflow_id`` (matches all jobs for that workflow), and/or by a
``search`` term.

``search`` looks inside the job rather than at its name alone: an operator
who recorded a tenant on a Selection step can find that tenant's jobs
afterwards (VA-694). See ``job_search_predicate`` for what it matches.

Visibility is role-scoped within the active organization: ADMIN and
OWNER see every job in the org; VIEWER and MEMBER see only their own.
Search narrows that scope; it never widens it.

## 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.
- `search` string, nullable — Filter to jobs matching this text, case-insensitively. Matches Selection answers recorded against the job, its step names, and the workflow name. Blank or whitespace-only is ignored.

## 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.
    - `site_id` string, nullable — Site selected at the start of this inspection.
    - `asset_id` string, nullable — Asset selected at the start of this inspection.
    - `location_path` string, nullable — Human-readable site and hierarchy path captured when this inspection started.
    - `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

## Changes

- **2026-09-04** `eb7293c7622b` — 4 info
  - added the new optional `query` request parameter `search`
  - added the optional property `items/items/asset_id` to the response with the `200` status
  - added the optional property `items/items/location_path` to the response with the `200` status
  - added the optional property `items/items/site_id` to the response with the `200` status

[Change history](https://skmtc.dev/tiliter/apis/tiliter-vision-ai-public-api/changes/api/v2/jobs/get.md)

---

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