# List current insights for an Agent Insights monitor

`GET /agent_insight_monitors/{monitor_id}/insights`

## Parameters

### Path parameters

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

### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `after` | `string` | No | A cursor that identifies the last item in the previous page. |
| `before` | `string` | No | A cursor that identifies the first item in the next page. |
| `limit` | `integer` | No | The maximum number of items to return. Defaults to 20. _Default:_ `20` |
| `order` | `PageOrder` | No | Sort order by creation time. Defaults to descending. _Default:_ `"desc"` _Enum:_ `asc`, `desc` |
| `category` | `string` | No | Filter insights by category. |
| `severity` | `enum` | No | Filter insights by severity. _Enum:_ `high`, `medium`, `low` |
| `status` | `enum` | No | Filter insights by lifecycle status. _Enum:_ `active`, `resolved`, `ignored` |
| `include_details` | `boolean` | No | Whether to include expanded insight details such as evidence and run links in the response. Defaults to false. _Default:_ `false` |
| `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` |

## Responses

### 200 — The request has succeeded.

Content-Type: `application/json`

The response data for a requested list of items.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `data` | `AgentInsight[]` | Yes | The requested list of items. |
| `first_id` | `string` | No | The first ID represented in this list. |
| `last_id` | `string` | No | The last ID represented in this list. |
| `has_more` | `boolean` | Yes | A value indicating whether there are additional values available not captured in this list. |

#### `data` — `AgentInsight[]`

The requested list of items.

**Array of** `AgentInsight`**:**

A persisted issue discovered from an agent's traces.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | `string` | Yes | The insight identifier. |
| `monitor_id` | `string` | Yes | The Agent Insights monitor this insight belongs to. |
| `agent_name` | `string` | Yes | The agent this insight belongs to. |
| `agent_version` | `string` | Yes | The latest immutable agent version associated with this insight. |
| `title` | `string` | Yes | A short title for the issue. |
| `severity` | `enum` | Yes | The severity of an agent insight. _Enum:_ `high`, `medium`, `low` |
| `category` | `string` | Yes | An open, service-generated category label for the issue. Clients must accept previously unseen values. |
| `status` | `enum` | Yes | The lifecycle status of an agent insight. _Enum:_ `active`, `resolved`, `ignored` |
| `trace_count` | `integer` | Yes | The number of traces that provide evidence for this insight. _Format:_ `int32` |
| `created_at` | `FoundryTimestamp` | Yes | _Format:_ `unixtime` |
| `updated_at` | `FoundryTimestamp` | Yes | _Format:_ `unixtime` |
| `description` | `string` | Yes | The root-cause diagnosis for the issue. |
| `details` | `AgentInsightDetails` | No | Additional insight details. Omitted unless details are requested. |

##### `details` — `AgentInsightDetails`

Additional insight details. Omitted unless details are requested.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `highlighted_traces` | `AgentInsightHighlightedTrace[]` | Yes | Up to 5 highlighted traces that provide evidence for this insight. |
| `linked_traces` | `AgentInsightLinkedTrace[]` | Yes | Up to 200 most recent traces linked to this insight as supporting evidence. |
| `recommended_actions` | `AgentInsightRecommendedAction` | Yes | The recommended remediation for an agent insight. |

###### `highlighted_traces` — `AgentInsightHighlightedTrace[]`

Up to 5 highlighted traces that provide evidence for this insight.

**Array of** `AgentInsightHighlightedTrace`**:**

A highlighted trace that provides evidence for an agent insight.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `trace_id` | `string` | Yes | The trace identifier. |
| `summary` | `string` | Yes | A short summary of the trace. |
| `duration_ms` | `FoundryDurationMilliseconds` | Yes | A duration encoded as an integer number of milliseconds. _Format:_ `int32` |
| `total_tokens` | `integer` | No | Aggregate input and output tokens reported across all model inference calls in this trace, including calls to different models. Intended for relative usage comparison, not cost estimation. _Format:_ `int32` |
| `timestamp` | `FoundryTimestamp` | Yes | _Format:_ `unixtime` |

###### `linked_traces` — `AgentInsightLinkedTrace[]`

Up to 200 most recent traces linked to this insight as supporting evidence.

**Array of** `AgentInsightLinkedTrace`**:**

A lightweight trace reference linked to an agent insight as supporting evidence.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `trace_id` | `string` | Yes | The trace identifier. |
| `timestamp` | `FoundryTimestamp` | Yes | _Format:_ `unixtime` |

###### `recommended_actions` — `AgentInsightRecommendedAction`

The recommended remediation for an agent insight.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `proposed_fix` | `AgentInsightProposedFix` | Yes | A recommended fix for an agent insight. |

- **`proposed_fix`** — `AgentInsightProposedFix`

A recommended fix for an agent insight.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `kind` | `enum` | Yes | The customer-renderable kind of an agent insight's proposed fix. _Enum:_ `prose`, `code_change`, `prompt_change` |
| `text` | `string` | Yes | The human-readable remediation guidance. |
| `changes` | `AgentInsightProposedFixChange[]` | No | The concrete changes. Omitted for a prose-only fix. |

- **`changes`** — `AgentInsightProposedFixChange[]`

The concrete changes. Omitted for a prose-only fix.

**Array of** `AgentInsightProposedFixChange`**:**

A customer-renderable change in a proposed fix.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `path` | `string` | No | The source path changed by a code change. |
| `language` | `string` | No | The language of the changed source path. |
| `diff` | `string` | No | The unified diff for the changed source path. |
| `surface` | `enum` | No | The Prompt surface changed by a proposed fix. _Enum:_ `instructions`, `tool` |
| `target` | `string` | No | The user-visible target within a Prompt surface, when needed. |
| `old_value` | `any \| null` | No | The bounded Prompt value before the change. Present for Prompt changes, including when null. |
| `new_value` | `any \| null` | No | The bounded Prompt value after the change. Present for Prompt changes, including when 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. |