> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whitecircle.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Events API
> 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.
Events are available in API version 2026-06-01. Send whitecircle-version: 2026-06-01 on every Events request.
## How It Works
1. You send one Event with `POST /api/event` or up to 50 Events with `POST /api/events`
2. Conditions match that Event's metadata and select the applicable Policies and Metrics
3. Event selectors filter those Policies and Metrics to the submitted type and field
4. 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
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.
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.
| 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](/latest/events/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.
```json theme={null}
{
"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](/latest/condition/overview) 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 `-`.