Check messages, tool calls, agent state, reasoning text, and inline image artifacts
The Events API lets you check individual pieces of an AI interaction instead of sending one combined message history. Use Events when you want Policy results for a specific message, tool output, function call, agent update, reasoning text, or inline image artifact.
How It Works
- You send one Event with
POST /api/eventor up to 50 Events withPOST /api/events - Conditions match that Event’s metadata and select the applicable Policies and Metrics
- Event selectors filter those Policies and Metrics to the submitted type and field
- White Circle evaluates the Event against the Events that came before it and returns an
internal_event_idfor each completed result
When to Use Events
Use Events for:
- Checking user and assistant messages separately
- Checking tool or function arguments, definitions, and outputs
- Checking agent input, instructions, output, or state
- Checking reasoning text you choose to submit
- Checking inline image Artifacts alongside messages or tool calls
- Referencing an Event created earlier in the same batch or already stored by White Circle
- Recording one structural parent plus causal links for agent fan-in and cross-run provenance
Submit one message, tool call, agent update, reasoning text, or artifact Event.
Submit several Events in one request and receive typed result buckets.
Load durable parent and causal-link relationships for a run.
Understand how previous Events inform the check of the current Event.
Model sessions, runs, sub-agents, parents, and links.
Learn how Conditions select Policies and Metrics for each Event.
Check inline image artifacts alongside other Events.
Submit standalone image artifacts with the artifact API endpoint.
Event Types
Each Event has a type and at most one content field to check.
If an Event has no content field, White Circle treats it as a reference to an existing Event. Reference-only Events must include event_id.
Event Identity and Retries
Events use two kinds of identifiers:
run_id and event_id help you connect Events to your own application data. They are not retry keys. Every Event you submit with content is checked and saved on its own, so sending the same run_id and event_id twice produces two results with different internal_event_id values. Retrying a failed request therefore checks the content again rather than returning the first result.
Reusing run_id also groups Events into one conversation for context when you send no external_session_id.
Reference Behavior
Reference-only Events resolve by run_id + event_id. White Circle returns the latest matching result when it has the same Event type.
Roles and Policy Targeting
Message Events require a role when they include content. Use:
For non-message Events, White Circle filters Policies and Metrics based on the Event type and field. For example, tool.output can target tool-output Policies, while agent.state can target agent-state Policies.
Conditions and Event Metadata
Conditions determine which Policies are candidates for each Event. White Circle evaluates Conditions against the metadata object on that Event, then applies Event type, field, and direction selectors to the selected Policies.
JSON
{
"type": "tool",
"event_id": "evt_tool_output_001",
"name": "lookup_order",
"output": { "refund_eligible": true },
"metadata": {
"user": { "region": "eu" },
"workflow": { "stage": "refund_review" }
}
}Policy results include enabled_by_conditions when one or more matching Conditions select the Policy. See Conditions for expression syntax and attachment behavior.
Execution Timing
Set started_at and finished_at to record when the work behind an Event ran in your system, such as a tool call or an agent step. Both are optional RFC 3339 timestamps. When you send both, White Circle shows the difference as the Event’s duration.
JSON
{
"type": "tool",
"event_id": "evt_tool_output_001",
"name": "lookup_order",
"output": { "refund_eligible": true },
"started_at": "2026-10-29T10:00:00Z",
"finished_at": "2026-10-29T10:00:02.350Z"
}White Circle returns 400 if finished_at is earlier than started_at, or if either value is not a valid timestamp. These fields are for display only: Event order and created_at are set by White Circle when it receives the Event.
Limits
Event IDs may contain letters, numbers, ., _, :, and -.