# Start an Agent Insights run for a monitor

`POST /agent_insight_monitors/{monitor_id}/runs`

## 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` |
| `Operation-Id` | `string` | No | Client-generated unique ID for idempotent retries. When absent, the server creates the job unconditionally. |

## Request Body

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

Run inputs. Send an empty object to use the default 168-hour lookback window.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `lookback_hours` | `number` | No | Optional finite positive number of hours of trace history to analyze, up to 2,160. Defaults to 168. _Default:_ `168` _Format:_ `double` |

## Responses

### 201 — The request has succeeded and a new resource has been created as a result.

Content-Type: `application/json`

A long-running run that analyzes one agent's traces and updates that agent's insights.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | `string` | Yes | Server-assigned unique identifier. |
| `inputs` | `AgentInsightRunCreate` | No | Inputs used when creating an agent insight run. |
| `result` | `AgentInsightRunResult` | No | Result statistics produced when an agent insight run succeeds. |
| `status` | `enum` | Yes | Extensible status values shared by Foundry jobs. _Enum:_ `queued`, `in_progress`, `succeeded`, `failed`, `cancelled` |
| `error` | `OpenAI.Error` | No |  |
| `monitor_id` | `string` | Yes | The Agent Insights monitor this run belongs to. |
| `agent_name` | `string` | Yes | The agent whose traces are analyzed by this run. |
| `trigger` | `enum` | Yes | The trigger that started an agent insight run. _Enum:_ `on_demand`, `scheduled` |
| `created_at` | `FoundryTimestamp` | Yes | _Format:_ `unixtime` |
| `updated_at` | `FoundryTimestamp` | Yes | _Format:_ `unixtime` |
| `window_start` | `FoundryTimestamp` | Yes | _Format:_ `unixtime` |
| `window_end` | `FoundryTimestamp` | Yes | _Format:_ `unixtime` |
| `started_at` | `FoundryTimestamp` | No | _Format:_ `unixtime` |
| `completed_at` | `FoundryTimestamp` | No | _Format:_ `unixtime` |
| `model_deployment_name` | `string` | Yes | The model deployment used to analyze traces for this run. |

#### `inputs` — `AgentInsightRunCreate`

Inputs used when creating an agent insight run.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `lookback_hours` | `number` | No | Optional finite positive number of hours of trace history to analyze, up to 2,160. Defaults to 168. _Default:_ `168` _Format:_ `double` |

#### `result` — `AgentInsightRunResult`

Result statistics produced when an agent insight run succeeds.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `traces_in_window` | `integer` | Yes | The number of traces in the analyzed time window. _Format:_ `int32` |
| `traces_analyzed` | `integer` | Yes | The number of traces analyzed by the run. _Format:_ `int32` |
| `insights_created` | `integer` | Yes | The number of insights created by the run. _Format:_ `int32` |
| `insights_updated` | `integer` | Yes | The number of insights updated by the run. _Format:_ `int32` |
| `insights_reopened` | `integer` | Yes | The number of insights reopened by the run. _Format:_ `int32` |
| `token_usage` | `AgentInsightTokenUsage` | Yes | Token usage for an Agent Insights run. |

##### `token_usage` — `AgentInsightTokenUsage`

Token usage for an Agent Insights run.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `input_tokens` | `integer` | Yes | The number of input tokens used by the run. _Format:_ `int32` |
| `output_tokens` | `integer` | Yes | The number of output tokens used by the run. _Format:_ `int32` |
| `cached_tokens` | `integer` | No | The number of input tokens served from cache. _Format:_ `int32` |
| `total_tokens` | `integer` | Yes | The total number of tokens used by the run. _Format:_ `int32` |

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

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