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

# Configure automatic intervention guardrails for training jobs

> Get or update automatic intervention rules for a running job. Rules fire when metrics cross thresholds over configurable windows.

Automatic intervention lets you define guardrails that fire when training metrics deviate from baselines. You can configure rules for reward spikes, KL divergence explosions, response length surges, and repetition increases. Only running jobs can have their auto-intervention config updated.

## Method + Path

```http theme={null}
GET /v1/jobs/:id/auto-intervention
PUT /v1/jobs/:id/auto-intervention
```

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

## GET response

Returns the current auto-intervention configuration for the job inside the standard PIN envelope.

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

<ResponseField name="data" type="object" required>
  <Expandable title="properties">
    <ResponseField name="enabled" type="boolean">
      Whether auto-intervention is active.
    </ResponseField>

    <ResponseField name="rules" type="array">
      List of rules.

      <Expandable title="rule object">
        <ResponseField name="id" type="string">
          Unique rule identifier.
        </ResponseField>

        <ResponseField name="metric" type="string">
          Metric to watch: `reward`, `kl`, `response_len`, `repeat`.
        </ResponseField>

        <ResponseField name="condition" type="string">
          Condition type: `spike`, `drop`, `kl_explode`, `len_surge`, `repeat_up`.
        </ResponseField>

        <ResponseField name="window_steps" type="integer">
          Long-term window size in steps (10 to 100000).
        </ResponseField>

        <ResponseField name="threshold" type="number">
          Ratio threshold for triggering (must be greater than 0).
        </ResponseField>

        <ResponseField name="min_consecutive" type="integer">
          Consecutive hits required before firing (1 to window\_steps).
        </ResponseField>

        <ResponseField name="action" type="string">
          Action to take: `stop` or `update_hyperparams`.
        </ResponseField>

        <ResponseField name="hyperparams" type="object">
          New hyperparameters when action is `update_hyperparams`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="cooldown_seconds" type="integer">
      Cooldown between repeated triggers of the same rule.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example GET response

```json theme={null}
{
  "code": 0,
  "data": {
    "enabled": true,
    "rules": [
      {
        "id": "reward_spike",
        "metric": "reward",
        "condition": "spike",
        "window_steps": 100,
        "threshold": 2.0,
        "min_consecutive": 3,
        "action": "stop"
      }
    ],
    "cooldown_seconds": 300
  },
  "message": ""
}
```

## PUT request body

<ParamField body="enabled" type="boolean" required>
  Turn auto-intervention on or off.
</ParamField>

<ParamField body="rules" type="array" required>
  List of rule objects (see schema above).
</ParamField>

<ParamField body="cooldown_seconds" type="integer" required>
  Minimum seconds between repeated triggers for the same rule (must not be negative).
</ParamField>

### Request body example

```json theme={null}
{
  "enabled": true,
  "rules": [
    {
      "id": "reward_spike",
      "metric": "reward",
      "condition": "spike",
      "window_steps": 100,
      "threshold": 2.0,
      "min_consecutive": 3,
      "action": "stop"
    },
    {
      "id": "kl_explode",
      "metric": "kl",
      "condition": "kl_explode",
      "window_steps": 50,
      "threshold": 3.0,
      "min_consecutive": 2,
      "action": "update_hyperparams",
      "hyperparams": {
        "lr": 0.000005,
        "group_size": 2
      }
    }
  ],
  "cooldown_seconds": 300
}
```

## PUT request example

<CodeGroup>
  ```bash curl theme={null}
  curl -s -X PUT "https://api.ariacompute.com/v1/jobs/jb_abc123def456/auto-intervention" \
    -H "Authorization: Bearer $PIN_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "enabled": true,
      "rules": [
        {
          "id": "reward_spike",
          "metric": "reward",
          "condition": "spike",
          "window_steps": 100,
          "threshold": 2.0,
          "min_consecutive": 3,
          "action": "stop"
        }
      ],
      "cooldown_seconds": 300
    }'
  ```
</CodeGroup>

## PUT response

Returns the updated configuration inside the standard PIN envelope.

<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="auto_intervention" type="object">
      The updated configuration.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example PUT response

```json theme={null}
{
  "code": 0,
  "data": {
    "job_id": "jb_abc123def456",
    "auto_intervention": {
      "enabled": true,
      "rules": [
        {
          "id": "reward_spike",
          "metric": "reward",
          "condition": "spike",
          "window_steps": 100,
          "threshold": 2.0,
          "min_consecutive": 3,
          "action": "stop"
        }
      ],
      "cooldown_seconds": 300
    }
  },
  "message": ""
}
```

## Errors

| Code | HTTP | Meaning                                                                                           |
| ---- | ---- | ------------------------------------------------------------------------------------------------- |
| 401  | 401  | Missing or invalid Bearer token.                                                                  |
| 404  | 404  | Job not found, does not belong to you, or auto-intervention is disabled globally.                 |
| 409  | 409  | Job is not running (only running jobs can be updated).                                            |
| 422  | 422  | Invalid rule configuration (duplicate IDs, invalid metric/condition/action, out-of-range values). |


## Related topics

- [Delete or cancel a training job](/api-reference/pin/jobs/delete.md)
- [Manually intervene in a running training job](/api-reference/pin/jobs/intervene.md)
- [Node Agent Control Channel and Interventions](/api-reference/pin/node-agent/control.md)
- [Create Training Job with PIN API](/api-reference/pin/jobs/create.md)
- [Pause, resume, start, or stop a training job](/api-reference/pin/jobs/lifecycle.md)