> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archetypeai.app/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Start with /introduction/getting-started. Use the Direct Query API (POST /query) with the Newton Fusion model (text, image, and video reasoning) or the Newton Omega encoder (time-series embeddings). ATAI_API_ENDPOINT must include the version path: /v0.5 for most APIs, /v0.6 for the Fine-Tuning Service. Pages whose descriptions are marked (Archived) document the legacy Lens runtime — do not use them for new projects.

# List Jobs

> Retrieve a paginated list of jobs with optional filters

<Callout icon="clock" color="#3064E3" iconType="solid">
  Requires [version 1.1.0](/release-notes/1.1.x#v1-1-0) or later of the Archetype platform.
</Callout>

## Overview

This endpoint returns a paginated list of jobs. You can filter by pipeline type, status, or a free-text search query.

## Request

<ParamField query="pipeline_type" type="string">
  Filter jobs by pipeline type (e.g., `batch`, `training`)
</ParamField>

<ParamField query="status" type="string">
  Filter jobs by status (e.g., `PENDING`, `RUNNING`, `COMPLETED`, `FAILED`, `CANCELLED`)
</ParamField>

<ParamField query="outcome" type="string">
  Optional filter on the job outcome: `SUCCESS`, `PARTIAL`, or `FAILED`. These are AND-combined
  with the other filters. Only `COMPLETED` jobs have an `outcome`, so a non-empty value for this
  parameter implicitly limits results to completed jobs. <Badge color="blue">[v1.1.5+](/release-notes/1.1.x#v1-1-5)</Badge>
</ParamField>

<ParamField query="q" type="string">
  Free-text search query to filter jobs
</ParamField>

<ParamField query="offset" type="integer">
  Number of items to skip for pagination (default: 0)
</ParamField>

<ParamField query="limit" type="integer">
  Maximum number of items to return per page
</ParamField>

## Response

<ResponseField name="total" type="integer">
  Total number of jobs matching the filter criteria
</ResponseField>

<ResponseField name="offset" type="integer">
  Current pagination offset
</ResponseField>

<ResponseField name="limit" type="integer">
  Maximum number of items returned
</ResponseField>

<ResponseField name="jobs" type="array">
  Array of job objects, each containing:

  * `id` — Unique job identifier
  * `org_id` — Organization identifier
  * `name` — Job name
  * `pipeline_type` — Pipeline type (`batch` or `training`)
  * `pipeline_key` — Pipeline key
  * `pipeline_version` — Pipeline version
  * `status` — Current job status
  * `outcome` — Job outcome (`SUCCESS`, `PARTIAL`, or `FAILED`). Omitted for jobs whose `status` isn't `COMPLETED` <Badge color="blue">[v1.1.5+](/release-notes/1.1.x#v1-1-5)</Badge>
  * `parameters` — Job parameters
  * `retry_count` — Number of retries
  * `preemption_count` — Number of preemptions
  * `queue_position` — Current position in queue (if queued)
  * `queue_depth` — Total queue depth (if queued)
  * `input_progress` — Per-status counts of tracked inputs (`pending`, `processing`,
    `completed`, `failed`, `processed_bytes`, `total_bytes`); populated on this list endpoint, `null` on
    write-path responses (see the [`input_progress`
    property](/api-reference/batch/jobs/get-job#param-input-progress) returned by the [Get
    Job](/api-reference/batch/jobs/get-job) endpoint)
  * `created_at` — Creation timestamp
  * `updated_at` — Last update timestamp
  * `started_at` — Start timestamp (if started)
  * `completed_at` — Completion timestamp (if completed)
  * `failed_at` — Failure timestamp (if failed)
  * `cancelled_at` — Cancellation timestamp (if cancelled)
  * `error` — Error details (if failed)
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl https://api.u1.archetypeai.app/v0.5/batch/jobs \
    -H "Authorization: Bearer $ATAI_API_KEY"
  ```

  ```python Python theme={"system"}
  import requests
  import os

  api_key = os.environ.get("ATAI_API_KEY")

  response = requests.get(
      "https://api.u1.archetypeai.app/v0.5/batch/jobs",
      headers={"Authorization": f"Bearer {api_key}"},
      params={
          "pipeline_type": "batch",
          "status": "RUNNING",
          "limit": 10
      }
  )

  data = response.json()
  print(f"Total jobs: {data['total']}")
  for job in data["jobs"]:
      print(f"  {job['id']}: {job['name']} — {job['status']}")
  ```

  ```javascript JavaScript theme={"system"}
  const params = new URLSearchParams({
    pipeline_type: 'batch',
    status: 'RUNNING',
    limit: '10'
  });

  const response = await fetch(`https://api.u1.archetypeai.app/v0.5/batch/jobs?${params}`, {
    headers: {
      'Authorization': `Bearer ${process.env.ATAI_API_KEY}`
    }
  });

  const data = await response.json();
  console.log(`Total jobs: ${data.total}`);
  data.jobs.forEach(job => {
    console.log(`  ${job.id}: ${job.name} — ${job.status}`);
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={"system"}
  {
    "total": 42,
    "offset": 0,
    "limit": 10,
    "jobs": [
      {
        "id": "job_2abc3def4ghi5jkl6mno7pqr",
        "org_id": "org_1abc2def3ghi4jkl",
        "name": "tep-classification",
        "pipeline_type": "batch",
        "pipeline_key": "machine-state-classification",
        "pipeline_version": "1.1.1",
        "status": "RUNNING",
        "parameters": {},
        "retry_count": 0,
        "preemption_count": 0,
        "queue_position": null,
        "queue_depth": null,
        "input_progress": {
          "pending": 0,
          "processing": 1,
          "completed": 2,
          "failed": 0,
          "processed_bytes": 40551733,
          "total_bytes": 105332974
        },
        "created_at": "2026-04-14T10:00:00Z",
        "updated_at": "2026-04-14T10:05:00Z",
        "started_at": "2026-04-14T10:02:00Z",
        "completed_at": null,
        "failed_at": null,
        "cancelled_at": null,
        "error": null
      }
    ]
  }
  ```

  ```json 401 - Unauthorized theme={"system"}
  {
    "detail": "Invalid access with key: api_key_not_found"
  }
  ```
</ResponseExample>