Events

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.

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

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.

Runs and the Event Graph

Model sessions, runs, sub-agents, parents, and links.

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 typeFields you can checkUse for
messagecontentUser or assistant messages
artifactcontentInline image Artifacts
toolarguments, output, definitionTool calls and tool results
functionarguments, output, definitionFunction calls and function results
agentinput, instructions, output, stateAgent tasks, instructions, results, and state
reasoningcontentReasoning 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:

FieldDescription
run_idYour ID for a group of related Events. Generated if omitted for Events with content.
event_idYour ID for one Event. Generated if omitted for Events with content and required for references.
internal_event_idWhite 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.

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.

StatusMeaning
referencedThe reference resolved to an existing Event.
not_foundThe 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:

RoleUse for
userUser-created content and inputs
assistantAssistant-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

{
  "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

LimitValue
Batch size50 Events
Links per Event50
Parent and link declarations per batch500
Request body32 MiB
Inline content size256 KiB per Event content field
Metadata size256 KiB per Event
run_id and event_id length128 characters
external_session_id, name, call_id, format, and external_artifact_id length256 characters

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