Repository Public
1# Misalignment monitoring23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45Misalignment monitoring checks whether an agent is properly interpreting the user's instructions in consequential contexts, such as transferring sensitive data, accessing sensitive data, or making destructive changes. It reviews model reasoning and actions asynchronously and can stop a conversation when it identifies a potential issue.67A flag indicates that the agent's actions need review. It does not establish that the user violated a policy or that the agent acted contrary to instructions. Monitoring can miss issues or flag legitimate activity, so continue to use [application safeguards](https://developers.openai.com/api/docs/guides/safety-best-practices), including human approval for consequential actions.89For more context, see the [misalignment monitoring overview in the Help Center](https://help.openai.com/articles/20001509).1011## Request coverage1213For models covered by this system, monitoring and automatic stopping depend on the request's API and how it preserves conversation context:1415| Requests | Behavior |16| ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |17| Responses API requests using persisted reasoning, WebSockets, or OpenAI compaction | Monitored. The system can identify continuations of a conversation and block further execution. |18| Responses API requests using none of those mechanisms | Monitored. Configured webhooks can receive alerts, but the system does not automatically stop the conversation. |19| Chat Completions API requests | Not covered by this monitoring system. Other safety checks still apply. |2021See [preserving reasoning across calls](https://developers.openai.com/api/docs/guides/reasoning#preserve-reasoning-across-calls), [WebSocket mode](https://developers.openai.com/api/docs/guides/websocket-mode), and [compaction](https://developers.openai.com/api/docs/guides/conversation-state#compaction) for conversation context guidance. Configuring an alert webhook does not enable automatic stopping.2223## Handle a stopped request2425When misalignment monitoring blocks a request before streaming begins, the API returns HTTP `403`, with error type `invalid_request_error` and code `misalignment_policy_violation`. Match the error code rather than the message text. Streaming integrations must also handle errors while consuming the stream, even after receiving output.2627If your application receives this error:28291. Stop dispatching further actions for the affected conversation. Do not automatically retry the blocked workflow.302. Preserve the relevant request and response IDs, tool calls, and application records according to your data handling policies.313. Show the available error information to the user or operator responsible for the task. Have them compare the agent's actions with the intended work and review any changes already made.3233The API does not provide a general way to resume a conversation stopped by misalignment monitoring.3435Because monitoring is asynchronous, an action may already have completed before monitoring identifies a concern. A stopped request does not undo earlier actions.3637## Receive project safety alerts3839Subscribe to `safety.alert.created` to route monitoring alerts for an API project to a system your team operates. Receiving alerts does not replace handling errors on API requests.4041Follow [Creating webhook endpoints](https://developers.openai.com/api/docs/guides/webhooks#creating-webhook-endpoints) for each project whose alerts you want to receive. Use the Webhooks guide for [signature verification](https://developers.openai.com/api/docs/guides/webhooks#verifying-webhook-signatures), [acknowledgments, retries, and duplicate deliveries](https://developers.openai.com/api/docs/guides/webhooks#handling-webhook-requests-on-a-server).4243The webhook contains an alert ID, rather than the alert details:4445```json46{47 "object": "event",48 "id": "evt_123",49 "type": "safety.alert.created",50 "created_at": 1787659200,51 "data": {52 "id": "alert_0123456789abcdef0123456789abcdef"53 }54}55```5657After verifying and acknowledging the webhook, retrieve the alert in your background processing. Replace the illustrative `salert_123` value with `data.id` from the webhook. The event's `id` identifies the webhook event rather than the alert. Use an API key authorized for the same project with the `api.safety.alerts.read` permission:5859```bash60curl "https://api.openai.com/v1/safety/alerts/salert_123" \61 -H "Authorization: Bearer ${OPENAI_API_KEY}"62```6364Retrieve a project safety alert6566```javascript67// Replace the illustrative IDs and URLs below with your own resource values.68import OpenAI from "openai";6970const client = new OpenAI();71const alertId = "salert_123";7273const alert = await client.safety.alerts.retrieve(alertId);74console.log(alert.error_type, alert.reason, alert.response_id);75```7677```python78# Replace the illustrative IDs and URLs below with your own resource values.7980from openai import OpenAI8182client = OpenAI()83alert = client.safety.alerts.retrieve("salert_123")84print(alert.error_type, alert.reason)85```8687```go88// Replace the illustrative IDs and URLs below with your own resource values.89package main9091import (92 "context"93 "fmt"9495 "github.com/openai/openai-go/v3"96)9798func main() {99 client := openai.NewClient()100 alert, err := client.Safety.Alerts.Get(context.Background(), "salert_123")101 if err != nil {102 panic(err)103 }104 fmt.Println(alert.ErrorType)105 fmt.Println(alert.Reason)106 fmt.Println(alert.RequestPaused)107}108```109110```java111// Replace the illustrative IDs and URLs below with your own resource values.112import com.openai.models.safety.alerts.SafetyAlert;113114SafetyAlert alert = client.safety().alerts().retrieve("salert_123");115System.out.println(alert.errorType());116alert.reason().ifPresent(System.out::println);117System.out.println(alert.requestPaused());118```119120```ruby121# Replace the illustrative IDs and URLs below with your own resource values.122require "openai"123124client = OpenAI::Client.new125alert = client.safety.alerts.retrieve("salert_123")126puts(alert.error_type)127puts(alert.reason)128puts(alert.request_paused)129```130131132Use the returned `request_id` and `response_id` to find the affected work in your application records. Treat the alert category as a concern to investigate. When `request_paused` is `true`, registering a safety block succeeded; this does not confirm that execution stopped or that earlier actions were reversed. Check your application's task state and tool records.133134The alert's `reason` can be `null`, including for Zero Data Retention (ZDR) requests. A non-null `reason` is a category description, not a transcript or full investigation report. Keep the records you need under your organization's data policies. See [Your data](https://developers.openai.com/api/docs/guides/your-data) for API data controls.135136If retrieval returns `404` with code `safety_alert_not_found`, check the alert ID and project credentials. Missing, inaccessible, or incomplete records can return this error. Alert delivery and retrieval do not provide a complete audit history.