> ## 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.

> Pause an ongoing batch job

# Pause job

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

## Overview

This endpoint pauses a job identified by its job ID. Per the job status lifecycle, a job in the
`PENDING`, `ADMITTED`, or `RUNNING` state can transition to `PAUSED`. A paused job can later be
returned to `PENDING` with the [Resume Job](/api-reference/batch/jobs/resume-job) endpoint.

On success the endpoint returns the job ID, its new status, and the time at which it was paused.

## Request

<ParamField path="id" type="string" required>
  Job identifier. A TypeID-encoded identifier with the `job_` prefix.
</ParamField>

## Response

On success, returns the paused job record.

<ResponseField name="id" type="string">
  The identifier of the paused job (a TypeID-encoded `JobId`).
</ResponseField>

<ResponseField name="status" type="string">
  The job's status after the transition: `PAUSED`.
</ResponseField>

<ResponseField name="paused_at" type="string">
  The date and time at which the job was paused.
</ResponseField>

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

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

  api_key = os.environ.get("ATAI_API_KEY")
  job_id = "job-2512078e5c9ce4d312a6681e771542"

  response = requests.post(
      f"https://api.u1.archetypeai.app/v0.5/batch/jobs/{job_id}/pause",
      headers={"Authorization": f"Bearer {api_key}"}
  )

  result = response.json()
  print(f"Job {result['id']} status: {result['status']} (paused at {result['paused_at']})")
  ```

  ```javascript JavaScript theme={"system"}
  const jobId = 'job-2512078e5c9ce4d312a6681e771542';

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

  const result = await response.json();
  console.log(`Job ${result.id} status: ${result.status} (paused at ${result.paused_at})`);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Job paused theme={"system"}
  {
    "id": "job-2512078e5c9ce4d312a6681e771542",
    "status": "PAUSED",
    "paused_at": "2025-12-07T18:37:42.576972Z"
  }
  ```

  ```json 404 - Job not found theme={"system"}
  {
    "code": "job_not_found",
    "message": "Job {id} not found",
    "suggestion": null,
    "error_uid": "err-xxxxxxxx"
  }
  ```

  ```json 409 - Invalid state transition theme={"system"}
  {
    "code": "invalid_state_transition",
    "message": "Cannot pause job in {status} state; only PENDING, ADMITTED, or RUNNING jobs can be paused.",
    "suggestion": null,
    "error_uid": "err-xxxxxxxx"
  }
  ```
</ResponseExample>