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

# Pause, resume, start, or stop a training job

> Control the lifecycle of a training job through pause, resume, start, and stop transitions. Each action returns the updated job status.

PIN supports explicit lifecycle control for training jobs. You can pause a running job to release its GPU while keeping checkpoints, resume a paused job to continue from the last checkpoint, start a queued or paused job, or stop a job to reach a terminal state.

## Method + Path

```http theme={null}
POST /v1/jobs/:id/pause
POST /v1/jobs/:id/resume
POST /v1/jobs/:id/start
POST /v1/jobs/:id/stop
```

## Authentication

Include your PIN API token or JWT in the `Authorization` header as a Bearer token.

```http theme={null}
Authorization: Bearer <token>
```

## Path parameters

<ParamField path="id" type="string" required>
  The job identifier (e.g., `jb_abc123def456`).
</ParamField>

## Request body

No request body is required for any lifecycle endpoint.

## Request examples

<CodeGroup>
  ```bash Pause theme={null}
  curl -s -X POST "https://api.ariacompute.com/v1/jobs/jb_abc123def456/pause" \
    -H "Authorization: Bearer $PIN_API_TOKEN"
  ```

  ```bash Resume theme={null}
  curl -s -X POST "https://api.ariacompute.com/v1/jobs/jb_abc123def456/resume" \
    -H "Authorization: Bearer $PIN_API_TOKEN"
  ```

  ```bash Start theme={null}
  curl -s -X POST "https://api.ariacompute.com/v1/jobs/jb_abc123def456/start" \
    -H "Authorization: Bearer $PIN_API_TOKEN"
  ```

  ```bash Stop theme={null}
  curl -s -X POST "https://api.ariacompute.com/v1/jobs/jb_abc123def456/stop" \
    -H "Authorization: Bearer $PIN_API_TOKEN"
  ```
</CodeGroup>

## Response

Returns a standard PIN success envelope with the updated job state.

<ResponseField name="code" type="integer" required>
  `0` on success, nonzero on error.
</ResponseField>

<ResponseField name="data" type="object" required>
  <Expandable title="properties">
    <ResponseField name="job_id" type="string">
      The job identifier.
    </ResponseField>

    <ResponseField name="status" type="string">
      New job status after the transition.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable message (empty on success).
</ResponseField>

### Example response

```json theme={null}
{
  "code": 0,
  "data": {
    "job_id": "jb_abc123def456",
    "status": "paused"
  },
  "message": ""
}
```

## Transition rules

| Action   | Allowed from       | Result                | Notes                                                     |
| -------- | ------------------ | --------------------- | --------------------------------------------------------- |
| `pause`  | `running`          | `paused`              | GPU released, checkpoints kept.                           |
| `resume` | `paused`           | `running` or `queued` | Tries agent-local resume first; falls back to re-enqueue. |
| `start`  | `queued`, `paused` | `running` or `queued` | No-op if already running. For paused, acts as resume.     |
| `stop`   | Any non-terminal   | `stopped`             | Terminal state; no refund.                                |

## Errors

| Code | HTTP | Meaning                                                     |
| ---- | ---- | ----------------------------------------------------------- |
| 401  | 401  | Missing or invalid Bearer token.                            |
| 404  | 404  | Job not found or does not belong to you.                    |
| 409  | 409  | Invalid state transition (e.g., pausing a non-running job). |
| 500  | 500  | Internal server error.                                      |


## Related topics

- [Manually intervene in a running training job](/api-reference/pin/jobs/intervene.md)
- [Delete or cancel a training job](/api-reference/pin/jobs/delete.md)
- [Create Training Job with PIN API](/api-reference/pin/jobs/create.md)
- [Delete an Agent](/api-reference/pin/agents/delete.md)
- [Configure automatic intervention guardrails for training jobs](/api-reference/pin/jobs/auto-intervention.md)