Check up to 50 Events in one request. Use this endpoint when you want to submit several related pieces of an interaction together, such as a user message, a tool result, and an assistant response.
How It Works
- You submit an
eventsarray containing 1 to 50 Event payloads - Conditions select the applicable Policies and Metrics for each Event
- White Circle evaluates Policies synchronously and queues Metrics asynchronously
- You receive one response with Policy results grouped by Event type
Each Event payload uses the same shape as Check One Event.
Conditions in a Batch
Conditions are evaluated separately for each Event. Put metadata on every Event that needs metadata-based Policy selection; metadata from one Event does not apply to another Event in the same batch.
JSON
{
"environment_id": "environment_123",
"events": [
{
"type": "message",
"role": "user",
"content": "Can you refund my order?",
"metadata": { "user": { "region": "eu" } }
},
{
"type": "tool",
"name": "lookup_order",
"output": { "refund_eligible": true },
"metadata": { "workflow": { "stage": "refund_review" } }
}
]
}Selected Metrics run asynchronously and are not included in the synchronous typed result buckets.
See Conditions for routing behavior.
Response Overview
Each result includes type, status, event_id, and internal_event_id, plus flagged, policies, and note when applicable. Each Policy result can include enabled_by_conditions with the Conditions that selected it.
Send include_shadow=true at the top level to also return shadow-mode Policies for every Event in the batch, each marked shadow: true. Shadow results never change any top-level flagged verdict.
Same-Batch References
A reference-only Event can point to another Event with content in the same batch. White Circle resolves same-batch references before looking up previous results.
JSON
{
"events": [
{
"type": "agent",
"state": {
"phase": "reviewing_refund"
},
"event_id": "evt_agent_state"
},
{
"type": "agent",
"event_id": "evt_agent_state"
}
],
"environment_id": "environment_123",
"run_id": "run_batch_ref"
}The second Event returns referenced if the first Event completes successfully.
Referencing Existing Events
If a reference-only Event does not match an Event with content in the same batch, White Circle looks up the latest result with the same run_id and event_id.
The reference returns:
Repeated Event IDs
You can submit multiple Events with content using the same event_id. White Circle checks and saves each one, and each completed check receives a different internal_event_id.
Partial Failures
Some per-Event validation failures return a failed result while the rest of the batch continues. For example, an invalid inline artifact can return status: "failed" while other Events are checked.
Request-level shape and relationship errors return 400 and reject the whole batch. This includes more than 50 Events, self-parenting, direct mutual parents involving a previously saved Event, and parent cycles declared within the batch.
Authorizations
Headers
Body
application/json
environment_idstringrequiredEnvironment whose Conditions, Policies, and Metrics apply. Required on every request.
eventsobject[]required1 to 50 Events. List them in the order they happened: each Event is checked against the Events listed before it.
Required array length:
1 - 50elementsShow child attributesHide child attributes
events.type enum<string>requiredKind of Event. Determines which content fields are allowed and which Policies can apply.
Available options:
message,artifact,tool,function,agent,reasoningevents.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.events.content anyContent to check for
message,artifact, andreasoningEvents. Messages and reasoning take text; artifacts take an image object.events.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.events.arguments anyArguments of a
toolorfunctioncall. Accepts any JSON value; White Circle keeps its shape.events.output anyResult of a
tool,function, oragent. Accepts any JSON value.events.definition anySchema or description of a
toolorfunction, such as an OpenAI tool definition. Accepts any JSON value.events.input anyTask or input given to an
agent, checked as user-direction content.events.instructions anySystem instructions given to an
agent. Enters context with thesystemrole.events.state anySnapshot of an
agent's internal state.events.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-.events.run_id string | nullRun for this Event. Overrides the top-level
run_id. Up to 128 characters: letters, numbers,.,_,:, and-.events.external_session_id string | nullSession for this Event. Overrides the top-level
external_session_id. Up to 256 characters.events.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-.events.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.events.external_artifact_id string | nullYour ID for the image in an
artifactEvent. Used as theevent_idwhen you omitevent_id. Up to 256 characters.events.name string | nullName of the tool, function, agent, or artifact, such as
lookup_order. Up to 256 characters.events.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.events.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.events.sequence integer<int64> | nullPosition of this chunk in its stream. Stored and returned in the run graph.
events.format string | nullFree-form label for the content format, such as
markdown. Stored only. Up to 256 characters.events.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.events.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.events.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-. Applies to every Event that does not set its own.external_session_idstring | nullYour conversation or session ID. Reuse it for every Event in the same conversation. See Event Context. Up to 256 characters. Applies to every Event that does not set its own.
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
flaggedbooleanrequiredtrueif any Event in the batch violated at least one Policy.messagesobject[]requiredResults for
messageEvents, in request order.Show child attributesHide child attributes
messages.type enum<string>requiredKind of Event that was submitted.
Available options:
message,artifact,tool,function,agent,reasoningmessages.status enum<string>requiredOutcome for this Event.
Available options:
completed,failed,referenced,not_foundmessages.event_id stringrequiredYour
event_id, or the generated one when you omitted it.messages.flagged boolean | nulltrueif this Event violated at least one Policy. Absent when no check ran.messages.policies object | 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
messages.policies. {key} objectShow child attributesHide child attributes
messages.policies. {key}. flagged booleanrequiredWhether this Event violated the Policy.
messages.policies. {key}. name stringrequiredHuman-readable Policy name.
messages.policies. {key}. enabled_by_conditions object[] | nullThe Conditions that selected this Policy for this Event, which is why it was evaluated at all.
messages.policies. {key}. shadow booleanPresent and
trueonly for shadow policies surfaced viainclude_shadow. A shadow result never affects the top-level verdict.
messages.note string | nullWhy no verdict was produced: no Condition selected a Policy or Metric, a reference did not resolve, or the Event failed validation or checking.
messages.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.
artifactsobject[]requiredResults for
artifactEvents, in request order.Show child attributesHide child attributes
artifacts.type enum<string>requiredKind of Event that was submitted.
Available options:
message,artifact,tool,function,agent,reasoningartifacts.status enum<string>requiredOutcome for this Event.
Available options:
completed,failed,referenced,not_foundartifacts.event_id stringrequiredYour
event_id, or the generated one when you omitted it.artifacts.flagged boolean | nulltrueif this Event violated at least one Policy. Absent when no check ran.artifacts.policies object | 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
artifacts.policies. {key} objectShow child attributesHide child attributes
artifacts.policies. {key}. flagged booleanrequiredWhether this Event violated the Policy.
artifacts.policies. {key}. name stringrequiredHuman-readable Policy name.
artifacts.policies. {key}. enabled_by_conditions object[] | nullThe Conditions that selected this Policy for this Event, which is why it was evaluated at all.
artifacts.policies. {key}. shadow booleanPresent and
trueonly for shadow policies surfaced viainclude_shadow. A shadow result never affects the top-level verdict.
artifacts.note string | nullWhy no verdict was produced: no Condition selected a Policy or Metric, a reference did not resolve, or the Event failed validation or checking.
artifacts.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.
toolsobject[]requiredResults for
toolEvents, in request order.Show child attributesHide child attributes
tools.type enum<string>requiredKind of Event that was submitted.
Available options:
message,artifact,tool,function,agent,reasoningtools.status enum<string>requiredOutcome for this Event.
Available options:
completed,failed,referenced,not_foundtools.event_id stringrequiredYour
event_id, or the generated one when you omitted it.tools.flagged boolean | nulltrueif this Event violated at least one Policy. Absent when no check ran.tools.policies object | 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
tools.policies. {key} objectShow child attributesHide child attributes
tools.policies. {key}. flagged booleanrequiredWhether this Event violated the Policy.
tools.policies. {key}. name stringrequiredHuman-readable Policy name.
tools.policies. {key}. enabled_by_conditions object[] | nullThe Conditions that selected this Policy for this Event, which is why it was evaluated at all.
tools.policies. {key}. shadow booleanPresent and
trueonly for shadow policies surfaced viainclude_shadow. A shadow result never affects the top-level verdict.
tools.note string | nullWhy no verdict was produced: no Condition selected a Policy or Metric, a reference did not resolve, or the Event failed validation or checking.
tools.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.
functionsobject[]requiredResults for
functionEvents, in request order.Show child attributesHide child attributes
functions.type enum<string>requiredKind of Event that was submitted.
Available options:
message,artifact,tool,function,agent,reasoningfunctions.status enum<string>requiredOutcome for this Event.
Available options:
completed,failed,referenced,not_foundfunctions.event_id stringrequiredYour
event_id, or the generated one when you omitted it.functions.flagged boolean | nulltrueif this Event violated at least one Policy. Absent when no check ran.functions.policies object | 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
functions.policies. {key} objectShow child attributesHide child attributes
functions.policies. {key}. flagged booleanrequiredWhether this Event violated the Policy.
functions.policies. {key}. name stringrequiredHuman-readable Policy name.
functions.policies. {key}. enabled_by_conditions object[] | nullThe Conditions that selected this Policy for this Event, which is why it was evaluated at all.
functions.policies. {key}. shadow booleanPresent and
trueonly for shadow policies surfaced viainclude_shadow. A shadow result never affects the top-level verdict.
functions.note string | nullWhy no verdict was produced: no Condition selected a Policy or Metric, a reference did not resolve, or the Event failed validation or checking.
functions.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.
agentsobject[]requiredResults for
agentEvents, in request order.Show child attributesHide child attributes
agents.type enum<string>requiredKind of Event that was submitted.
Available options:
message,artifact,tool,function,agent,reasoningagents.status enum<string>requiredOutcome for this Event.
Available options:
completed,failed,referenced,not_foundagents.event_id stringrequiredYour
event_id, or the generated one when you omitted it.agents.flagged boolean | nulltrueif this Event violated at least one Policy. Absent when no check ran.agents.policies object | 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
agents.policies. {key} objectShow child attributesHide child attributes
agents.policies. {key}. flagged booleanrequiredWhether this Event violated the Policy.
agents.policies. {key}. name stringrequiredHuman-readable Policy name.
agents.policies. {key}. enabled_by_conditions object[] | nullThe Conditions that selected this Policy for this Event, which is why it was evaluated at all.
agents.policies. {key}. shadow booleanPresent and
trueonly for shadow policies surfaced viainclude_shadow. A shadow result never affects the top-level verdict.
agents.note string | nullWhy no verdict was produced: no Condition selected a Policy or Metric, a reference did not resolve, or the Event failed validation or checking.
agents.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.
reasoningobject[]requiredResults for
reasoningEvents, in request order.Show child attributesHide child attributes
reasoning.type enum<string>requiredKind of Event that was submitted.
Available options:
message,artifact,tool,function,agent,reasoningreasoning.status enum<string>requiredOutcome for this Event.
Available options:
completed,failed,referenced,not_foundreasoning.event_id stringrequiredYour
event_id, or the generated one when you omitted it.reasoning.flagged boolean | nulltrueif this Event violated at least one Policy. Absent when no check ran.reasoning.policies object | 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
reasoning.policies. {key} objectShow child attributesHide child attributes
reasoning.policies. {key}. flagged booleanrequiredWhether this Event violated the Policy.
reasoning.policies. {key}. name stringrequiredHuman-readable Policy name.
reasoning.policies. {key}. enabled_by_conditions object[] | nullThe Conditions that selected this Policy for this Event, which is why it was evaluated at all.
reasoning.policies. {key}. shadow booleanPresent and
trueonly for shadow policies surfaced viainclude_shadow. A shadow result never affects the top-level verdict.
reasoning.note string | nullWhy no verdict was produced: no Condition selected a Policy or Metric, a reference did not resolve, or the Event failed validation or checking.
reasoning.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_idstringrequiredTop-level run of the batch. Events that set their own
run_idkeep it.
Bad Request