Check a single Event against the Policies and Metrics selected by active Conditions in your Environment. Use this endpoint for one message, tool output, function call, agent update, reasoning, or inline image artifact.
How It Works
- You submit one Event with a
type, one content field, and optionalmetadata - Conditions match the Event’s metadata and select Policies and Metrics.
- Event selectors filter them to the submitted type and field
- You receive synchronous Policy results, and selected Metrics continue asynchronously.
Content Fields
Provide exactly one content field per Event.
tool.arguments and function.arguments accept any JSON value, including a string, number, boolean, null, array, or nested object. White Circle preserves the JSON shape for moderation.
For an artifact image with raw base64 data, mime_type is optional for JPEG, PNG, WebP, and GIF content. White Circle detects the image type from the decoded bytes.
Response Overview
flagged and policies are present only when status is completed. For any other status no check ran, so the response states no verdict rather than reporting false.
note explains why:
Each Policy object includes:
flagged— Whether this Policy was violatedname— Human-readable Policy nameenabled_by_conditions— The Conditions that selected this Policy for this Event, which is why it was evaluated. Absent when no Condition was involved.shadow— Present andtrueonly for shadow-mode Policies returned viainclude_shadow. A shadow result never affects the top-levelflaggedverdict. Absent for production Policies.
Conditions and Metadata
White Circle evaluates active Conditions against the metadata object on this Event. Matching Conditions select the applicable Policies and Metrics. Event selectors then filter them to this Event’s type, field, and direction.
Selected Metrics run asynchronously and are not returned in the synchronous policies map. View Metric results in the dashboard after processing completes.
See Conditions for expression syntax and Policy or Metric attachments.
Parents and Links
parent_event_id and links record how Events relate inside your agent: which step produced an Event, and which outputs it used. White Circle stores them as a run graph that you can load with Get a Run Graph and browse in the dashboard. For a full walkthrough with sub-agents, see Runs and the Event Graph.
In this example, the main agent merges the results of two sub-agent runs into its final answer:
JSON
{
"event": {
"type": "message",
"role": "assistant",
"content": "Combined result",
"links": [
{ "run_id": "run_security", "event_id": "security_output" },
{ "run_id": "run_tests", "event_id": "test_output" }
],
"event_id": "final_answer",
"parent_event_id": "main_agent"
},
"environment_id": "environment_123",
"run_id": "run_main"
}The parent and link targets do not have to exist yet. The run graph keeps the reference and resolves it when the target Event arrives.
Where Parents and Links Appear
- Run graph API. Get a Run Graph returns a
parentedge for eachparent_event_idand alinkedge for each entry inlinks. - Dashboard. The Runs page draws parent edges as the run tree and breadcrumbs, and shows links as causal inputs, including inputs from other runs.
Tool Call Pairing
When a tool or function Event sends output without a call_id, White Circle pairs it with the call whose event_id matches the output’s parent_event_id. The model then sees the arguments and the output as one call.
JSON
[
{ "type": "tool", "name": "lookup_order", "event_id": "lookup_args", "arguments": { "order_id": "4815" } },
{ "type": "tool", "name": "lookup_order", "event_id": "lookup_result", "parent_event_id": "lookup_args", "output": { "refund_eligible": true } }
]Sending the same call_id on both Events pairs them the same way.
Sub-agents
Send a sub-agent’s Events in the same run as the agent that started it, and set the parent_event_id of the sub-agent’s first Event to the step that started it. Each sub-agent then becomes its own branch of the run tree. Use links when an Event consumes another branch’s output, or an Event from another run. A parent must be in the same run, so connections between runs always use links.
Validation
Reference-only Events cannot declare parent_event_id or links, because references are read-only lookups.
White Circle returns 400 for self-parenting, self-links, duplicate links, direct mutual parents such as A → B → A, and parent cycles inside one batch. It does not check for longer cycles across earlier requests.
White Circle also returns 400 when finished_at is earlier than started_at. See Execution Timing.
Event Identity and Retries
run_id and event_id help you connect Events to your own application data. They are not retry keys. If you submit the same run_id and event_id again, White Circle may run another check. The latest durable attempt (completed or failed) defines the current graph relationships. Each retry replaces the complete parent/link declaration set; omitted relationships are cleared from the current graph.
Use internal_event_id to refer to one saved result.
Reference an Existing Event
To reference an existing Event, send the type and event_id without a content field. White Circle returns referenced when the latest matching result has the same Event type. Otherwise, it returns not_found.
Authorizations
Headers
Body
application/json
environment_idstringrequiredEnvironment whose Conditions, Policies, and Metrics apply. Required on every request.
eventobjectrequiredThe Event to check or reference.
Show child attributesHide child attributes
event.type enum<string>requiredKind of Event. Determines which content fields are allowed and which Policies can apply.
Available options:
message,artifact,tool,function,agent,reasoningevent.role string | nullWho produced the content:
user,assistant,system,developer, ortool. Required formessageEvents with content unless the request sets a top-levelrole. Overrides the Policy direction of other Event types; when omitted, White Circle picks it from the type and field, for exampletool.outputasassistant.event.content anyContent to check for
message,artifact, andreasoningEvents. Messages and reasoning take text; artifacts take an image object.event.delta anyAn incremental chunk of a streamed
messageorreasoningEvent. Each delta is checked as its own Event; White Circle does not join deltas, so send chunks large enough to judge, such as every N tokens or sentences.event.arguments anyArguments of a
toolorfunctioncall. Accepts any JSON value; White Circle keeps its shape.event.output anyResult of a
tool,function, oragent. Accepts any JSON value.event.definition anySchema or description of a
toolorfunction, such as an OpenAI tool definition. Accepts any JSON value.event.input anyTask or input given to an
agent, checked as user-direction content.event.instructions anySystem instructions given to an
agent. Enters context with thesystemrole.event.state anySnapshot of an
agent's internal state.event.event_id string | nullYour ID for this Event. Required for reference-only Events. Generated when omitted for Events with content. Not a retry key: sending the same
run_idandevent_idagain runs a new check. Up to 128 characters: letters, numbers,.,_,:, and-.event.run_id string | nullRun for this Event. Overrides the top-level
run_id. Up to 128 characters: letters, numbers,.,_,:, and-.event.external_session_id string | nullSession for this Event. Overrides the top-level
external_session_id. Up to 256 characters.event.parent_event_id string | nullevent_idof this Event's structural parent in the same run, such as the agent step that produced it. Appears as aparentedge in the run graph and pairs a tool or functionoutputwith the call that has thisevent_idwhen you send nocall_id. Not allowed on reference-only Events. Up to 128 characters: letters, numbers,.,_,:, and-.event.links object[]Causal inputs this Event consumed, in this run or in other runs of the same Environment. Each appears as a
linkedge in the run graph. Up to 50 per Event. Not allowed on reference-only Events.event.external_artifact_id string | nullYour ID for the image in an
artifactEvent. Used as theevent_idwhen you omitevent_id. Up to 256 characters.event.name string | nullName of the tool, function, agent, or artifact, such as
lookup_order. Up to 256 characters.event.call_id string | nullYour ID for one tool or function invocation. Send the same
call_idon theargumentsandoutputEvents so the model sees them as one call. Up to 256 characters.event.stream_id string | nullYour ID for the stream a
deltabelongs to. Stored and returned in the run graph; does not change how deltas are checked. Up to 256 characters.event.sequence integer<int64> | nullPosition of this chunk in its stream. Stored and returned in the run graph.
event.format string | nullFree-form label for the content format, such as
markdown. Stored only. Up to 256 characters.event.started_at string<date-time> | nullWhen the work behind this Event started in your system, as RFC 3339. Shown on the Event with
finished_atas its duration. Display only: it does not change Event ordering orcreated_at.event.finished_at string<date-time> | nullWhen the work behind this Event finished in your system, as RFC 3339. Must not be earlier than
started_at. Display only: it does not change Event ordering orcreated_at.event.metadata anyCustom JSON object, up to 256 KiB. Conditions match against it to select Policies and Metrics for this Event.
run_idstring | nullYour ID for a group of related Events, such as one agent run. Defaults to
external_session_idwhen omitted.parent_event_idand same-runlinksresolve inside this run. Up to 128 characters: letters, numbers,.,_,:, and-.external_session_idstring | nullYour conversation or session ID. Reuse it for every Event in the same conversation. See Event Context. Up to 256 characters.
rolestring | nullDefault role for
messageandartifactEvents that do not set their ownrole. Other Event types ignore it.include_shadowboolean | nullAlso return shadow-policy results (each marked
shadow: true). Shadow results never affect the top-levelflagged/violationverdict.
Response
Success
eventobjectrequiredIdentity and status of the Event that was submitted.
Show child attributesHide child attributes
event.type enum<string>requiredKind of Event that was submitted.
Available options:
message,artifact,tool,function,agent,reasoningevent.status enum<string>requiredOutcome for this Event.
Available options:
completed,failed,referenced,not_foundevent.event_id stringrequiredYour
event_id, or the generated one when you omitted it.event.internal_event_id string | nullWhite Circle's ID for this saved result. Use it with
GET /api/event/{internal_event_id}. Each check gets a new value, even whenrun_idandevent_idrepeat.
run_idstringrequiredRun the Event was recorded in.
flaggedboolean | nullAbsent when no check ran, such as a reference, a failure, or an Event no Condition selected policies for.
policiesobject | nullPolicy results keyed by Policy ID. Present only when
statusiscompleted. Contains only the Policies that Conditions selected for this Event.Show child attributesHide child attributes
policies.{key} objectShow child attributesHide child attributes
policies.{key}. flagged booleanrequiredWhether this Event violated the Policy.
policies.{key}. name stringrequiredHuman-readable Policy name.
policies.{key}. enabled_by_conditions object[] | nullThe Conditions that selected this Policy for this Event, which is why it was evaluated at all.
policies.{key}. shadow booleanPresent and
trueonly for shadow policies surfaced viainclude_shadow. A shadow result never affects the top-level verdict.
notestring | nullWhy no verdict was produced: no Condition selected a Policy or Metric, a reference did not resolve, or the Event failed validation or checking.
Bad Request