> ## 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.
# Check Multiple Events
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
1. You submit an `events` array containing 1 to 50 Event payloads
2. Conditions select the applicable Policies and Metrics for each Event
3. White Circle evaluates Policies synchronously and queues Metrics asynchronously
4. You receive one response with Policy results grouped by Event type
Batch requests preserve result order within each typed bucket, but results are grouped by type: `messages`, `artifacts`, `tools`, `functions`, `agents`, and `reasoning`.
List Events in the order they happened. Each Event is checked against the Events listed before it. See [Event Context](/latest/events/context).
## Example Request
```bash theme={null}
curl -X POST "https://eu.whitecircle.com/api/events" \
-H "Authorization: Bearer wc-your-api-key" \
-H "Content-Type: application/json" \
-H "whitecircle-version: 2026-06-01" \
-d '{
"environment_id": "environment_123",
"run_id": "run_refund_123",
"external_session_id": "conversation_456",
"events": [
{
"type": "message",
"role": "user",
"content": "Can you refund my order?",
"event_id": "evt_user_001"
},
{
"type": "tool",
"name": "lookup_order",
"output": {
"order_id": "ord_123",
"refund_eligible": true
},
"event_id": "evt_tool_output_001"
},
{
"type": "message",
"role": "assistant",
"content": "Your order is eligible for a refund.",
"event_id": "evt_assistant_001"
}
]
}'
```
## Request Overview
| Field | Type | Required | Description |
| --------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `environment_id` | string | ✓ | Environment to use. Required for every request. |
| `run_id` | string | | Your ID for this group of Events. Reusing it supplies [context](/latest/events/context) when no `external_session_id` is sent. Generated if omitted. Each Event can override it. |
| `external_session_id` | string | | Your conversation or session tracking ID. Reusing it checks these Events against the previous Events of that conversation. See [Event Context](/latest/events/context). Each Event can override it. |
| `role` | string | | Role applied to `message` and `artifact` Events that do not set their own. |
| `events` | array | ✓ | Between 1 and 50 Event payloads. Empty arrays are rejected. |
Each Event payload uses the same shape as [Check One Event](/latest/events/check-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 theme={null}
{
"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" } }
}
]
}
```
If no active Condition matches an Event, no Policies are evaluated and no Metrics are queued for that Event, even if another Event in the batch matched a Condition.
Selected Metrics run asynchronously and are not included in the synchronous typed result buckets.
See [Conditions](/latest/condition/overview) for routing behavior.
## Response Overview
| Field | Description |
| ----------- | ------------------------------------------------- |
| `flagged` | `true` if any completed Event result was flagged. |
| `messages` | Results for `message` Events. |
| `artifacts` | Results for `artifact` Events. |
| `tools` | Results for `tool` Events. |
| `functions` | Results for `function` Events. |
| `agents` | Results for `agent` Events. |
| `reasoning` | Results for `reasoning` Events. |
| `run_id` | Group ID used for the batch. |
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.
A batch reports each verdict on its own result, because one request checks many Events. The single-Event response instead reports the verdict once at the top level. See [Check One Event](/latest/events/check-event).
## 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 theme={null}
{
"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:
| Status | Meaning |
| ------------ | ---------------------------------------------------------------------------- |
| `referenced` | A matching result exists and has the same Event type. |
| `not_found` | No matching Event exists, or the latest matching Event has a different type. |
## 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`.
Use different `event_id` values when each Event should have its own application 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.
## OpenAPI
````yaml POST /api/events
openapi: 3.1.0
info:
title: WhiteCircle API Backend
description: 'Authentication: Bearer API Key Required'
license:
name: ''
version: '2026-06-01'
servers:
- url: https://eu.whitecircle.com
- url: https://us.whitecircle.com
security: []
tags:
- name: Session
description: Session-based content checking and moderation
- name: User
description: User risk assessment and scoring
- name: Policy
description: Policy management CRUD
- name: Metric
description: Metric management CRUD
- name: Artifact
description: Standalone artifact moderation
- name: Events
description: Append-only event ingestion and public event lookup
- name: Condition
description: Metadata-driven policy routing
paths:
/api/events:
post:
tags:
- Events
operationId: events_check_v1
parameters:
- name: whitecircle-version
in: header
description: API Version
required: true
schema:
type: string
example: '2026-06-01'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EventsRequestEnvelope'
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/EventsResponseEnvelope'
'400':
description: Bad Request
security:
- bearerAuth: []
components:
schemas:
EventsRequestEnvelope:
type: object
required:
- environment_id
- events
properties:
environment_id:
type: string
run_id:
type:
- string
- 'null'
external_session_id:
type:
- string
- 'null'
role:
type:
- string
- 'null'
events:
type: array
items:
$ref: '#/components/schemas/EventPayload'
maxItems: 50
minItems: 1
EventsResponseEnvelope:
type: object
required:
- flagged
- messages
- artifacts
- tools
- functions
- agents
- reasoning
- run_id
properties:
flagged:
type: boolean
messages:
type: array
items:
$ref: '#/components/schemas/EventResult'
artifacts:
type: array
items:
$ref: '#/components/schemas/EventResult'
tools:
type: array
items:
$ref: '#/components/schemas/EventResult'
functions:
type: array
items:
$ref: '#/components/schemas/EventResult'
agents:
type: array
items:
$ref: '#/components/schemas/EventResult'
reasoning:
type: array
items:
$ref: '#/components/schemas/EventResult'
run_id:
type: string
example:
flagged: false
agents: []
artifacts: []
functions: []
messages:
- event_id: evt_user_001
flagged: false
internal_event_id: 11111111-1111-4111-8111-111111111111
policies: {}
status: completed
type: message
reasoning: []
run_id: run_refund_123
tools:
- event_id: evt_tool_output_001
flagged: false
internal_event_id: 22222222-2222-4222-8222-222222222222
policies: {}
status: completed
type: tool
EventPayload:
type: object
required:
- type
properties:
type:
$ref: '#/components/schemas/EventType'
role:
type:
- string
- 'null'
content: {}
delta: {}
arguments: {}
output: {}
definition: {}
input: {}
instructions: {}
state: {}
event_id:
type:
- string
- 'null'
run_id:
type:
- string
- 'null'
external_session_id:
type:
- string
- 'null'
parent_event_id:
type:
- string
- 'null'
links:
type: array
items:
$ref: '#/components/schemas/EventLink'
external_artifact_id:
type:
- string
- 'null'
name:
type:
- string
- 'null'
call_id:
type:
- string
- 'null'
stream_id:
type:
- string
- 'null'
sequence:
type:
- integer
- 'null'
format: int64
format:
type:
- string
- 'null'
timestamp:
type:
- string
- 'null'
format: date-time
metadata: {}
EventResult:
type: object
required:
- type
- status
- event_id
properties:
type:
$ref: '#/components/schemas/EventType'
status:
$ref: '#/components/schemas/EventResultStatus'
flagged:
type:
- boolean
- 'null'
policies:
type:
- object
- 'null'
additionalProperties:
$ref: '#/components/schemas/EventPolicyResult'
propertyNames:
type: string
note:
type:
- string
- 'null'
event_id:
type: string
internal_event_id:
type:
- string
- 'null'
EventType:
type: string
enum:
- message
- artifact
- tool
- function
- agent
- reasoning
EventLink:
type: object
required:
- event_id
properties:
run_id:
type:
- string
- 'null'
event_id:
type: string
EventResultStatus:
type: string
enum:
- completed
- failed
- referenced
- not_found
EventPolicyResult:
type: object
required:
- flagged
- name
properties:
flagged:
type: boolean
name:
type: string
enabled_by_conditions:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/EnabledByCondition'
description: >-
The Conditions that selected this Policy for this Event, which is
why it
was evaluated at all.
EnabledByCondition:
type: object
required:
- id
- name
properties:
id:
type: string
name:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: 'API Key required. Format: Bearer wc-your-api-key'
````