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

# List Jobs

`GET /api/v1/jobs/`

## Request

- Base URL: `https://platform-api.transform.unstructured.io` (the document declares no server; this is the origin it was published from)
- URL: `https://platform-api.transform.unstructured.io/api/v1/jobs/`
- Auth: none declared
- TypeScript: <https://skmtc.dev/unstructured/apis/platform-api/docs/api/v1/jobs/get.ts> (a function with typed inputs; its response is checked against the schema)

Retrieve a list of jobs with optional filtering by workflow ID or job status.

## Query parameters

- `workflow_id` string, uuid, nullable
- `status` string, nullable

## Headers

- `unstructured-api-key` string, nullable

## Response `200`

Successful Response

- JobInformation[]
  - `id` string, uuid, required
  - `workflow_id` string, uuid, required
  - `workflow_name` string, required
  - `status` 'SCHEDULED' | 'IN_PROGRESS' | 'COMPLETED' | 'STOPPED' | 'FAILED' | 'REJECTED', required
  - `stop_requested` boolean
  - `created_at` string, date-time, required
  - `runtime` string, duration, nullable
  - `input_file_ids` string[], nullable
  - `output_node_files` NodeFileMetadata[], nullable
    - `node_id` string, required
    - `file_id` string, required
    - `node_type` string, required
    - `node_subtype` string, required
  - `job_type` 'ephemeral' | 'persistent' | 'scheduled' | 'template'
  - `created_by_id` string, uuid, nullable
  - `reason` string, nullable: Sanitized failure reason for a FAILED job; None otherwise.
  - `processing_status` 'SCHEDULED' | 'IN_PROGRESS' | 'SUCCESS' | 'COMPLETED_WITH_ERRORS' | 'STOPPED' | 'FAILED' | 'REJECTED'
  - `failed_file_count` integer, nullable: Documents that failed so far. Read it against `processing_status`, which says whether the job has reached a verdict: on a job that has not finished, 0 means none recorded yet, not that every input produced output.
  - `completion_issue` 'NO_DOCUMENTS_DISCOVERED' | 'NO_DOCUMENTS_SUCCEEDED': Why a COMPLETED job delivered no document. Read for what a run did; the verdict only says whether anything was lost. A run whose source handed back nothing finishes `processing_status: SUCCESS` with an empty destination, and without this there is no statement anywhere that it moved nothing (Pylon 2287, PLU-622). A run that discovered documents and delivered none of them without failing any is FAILED, and carries this for the same reason: nothing else on the row explains it. A run whose documents failed carries none of these; `/failed-files` explains it. So the verdict cannot be used to find these runs, and a caller that wants to know whether a job delivered anything branches on this field. Its own type on its own nullable field, deliberately NOT a `JobProcessingStatus` member: that enum is on the public wire and a closed generated-SDK enum breaks a whole `list_jobs` page on one unrecognised value (DTPL-696, `REJECTED`). Null is "no issue detected", never "checked and fine" -- a caller must not read the absence of a value as a guarantee, and a job FAILED for some other reason (a failed document, a preflight rejection) carries none of these. New members may be added; treat an unrecognised one as "an issue was detected, of a kind this client does not know".

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/unstructured/apis/platform-api.md) - [All operations](https://skmtc.dev/unstructured/apis/platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/unstructured/apis/platform-api/revisions/16b4542093db?raw)