Events API

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.

Events are available in API version 2026-06-01. Send whitecircle-version: 2026-06-01 on every Events request.

How It Works

You send one Event with POST /api/event or up to 50 Events with POST /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_id for each completed result

Both endpoints check the same way. POST /api/event returns the verdict at the top level for the one Event you sent, so there is nothing to match up. POST /api/events returns results grouped into typed buckets, which you index by event_id.

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

Check One Event

Submit one message, tool call, agent update, reasoning text, or artifact Event.

Check Multiple Events

Submit several Events in one request and receive typed result buckets.

Get a Run Graph

Load durable parent and causal-link relationships for a run.

Event Context

Understand how previous Events inform the check of the current Event.

Conditions

Learn how Conditions select Policies and Metrics for each Event.

Artifact Events

Check inline image artifacts alongside other Events.

Standalone Artifacts

Submit standalone image artifacts with the artifact API endpoint.

Event Types

Each Event has a type and at most one content field to check.

Event type	Fields you can check	Use for
`message`	`content`	User or assistant messages
`artifact`	`content`	Inline image Artifacts
`tool`	`arguments`, `output`, `definition`	Tool calls and tool results
`function`	`arguments`, `output`, `definition`	Function calls and function results
`agent`	`input`, `instructions`, `output`, `state`	Agent tasks, instructions, results, and state
`reasoning`	`content`	Reasoning text you choose to submit

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:

Field	Description
`run_id`	Your ID for a group of related Events. Generated if omitted for Events with content.
`event_id`	Your ID for one Event. Generated if omitted for Events with content and required for references.
`internal_event_id`	White Circle’s ID for one saved result, returned after a check completes or a reference resolves.

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.

Store internal_event_id when you need to retrieve or refer to a specific result.

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.

Status	Meaning
`referenced`	The reference resolved to an existing Event.
`not_found`	The reference did not resolve, or the latest matching Event had a different type.

Roles and Policy Targeting

Message Events require a role when they include content. Use:

Role	Use for
`user`	User-created content and inputs
`assistant`	Assistant-created content and outputs

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.

{
  "type": "tool",
  "event_id": "evt_tool_output_001",
  "name": "lookup_order",
  "output": { "refund_eligible": true },
  "metadata": {
    "user": { "region": "eu" },
    "workflow": { "stage": "refund_review" }
  }
}

If no active Condition matches an Event, no Policies are evaluated for that Event. Conditions are evaluated independently for every Event in a batch.

Policy results include enabled_by_conditions when one or more matching Conditions select the Policy. See Conditions for expression syntax and attachment behavior.

Limits

Limit	Value
Batch size	50 Events
Links per Event	50
Parent and link declarations per batch	500
Request body	32 MiB
Inline content size	256 KiB per Event content field
Metadata size	256 KiB per Event
`run_id` and `event_id` length	128 characters
`external_session_id`, `name`, `call_id`, `format`, and `external_artifact_id` length	256 characters

Event IDs may contain letters, numbers, ., _, :, and -.

First Steps

Use Cases

Integrations

Events

Conditions

Artifacts

Policy

Metric

User

How It Works

When to Use Events

Check One Event

Check Multiple Events

Get a Run Graph

Event Context

Conditions

Artifact Events

Standalone Artifacts

Event Types

Event Identity and Retries

Reference Behavior

Roles and Policy Targeting

Conditions and Event Metadata

Limits

​How It Works

​When to Use Events

Check One Event

Check Multiple Events

Get a Run Graph

Event Context

Conditions

Artifact Events

Standalone Artifacts

​Event Types

​Event Identity and Retries

​Reference Behavior

​Roles and Policy Targeting

​Conditions and Event Metadata

​Limits

How It Works

When to Use Events

Event Types

Event Identity and Retries

Reference Behavior

Roles and Policy Targeting

Conditions and Event Metadata

Limits