# Update an Agent Insights monitor

`PATCH /agent_insight_monitors/{monitor_id}`

## Parameters

### Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `monitor_id` | `string` | Yes | The identifier of the monitor. |

### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `api-version` | `string` | Yes | The API version to use for this operation. |

### Header parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `Foundry-Features` | `enum` | Yes | A feature flag opt-in required when using preview operations or modifying persisted preview resources. _Constant:_ `AgentInsights=V1Preview` |

## Request Body

Content-Type: `application/merge-patch+json` *(required)*

The monitor fields to update.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `enabled` | `boolean` | No | Whether scheduled insight generation is armed for the monitor. |
| `run_interval_hours` | `number` | No | Interval between scheduled insight runs, in hours. _Format:_ `double` |
| `model_deployment_name` | `string` | No | The model deployment to use for analyzing traces. Accepts either the deployment name alone or with the connection name as '{connectionName}/modelDeploymentName'. |
| `overview_override` | `AgentInsightsOverviewOverride \| null` | No | Sets the effective user overview, or clears it when explicitly set to null. Omission leaves the overview unchanged. This field cannot be combined with other monitor updates. |

### `overview_override` — `AgentInsightsOverviewOverride | null`

Sets the effective user overview, or clears it when explicitly set to null. Omission leaves the overview unchanged. This field cannot be combined with other monitor updates.

**One of the following:**

#### `AgentInsightsOverviewOverride` — `AgentInsightsOverviewOverride`

A user-provided overview that becomes effective immediately and seeds the next generation.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `content` | `string` | Yes | The nonblank overview content, limited to 64 KiB when encoded as UTF-8. |

#### `null` — `null`

| Type | Description |
|------|-------------|
| `null` | — |

## Responses

### 200 — The request has succeeded.

Content-Type: `application/json`

A per-agent Agent Insights monitor that owns configuration, runs, and discovered insights.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | `string` | Yes | The monitor identifier. |
| `agent_name` | `string` | Yes | The agent this monitor analyzes. There can be only one monitor per agent. |
| `enabled` | `boolean` | Yes | Whether scheduled insight generation is armed for the monitor. |
| `run_interval_hours` | `number` | Yes | Interval between scheduled insight runs, in hours. _Format:_ `double` |
| `model_deployment_name` | `string` | Yes | The model deployment to use for analyzing traces. Accepts either the deployment name alone or with the connection name as '{connectionName}/modelDeploymentName'. |
| `next_scheduled_run_at` | `FoundryTimestamp` | No | _Format:_ `unixtime` |
| `estimated_cost` | `AgentInsightEstimatedCost` | No | Estimated Agent Insights cost. |
| `suspension` | `AgentInsightSuspension \| null` | Yes | Why the system suspended scheduled generation. Null when the monitor is not suspended. |
| `overview` | `AgentInsightsOverview \| null` | Yes | The effective overview, or null before an overview is available. |
| `updated_at` | `FoundryTimestamp` | Yes | _Format:_ `unixtime` |

#### `estimated_cost` — `AgentInsightEstimatedCost`

Estimated Agent Insights cost.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `amount` | `number` | Yes | Estimated cost amount. _Format:_ `double` |
| `currency` | `enum` | Yes | Currency for the estimated cost amount. Agent Insights estimates are reported in US dollars. _Constant:_ `USD` |

#### `suspension` — `AgentInsightSuspension | null`

Why the system suspended scheduled generation. Null when the monitor is not suspended.

**One of the following:**

##### `AgentInsightSuspension` — `AgentInsightSuspension`

Structured reason why scheduled generation is suspended for a monitor.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `code` | `string` | Yes | Stable, machine-readable suspension category. |
| `message` | `string` | Yes | Human-readable description of the suspension. |
| `occurred_at` | `FoundryTimestamp` | Yes | _Format:_ `unixtime` |
| `details` | `object` | No | Additional reason-specific suspension details. |

##### `null` — `null`

| Type | Description |
|------|-------------|
| `null` | — |

#### `overview` — `AgentInsightsOverview | null`

The effective overview, or null before an overview is available.

**One of the following:**

##### `AgentInsightsOverview` — `AgentInsightsOverview`

The effective overview for an Agent Insights monitor.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `content` | `string` | Yes | The overview content. |
| `source` | `enum` | Yes | Identifies where an Agent Insights overview came from. _Enum:_ `generated`, `user_override` |
| `updated_at` | `FoundryTimestamp` | Yes | _Format:_ `unixtime` |

##### `null` — `null`

| Type | Description |
|------|-------------|
| `null` | — |

### 4XX — Client error

Content-Type: `application/json`

Error response for API failures.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `error` | `OpenAI.Error` | Yes |  |

#### `error` — `OpenAI.Error`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `code` | `string \| null` | Yes |  |
| `message` | `string` | Yes |  |
| `param` | `string \| null` | No |  |
| `type` | `string` | No |  |
| `misalignment` | `OpenAI.MisalignmentErrorDetailsResource` | No |  |
| `details` | `OpenAI.Error[]` | No |  |
| `additionalInfo` | `object` | No |  |
| `debugInfo` | `object` | No |  |

##### `misalignment` — `OpenAI.MisalignmentErrorDetailsResource`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `error_type` | `enum` | No | _Enum:_ `potentially_unintended_data_transfer`, `potentially_unintended_data_access`, `potentially_unintended_destructive_activity`, `other` |
| `detailed_explanation` | `string` | No | The public explanation for this block. |
| `steer` | `OpenAI._MisalignmentSteer` | No |  |

###### `steer` — `OpenAI._MisalignmentSteer`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `message` | `string` | Yes | The public continuation instruction. |

### 5XX — Server error

Content-Type: `application/json`

Error response for API failures.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `error` | `OpenAI.Error` | Yes |  |

#### `error` — `OpenAI.Error`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `code` | `string \| null` | Yes |  |
| `message` | `string` | Yes |  |
| `param` | `string \| null` | No |  |
| `type` | `string` | No |  |
| `misalignment` | `OpenAI.MisalignmentErrorDetailsResource` | No |  |
| `details` | `OpenAI.Error[]` | No |  |
| `additionalInfo` | `object` | No |  |
| `debugInfo` | `object` | No |  |

##### `misalignment` — `OpenAI.MisalignmentErrorDetailsResource`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `error_type` | `enum` | No | _Enum:_ `potentially_unintended_data_transfer`, `potentially_unintended_data_access`, `potentially_unintended_destructive_activity`, `other` |
| `detailed_explanation` | `string` | No | The public explanation for this block. |
| `steer` | `OpenAI._MisalignmentSteer` | No |  |

###### `steer` — `OpenAI._MisalignmentSteer`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `message` | `string` | Yes | The public continuation instruction. |