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

# List jobs

`GET /jobs`

## Request

- Base URL: `https://api.varg.ai/v2`
- URL: `https://api.varg.ai/v2/jobs`
- Auth: HTTP bearer

List the caller's 50 most recent jobs, newest first. No pagination or filters; for older work use `GET /files` or `GET /billing/usage`.

## Response `200`

Job list

- object
  - `data` Job[], required
    - `id` string, required
    - `status` 'queued' | 'running' | 'awaiting_confirmation' | 'completed' | 'failed' | 'cancelled', required: The status only moves forward: `queued` → `running` → `completed`, `failed` or `cancelled`. Everything a running job goes through — sending to the provider, uploading references, switching to another provider — is a `stage` of `running`; a job never goes back to `queued`. (Older API builds also reported `submitting`; treat it as `running`.) `awaiting_confirmation` (multi-step pipelines only): the job finished a step that asks for review and waits for `POST /jobs/{id}/confirm`. It is not terminal.
    - `stage` 'queued' | 'submitting' | 'uploading_references' | 'rendering' | 'retrying' | 'finalizing' | 'null', nullable, required: What the job is doing right now. `null` once the job is terminal, and while the job is `awaiting_confirmation`. - `queued` — waiting for a slot; no attempt yet - `submitting` — being sent to the provider - `uploading_references` — the provider is taking the reference files into its asset library (`progress_message` shows `n/m`) - `rendering` — the provider accepted the task and is generating - `retrying` — an attempt failed (the provider refused, failed or rate limited it); the job waits for its next attempt, usually on another provider. See `attempts`. - `finalizing` — the result is being saved and billed
    - `attempts` JobAttempt[], required: Every provider tried for this job, oldest first. `provider` / `provider_model` are the newest one.
      - `n` integer
      - `provider` string, nullable
      - `model_key` string, nullable
      - `status` 'running' | 'completed' | 'failed' | 'cancelled'
      - `reason` string: Why a failed attempt failed, in a few words
      - `reason_code` 'content_privacy' | 'content_policy' | 'quota' | 'rate_limit' | 'provider_error' | 'timeout' | 'expired' | 'prompt_too_long'
      - `references_uploaded` integer: Reference files taken into the provider's asset library
      - `resubmitted` boolean: The provider refused the first submit and got the task again (with uploaded references)
      - `started_at` string, date-time, nullable
      - `ended_at` string, date-time, nullable
    - `tool` string, required: Internal tool id (e.g. `tool_2001a2b3c4d5` for video). It differs between environments and is kept for backwards compatibility. Do not compare it against `GET /tools` keys; use `tool_key`.
    - `tool_key` string, nullable, required: Readable tool key (`image`, `video`, `speech`, `pipeline`, ...): the key of `GET /tools`, of the sugar route that created the job (`POST /video` → `video`), of `GET /files?tool=` and of lineage. `null` only if the tool registry could not be read.
    - `input` object, required: The request body as submitted (model, prompt, ...)
    - `output` JobOutput, required: Canonical output envelope. Present only when the job is completed.
      - `version` 'v1'
      - `outputs` object[]
        - `url` string: Stable varg-hosted URL (s3.varg.ai)
        - `file_id` string: The file record for this output — use with /files and /lineage
        - `media_type` string
        - `size_bytes` integer
        - `thumbnail_url` string, nullable
        - `data` unknown
        - `raw` unknown
    - `error` string, nullable, required: Human-readable failure message. `null` unless the job failed or was cancelled.
    - `progress_message` string, nullable, required
    - `progress` number, nullable, required: Fraction 0..1
    - `progress_metadata` object, nullable, required
    - `step_state` object, nullable, required: Multi-step pipeline jobs only: the current step and each step's status, intermediate output and cost. `null` for ordinary jobs.
      - `current_step` string, nullable
      - `steps` object
    - `estimated_duration_ms` integer, nullable, required
    - `estimated_cost_cents` integer, nullable, required
    - `actual_cost_cents` integer, nullable, required
    - `pricing` JobPricing, required: Structured pricing. 1 credit = 1 cent = $0.01.
      - `estimated` integer, nullable: Reserved at creation (cents)
      - `actual` integer, nullable: Charged at completion (cents). 0 for cache hits.
      - `billing` string, nullable
      - `cached` boolean, nullable: true when the result came from cache (actual = 0)
      - `billed_units` object, nullable
      - `pricing_id` string, nullable: The pinned pricing rule this job was charged under
    - `provider` string, nullable, required
    - `provider_model` string, nullable, required
    - `provider_status` string, nullable, required: The provider's raw status string
    - `provider_job_id` string, nullable, required
    - `completed_by_provider_model_id` string, nullable, required: Provider model route that completed the job
    - `last_attempt_provider_model_id` string, nullable, required: Provider model route of the most recent attempt
    - `workspace_id` string, nullable, required: Folder the outputs are filed into (see `X-Workspace-Id`)
    - `created_at` string, date-time, required
    - `started_at` string, date-time, nullable, required
    - `completed_at` string, date-time, nullable, required
    - `warnings` string[]: Present on creation responses when the request was adjusted (for example a resolution fallback)
    - `urls` object: Lifecycle URLs (present on creation responses)
      - `self` string
      - `status` string
      - `refresh` string
      - `cancel` string
      - `retry` string
      - `confirm` string
      - `rerun` string

## Other responses

- `401`: Missing or invalid API key / JWT

## Changes

- **2026-10-20** `09d49a6d852f`: 1 info
  - added the required property `data/items/tool_key` to the response with the `200` status
- **2026-10-20** `43bcf5ea398d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/varg/apis/varg-api/changes/jobs/get.md)

---

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