# Check Multiple Events

`POST /api/events`

Base URLs: `https://eu.whitecircle.com`, `https://us.whitecircle.com`

OpenAPI: [latest/openapi.json](https://whitecircle.com/docs/latest/openapi.json)

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

> [!NOTE]
> Batch requests preserve result order within each typed bucket, but results are grouped by type: `messages`, `artifacts`, `tools`, `functions`, `agents`, and `reasoning`.

> [!TIP]
> List Events in the order they happened. Each Event is checked against the Events listed before it. See [Event Context](https://whitecircle.com/docs/latest/events/context.md).

Each Event payload uses the same shape as [Check One Event](https://whitecircle.com/docs/latest/events/check-event.md).

## 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
{
  "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" } }
    }
  ]
}
```

> [!WARNING]
> 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](https://whitecircle.com/docs/latest/condition/overview.md) for routing behavior.

## Response Overview

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.

> [!NOTE]
> 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](https://whitecircle.com/docs/latest/events/check-event.md).

Send `include_shadow=true` at the top level to also return [shadow-mode Policies](https://whitecircle.com/docs/latest/first-steps/policies.md) for every Event in the batch, each marked `shadow: true`. Shadow results never change any top-level `flagged` verdict.

## 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
{
  "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`.

> [!TIP]
> 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.

## Authorizations

- `Authorization` (`string`, header, required): API Key required. Format: Bearer wc-your-api-key.

## Headers

- `whitecircle-version` (`string`, required): API Version. Example: `"2026-06-01"`.

## Body

`application/json`

- `environment_id` (`string`, required): Environment whose Conditions, Policies, and Metrics apply. Required on every request.
- `events` (`object[]`, required): 1 to 50 Events. List them in the order they happened: each Event is checked against the Events listed before it. Required array length: `1 - 50` elements.
- `events.type` (`enum<string>`, required): Kind of Event. Determines which content fields are allowed and which Policies can apply. Available options: `message`, `artifact`, `tool`, `function`, `agent`, `reasoning`.
- `events.role` (`string | null`, optional): Who produced the content: `user`, `assistant`, `system`, `developer`, or `tool`. Required for `message` Events with content unless the request sets a top-level `role`. Overrides the Policy direction of other Event types; when omitted, White Circle picks it from the type and field, for example `tool.output` as `assistant`.
- `events.content` (`any`, optional): Content to check for `message`, `artifact`, and `reasoning` Events. Messages and reasoning take text; artifacts take an image object.
- `events.delta` (`any`, optional): An incremental chunk of a streamed `message` or `reasoning` Event. Each delta is checked as its own Event; White Circle does not join deltas, so send chunks large enough to judge, such as every N tokens or sentences.
- `events.arguments` (`any`, optional): Arguments of a `tool` or `function` call. Accepts any JSON value; White Circle keeps its shape.
- `events.output` (`any`, optional): Result of a `tool`, `function`, or `agent`. Accepts any JSON value.
- `events.definition` (`any`, optional): Schema or description of a `tool` or `function`, such as an OpenAI tool definition. Accepts any JSON value.
- `events.input` (`any`, optional): Task or input given to an `agent`, checked as user-direction content.
- `events.instructions` (`any`, optional): System instructions given to an `agent`. Enters context with the `system` role.
- `events.state` (`any`, optional): Snapshot of an `agent`'s internal state.
- `events.event_id` (`string | null`, optional): Your ID for this Event. Required for reference-only Events. Generated when omitted for Events with content. Not a retry key: sending the same `run_id` and `event_id` again runs a new check. Up to 128 characters: letters, numbers, `.`, `_`, `:`, and `-`.
- `events.run_id` (`string | null`, optional): Run for this Event. Overrides the top-level `run_id`. Up to 128 characters: letters, numbers, `.`, `_`, `:`, and `-`.
- `events.external_session_id` (`string | null`, optional): Session for this Event. Overrides the top-level `external_session_id`. Up to 256 characters.
- `events.parent_event_id` (`string | null`, optional): `event_id` of this Event's structural parent in the same run, such as the agent step that produced it. Appears as a `parent` edge in the run graph and pairs a tool or function `output` with the call that has this `event_id` when you send no `call_id`. Not allowed on reference-only Events. Up to 128 characters: letters, numbers, `.`, `_`, `:`, and `-`.
- `events.links` (`object[]`, optional): Causal inputs this Event consumed, in this run or in other runs of the same Environment. Each appears as a `link` edge in the run graph. Up to 50 per Event. Not allowed on reference-only Events.
- `events.links.event_id` (`string`, required): `event_id` of the linked Event. The target does not have to exist yet.
- `events.links.run_id` (`string | null`, optional): Run of the linked Event. Omit for an Event in the same run. Links can point to any run in the same Environment.
- `events.external_artifact_id` (`string | null`, optional): Your ID for the image in an `artifact` Event. Used as the `event_id` when you omit `event_id`. Up to 256 characters.
- `events.name` (`string | null`, optional): Name of the tool, function, agent, or artifact, such as `lookup_order`. Up to 256 characters.
- `events.call_id` (`string | null`, optional): Your ID for one tool or function invocation. Send the same `call_id` on the `arguments` and `output` Events so the model sees them as one call. Up to 256 characters.
- `events.stream_id` (`string | null`, optional): Your ID for the stream a `delta` belongs to. Stored and returned in the run graph; does not change how deltas are checked. Up to 256 characters.
- `events.sequence` (`integer<int64> | null`, optional): Position of this chunk in its stream. Stored and returned in the run graph.
- `events.format` (`string | null`, optional): Free-form label for the content format, such as `markdown`. Stored only. Up to 256 characters.
- `events.started_at` (`string<date-time> | null`, optional): When the work behind this Event started in your system, as RFC 3339. Shown on the Event with `finished_at` as its duration. Display only: it does not change Event ordering or `created_at`.
- `events.finished_at` (`string<date-time> | null`, optional): When the work behind this Event finished in your system, as RFC 3339. Must not be earlier than `started_at`. Display only: it does not change Event ordering or `created_at`.
- `events.metadata` (`any`, optional): Custom JSON object, up to 256 KiB. Conditions match against it to select Policies and Metrics for this Event.
- `run_id` (`string | null`, optional): Your ID for a group of related Events, such as one agent run. Defaults to `external_session_id` when omitted. `parent_event_id` and same-run `links` resolve inside this run. Up to 128 characters: letters, numbers, `.`, `_`, `:`, and `-`. Applies to every Event that does not set its own.
- `external_session_id` (`string | null`, optional): Your conversation or session ID. Reuse it for every Event in the same conversation. See [Event Context](https://whitecircle.com/docs/latest/events/context.md). Up to 256 characters. Applies to every Event that does not set its own.
- `role` (`string | null`, optional): Default role for `message` and `artifact` Events that do not set their own `role`. Other Event types ignore it.
- `include_shadow` (`boolean | null`, optional): Also return shadow-policy results (each marked `shadow: true`). Shadow results never affect the top-level `flagged`/`violation` verdict.

## Request example

```bash
curl --request POST \
  --url 'https://eu.whitecircle.com/api/events' \
  --header "Authorization: Bearer $WHITECIRCLE_API_KEY" \
  --header 'whitecircle-version: 2026-06-01' \
  --header 'Content-Type: application/json' \
  --data '{
  "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 4815?",
      "event_id": "evt_user_001"
    },
    {
      "type": "tool",
      "name": "lookup_order",
      "output": {
        "order_id": "4815",
        "refund_eligible": true
      },
      "event_id": "evt_tool_001",
      "call_id": "call_abc"
    }
  ]
}'
```

## Response

### 200

Success

`application/json`

- `flagged` (`boolean`, required): `true` if any Event in the batch violated at least one Policy.
- `messages` (`object[]`, required): Results for `message` Events, in request order.
- `messages.type` (`enum<string>`, required): Kind of Event that was submitted. Available options: `message`, `artifact`, `tool`, `function`, `agent`, `reasoning`.
- `messages.status` (`enum<string>`, required): Outcome for this Event. Available options: `completed`, `failed`, `referenced`, `not_found`.
- `messages.event_id` (`string`, required): Your `event_id`, or the generated one when you omitted it.
- `messages.flagged` (`boolean | null`, optional): `true` if this Event violated at least one Policy. Absent when no check ran.
- `messages.policies` (`object | null`, optional): Policy results keyed by Policy ID. Present only when `status` is `completed`. Contains only the Policies that Conditions selected for this Event.
- `messages.policies.{key}` (`object`, optional)
- `messages.policies.{key}.flagged` (`boolean`, required): Whether this Event violated the Policy.
- `messages.policies.{key}.name` (`string`, required): Human-readable Policy name.
- `messages.policies.{key}.enabled_by_conditions` (`object[] | null`, optional): The Conditions that selected this Policy for this Event, which is why it was evaluated at all.
- `messages.policies.{key}.enabled_by_conditions.id` (`string`, required)
- `messages.policies.{key}.enabled_by_conditions.name` (`string`, required)
- `messages.policies.{key}.shadow` (`boolean`, optional): Present and `true` only for shadow policies surfaced via `include_shadow`. A shadow result never affects the top-level verdict.
- `messages.note` (`string | null`, optional): Why no verdict was produced: no Condition selected a Policy or Metric, a reference did not resolve, or the Event failed validation or checking.
- `messages.internal_event_id` (`string | null`, optional): White Circle's ID for this saved result. Use it with `GET /api/event/{internal_event_id}`. Each check gets a new value, even when `run_id` and `event_id` repeat.
- `artifacts` (`object[]`, required): Results for `artifact` Events, in request order.
- `artifacts.type` (`enum<string>`, required): Kind of Event that was submitted. Available options: `message`, `artifact`, `tool`, `function`, `agent`, `reasoning`.
- `artifacts.status` (`enum<string>`, required): Outcome for this Event. Available options: `completed`, `failed`, `referenced`, `not_found`.
- `artifacts.event_id` (`string`, required): Your `event_id`, or the generated one when you omitted it.
- `artifacts.flagged` (`boolean | null`, optional): `true` if this Event violated at least one Policy. Absent when no check ran.
- `artifacts.policies` (`object | null`, optional): Policy results keyed by Policy ID. Present only when `status` is `completed`. Contains only the Policies that Conditions selected for this Event.
- `artifacts.policies.{key}` (`object`, optional)
- `artifacts.policies.{key}.flagged` (`boolean`, required): Whether this Event violated the Policy.
- `artifacts.policies.{key}.name` (`string`, required): Human-readable Policy name.
- `artifacts.policies.{key}.enabled_by_conditions` (`object[] | null`, optional): The Conditions that selected this Policy for this Event, which is why it was evaluated at all.
- `artifacts.policies.{key}.enabled_by_conditions.id` (`string`, required)
- `artifacts.policies.{key}.enabled_by_conditions.name` (`string`, required)
- `artifacts.policies.{key}.shadow` (`boolean`, optional): Present and `true` only for shadow policies surfaced via `include_shadow`. A shadow result never affects the top-level verdict.
- `artifacts.note` (`string | null`, optional): Why no verdict was produced: no Condition selected a Policy or Metric, a reference did not resolve, or the Event failed validation or checking.
- `artifacts.internal_event_id` (`string | null`, optional): White Circle's ID for this saved result. Use it with `GET /api/event/{internal_event_id}`. Each check gets a new value, even when `run_id` and `event_id` repeat.
- `tools` (`object[]`, required): Results for `tool` Events, in request order.
- `tools.type` (`enum<string>`, required): Kind of Event that was submitted. Available options: `message`, `artifact`, `tool`, `function`, `agent`, `reasoning`.
- `tools.status` (`enum<string>`, required): Outcome for this Event. Available options: `completed`, `failed`, `referenced`, `not_found`.
- `tools.event_id` (`string`, required): Your `event_id`, or the generated one when you omitted it.
- `tools.flagged` (`boolean | null`, optional): `true` if this Event violated at least one Policy. Absent when no check ran.
- `tools.policies` (`object | null`, optional): Policy results keyed by Policy ID. Present only when `status` is `completed`. Contains only the Policies that Conditions selected for this Event.
- `tools.policies.{key}` (`object`, optional)
- `tools.policies.{key}.flagged` (`boolean`, required): Whether this Event violated the Policy.
- `tools.policies.{key}.name` (`string`, required): Human-readable Policy name.
- `tools.policies.{key}.enabled_by_conditions` (`object[] | null`, optional): The Conditions that selected this Policy for this Event, which is why it was evaluated at all.
- `tools.policies.{key}.enabled_by_conditions.id` (`string`, required)
- `tools.policies.{key}.enabled_by_conditions.name` (`string`, required)
- `tools.policies.{key}.shadow` (`boolean`, optional): Present and `true` only for shadow policies surfaced via `include_shadow`. A shadow result never affects the top-level verdict.
- `tools.note` (`string | null`, optional): Why no verdict was produced: no Condition selected a Policy or Metric, a reference did not resolve, or the Event failed validation or checking.
- `tools.internal_event_id` (`string | null`, optional): White Circle's ID for this saved result. Use it with `GET /api/event/{internal_event_id}`. Each check gets a new value, even when `run_id` and `event_id` repeat.
- `functions` (`object[]`, required): Results for `function` Events, in request order.
- `functions.type` (`enum<string>`, required): Kind of Event that was submitted. Available options: `message`, `artifact`, `tool`, `function`, `agent`, `reasoning`.
- `functions.status` (`enum<string>`, required): Outcome for this Event. Available options: `completed`, `failed`, `referenced`, `not_found`.
- `functions.event_id` (`string`, required): Your `event_id`, or the generated one when you omitted it.
- `functions.flagged` (`boolean | null`, optional): `true` if this Event violated at least one Policy. Absent when no check ran.
- `functions.policies` (`object | null`, optional): Policy results keyed by Policy ID. Present only when `status` is `completed`. Contains only the Policies that Conditions selected for this Event.
- `functions.policies.{key}` (`object`, optional)
- `functions.policies.{key}.flagged` (`boolean`, required): Whether this Event violated the Policy.
- `functions.policies.{key}.name` (`string`, required): Human-readable Policy name.
- `functions.policies.{key}.enabled_by_conditions` (`object[] | null`, optional): The Conditions that selected this Policy for this Event, which is why it was evaluated at all.
- `functions.policies.{key}.enabled_by_conditions.id` (`string`, required)
- `functions.policies.{key}.enabled_by_conditions.name` (`string`, required)
- `functions.policies.{key}.shadow` (`boolean`, optional): Present and `true` only for shadow policies surfaced via `include_shadow`. A shadow result never affects the top-level verdict.
- `functions.note` (`string | null`, optional): Why no verdict was produced: no Condition selected a Policy or Metric, a reference did not resolve, or the Event failed validation or checking.
- `functions.internal_event_id` (`string | null`, optional): White Circle's ID for this saved result. Use it with `GET /api/event/{internal_event_id}`. Each check gets a new value, even when `run_id` and `event_id` repeat.
- `agents` (`object[]`, required): Results for `agent` Events, in request order.
- `agents.type` (`enum<string>`, required): Kind of Event that was submitted. Available options: `message`, `artifact`, `tool`, `function`, `agent`, `reasoning`.
- `agents.status` (`enum<string>`, required): Outcome for this Event. Available options: `completed`, `failed`, `referenced`, `not_found`.
- `agents.event_id` (`string`, required): Your `event_id`, or the generated one when you omitted it.
- `agents.flagged` (`boolean | null`, optional): `true` if this Event violated at least one Policy. Absent when no check ran.
- `agents.policies` (`object | null`, optional): Policy results keyed by Policy ID. Present only when `status` is `completed`. Contains only the Policies that Conditions selected for this Event.
- `agents.policies.{key}` (`object`, optional)
- `agents.policies.{key}.flagged` (`boolean`, required): Whether this Event violated the Policy.
- `agents.policies.{key}.name` (`string`, required): Human-readable Policy name.
- `agents.policies.{key}.enabled_by_conditions` (`object[] | null`, optional): The Conditions that selected this Policy for this Event, which is why it was evaluated at all.
- `agents.policies.{key}.enabled_by_conditions.id` (`string`, required)
- `agents.policies.{key}.enabled_by_conditions.name` (`string`, required)
- `agents.policies.{key}.shadow` (`boolean`, optional): Present and `true` only for shadow policies surfaced via `include_shadow`. A shadow result never affects the top-level verdict.
- `agents.note` (`string | null`, optional): Why no verdict was produced: no Condition selected a Policy or Metric, a reference did not resolve, or the Event failed validation or checking.
- `agents.internal_event_id` (`string | null`, optional): White Circle's ID for this saved result. Use it with `GET /api/event/{internal_event_id}`. Each check gets a new value, even when `run_id` and `event_id` repeat.
- `reasoning` (`object[]`, required): Results for `reasoning` Events, in request order.
- `reasoning.type` (`enum<string>`, required): Kind of Event that was submitted. Available options: `message`, `artifact`, `tool`, `function`, `agent`, `reasoning`.
- `reasoning.status` (`enum<string>`, required): Outcome for this Event. Available options: `completed`, `failed`, `referenced`, `not_found`.
- `reasoning.event_id` (`string`, required): Your `event_id`, or the generated one when you omitted it.
- `reasoning.flagged` (`boolean | null`, optional): `true` if this Event violated at least one Policy. Absent when no check ran.
- `reasoning.policies` (`object | null`, optional): Policy results keyed by Policy ID. Present only when `status` is `completed`. Contains only the Policies that Conditions selected for this Event.
- `reasoning.policies.{key}` (`object`, optional)
- `reasoning.policies.{key}.flagged` (`boolean`, required): Whether this Event violated the Policy.
- `reasoning.policies.{key}.name` (`string`, required): Human-readable Policy name.
- `reasoning.policies.{key}.enabled_by_conditions` (`object[] | null`, optional): The Conditions that selected this Policy for this Event, which is why it was evaluated at all.
- `reasoning.policies.{key}.enabled_by_conditions.id` (`string`, required)
- `reasoning.policies.{key}.enabled_by_conditions.name` (`string`, required)
- `reasoning.policies.{key}.shadow` (`boolean`, optional): Present and `true` only for shadow policies surfaced via `include_shadow`. A shadow result never affects the top-level verdict.
- `reasoning.note` (`string | null`, optional): Why no verdict was produced: no Condition selected a Policy or Metric, a reference did not resolve, or the Event failed validation or checking.
- `reasoning.internal_event_id` (`string | null`, optional): White Circle's ID for this saved result. Use it with `GET /api/event/{internal_event_id}`. Each check gets a new value, even when `run_id` and `event_id` repeat.
- `run_id` (`string`, required): Top-level run of the batch. Events that set their own `run_id` keep it.

**Example**

```json
{
  "flagged": false,
  "messages": [
    {
      "type": "message",
      "status": "completed",
      "flagged": false,
      "policies": {
        "01930000-0000-7000-8000-000000000001": {
          "flagged": false,
          "name": "PII disclosure",
          "enabled_by_conditions": [
            {
              "id": "01930000-0000-7000-8000-000000000002",
              "name": "EU users"
            }
          ]
        }
      },
      "event_id": "evt_user_001",
      "internal_event_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890"
    }
  ],
  "artifacts": [],
  "tools": [
    {
      "type": "tool",
      "status": "completed",
      "flagged": false,
      "policies": {},
      "note": "No policies or metrics were selected for this Event",
      "event_id": "evt_tool_001",
      "internal_event_id": "b2c3d4e5-f6a7-4901-bcde-f23456789012"
    }
  ],
  "functions": [],
  "agents": [],
  "reasoning": [],
  "run_id": "run_refund_123"
}
```

### 400

Bad Request
