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

# Manually intervene in a running training job

> Send a manual intervention to a running job to stop training or update hyperparameters on the fly. Only running jobs can be intervened.

Use this endpoint to manually intervene in a running training job. You can either stop the job immediately or hot-change a subset of hyperparameters (learning rate, epochs, beta, group size) without restarting the container.

## Method + Path

```http theme={null}
POST /v1/jobs/:id/intervene
```

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

<ParamField body="action" type="string" required>
  Intervention action. Must be `stop` or `update_hyperparams`.
</ParamField>

<ParamField body="reason" type="string" optional>
  Human-readable reason for the intervention (logged for audit).
</ParamField>

<ParamField body="hyperparams" type="object" optional>
  New hyperparameters when action is `update_hyperparams`. Only these fields may be hot-changed: `lr`, `epochs`, `beta`, `group_size`.
</ParamField>

### Request body example

```json theme={null}
{
  "action": "update_hyperparams",
  "reason": "Reduce LR after spike",
  "hyperparams": {
    "lr": 0.00001,
    "epochs": 5
  }
}
```

## Request example

<CodeGroup>
  ```bash curl theme={null}
  curl -s -X POST "https://api.ariacompute.com/v1/jobs/jb_abc123def456/intervene" \
    -H "Authorization: Bearer $PIN_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "update_hyperparams",
      "reason": "Reduce LR after spike",
      "hyperparams": {
        "lr": 0.00001,
        "epochs": 5
      }
    }'
  ```
</CodeGroup>

## Response

Returns a standard PIN success envelope with the intervention record.

<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="action" type="string">
      The requested action.
    </ResponseField>

    <ResponseField name="status" type="string">
      Intervention status: `pending`, `applied`, or `failed`.
    </ResponseField>

    <ResponseField name="intervention_id" type="string">
      Unique identifier for this intervention.
    </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",
    "action": "update_hyperparams",
    "status": "pending",
    "intervention_id": "iv_7a8b9c0d1e2f"
  },
  "message": ""
}
```

## Errors

| Code | HTTP | Meaning                                                              |
| ---- | ---- | -------------------------------------------------------------------- |
| 401  | 401  | Missing or invalid Bearer token.                                     |
| 404  | 404  | Job not found, does not belong to you, or intervention is disabled.  |
| 409  | 409  | Job is not running (only running jobs can be intervened).            |
| 422  | 422  | Invalid action or hyperparameters contain non-hot-changeable fields. |


## Related topics

- [Delete or cancel a training job](/api-reference/pin/jobs/delete.md)
- [Pause, resume, start, or stop a training job](/api-reference/pin/jobs/lifecycle.md)
- [Configure automatic intervention guardrails for training jobs](/api-reference/pin/jobs/auto-intervention.md)
- [Create Training Job with PIN API](/api-reference/pin/jobs/create.md)
- [List training jobs with status, type, and project filters](/api-reference/pin/jobs/list.md)