Events

Check Multiple Events

POST
/api/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

Each Event payload uses the same shape as Check One 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

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

Selected Metrics run asynchronously and are not included in the synchronous typed result buckets.

See Conditions 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.

Send include_shadow=true at the top level to also return shadow-mode Policies 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:

StatusMeaning
referencedA matching result exists and has the same Event type.
not_foundNo 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.

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

  • Authorizationstringheaderrequired

    API Key required. Format: Bearer wc-your-api-key

Headers

  • whitecircle-versionstringrequired

    API Version

    Example: "2026-06-01"

Body

application/json

  • environment_idstringrequired

    Environment whose Conditions, Policies, and Metrics apply. Required on every request.

  • eventsobject[]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

    Show child attributes
    • events.typeenum<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.rolestring | null

      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.contentany

      Content to check for message, artifact, and reasoning Events. Messages and reasoning take text; artifacts take an image object.

    • events.deltaany

      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.argumentsany

      Arguments of a tool or function call. Accepts any JSON value; White Circle keeps its shape.

    • events.outputany

      Result of a tool, function, or agent. Accepts any JSON value.

    • events.definitionany

      Schema or description of a tool or function, such as an OpenAI tool definition. Accepts any JSON value.

    • events.inputany

      Task or input given to an agent, checked as user-direction content.

    • events.instructionsany

      System instructions given to an agent. Enters context with the system role.

    • events.stateany

      Snapshot of an agent's internal state.

    • events.event_idstring | null

      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_idstring | null

      Run for this Event. Overrides the top-level run_id. Up to 128 characters: letters, numbers, ., _, :, and -.

    • events.external_session_idstring | null

      Session for this Event. Overrides the top-level external_session_id. Up to 256 characters.

    • events.parent_event_idstring | null

      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.external_artifact_idstring | null

      Your ID for the image in an artifact Event. Used as the event_id when you omit event_id. Up to 256 characters.

    • events.namestring | null

      Name of the tool, function, agent, or artifact, such as lookup_order. Up to 256 characters.

    • events.call_idstring | null

      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_idstring | null

      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.sequenceinteger<int64> | null

      Position of this chunk in its stream. Stored and returned in the run graph.

    • events.formatstring | null

      Free-form label for the content format, such as markdown. Stored only. Up to 256 characters.

    • events.started_atstring<date-time> | null

      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_atstring<date-time> | null

      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.metadataany

      Custom JSON object, up to 256 KiB. Conditions match against it to select Policies and Metrics for this Event.

  • run_idstring | null

    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_idstring | null

    Your conversation or session ID. Reuse it for every Event in the same conversation. See Event Context. Up to 256 characters. Applies to every Event that does not set its own.

  • rolestring | null

    Default role for message and artifact Events that do not set their own role. Other Event types ignore it.

  • include_shadowboolean | null

    Also return shadow-policy results (each marked shadow: true). Shadow results never affect the top-level flagged/violation verdict.

Response

application/json

Success

  • flaggedbooleanrequired

    true if any Event in the batch violated at least one Policy.

  • messagesobject[]required

    Results for message Events, in request order.

    Show child attributes
    • messages.typeenum<string>required

      Kind of Event that was submitted.

      Available options: message, artifact, tool, function, agent, reasoning

    • messages.statusenum<string>required

      Outcome for this Event.

      Available options: completed, failed, referenced, not_found

    • messages.event_idstringrequired

      Your event_id, or the generated one when you omitted it.

    • messages.flaggedboolean | null

      true if this Event violated at least one Policy. Absent when no check ran.

    • messages.policiesobject | null

      Policy results keyed by Policy ID. Present only when status is completed. Contains only the Policies that Conditions selected for this Event.

      Show child attributes
      • messages.policies.{key}object

        Show child attributes
        • messages.policies.{key}.flaggedbooleanrequired

          Whether this Event violated the Policy.

        • messages.policies.{key}.namestringrequired

          Human-readable Policy name.

        • messages.policies.{key}.enabled_by_conditionsobject[] | null

          The Conditions that selected this Policy for this Event, which is why it was evaluated at all.

          Show child attributes
          • messages.policies.{key}.enabled_by_conditions.idstringrequired

          • messages.policies.{key}.enabled_by_conditions.namestringrequired

        • messages.policies.{key}.shadowboolean

          Present and true only for shadow policies surfaced via include_shadow. A shadow result never affects the top-level verdict.

    • messages.notestring | null

      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_idstring | null

      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.

  • artifactsobject[]required

    Results for artifact Events, in request order.

    Show child attributes
    • artifacts.typeenum<string>required

      Kind of Event that was submitted.

      Available options: message, artifact, tool, function, agent, reasoning

    • artifacts.statusenum<string>required

      Outcome for this Event.

      Available options: completed, failed, referenced, not_found

    • artifacts.event_idstringrequired

      Your event_id, or the generated one when you omitted it.

    • artifacts.flaggedboolean | null

      true if this Event violated at least one Policy. Absent when no check ran.

    • artifacts.policiesobject | null

      Policy results keyed by Policy ID. Present only when status is completed. Contains only the Policies that Conditions selected for this Event.

      Show child attributes
      • artifacts.policies.{key}object

        Show child attributes
        • artifacts.policies.{key}.flaggedbooleanrequired

          Whether this Event violated the Policy.

        • artifacts.policies.{key}.namestringrequired

          Human-readable Policy name.

        • artifacts.policies.{key}.enabled_by_conditionsobject[] | null

          The Conditions that selected this Policy for this Event, which is why it was evaluated at all.

          Show child attributes
          • artifacts.policies.{key}.enabled_by_conditions.idstringrequired

          • artifacts.policies.{key}.enabled_by_conditions.namestringrequired

        • artifacts.policies.{key}.shadowboolean

          Present and true only for shadow policies surfaced via include_shadow. A shadow result never affects the top-level verdict.

    • artifacts.notestring | null

      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_idstring | null

      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.

  • toolsobject[]required

    Results for tool Events, in request order.

    Show child attributes
    • tools.typeenum<string>required

      Kind of Event that was submitted.

      Available options: message, artifact, tool, function, agent, reasoning

    • tools.statusenum<string>required

      Outcome for this Event.

      Available options: completed, failed, referenced, not_found

    • tools.event_idstringrequired

      Your event_id, or the generated one when you omitted it.

    • tools.flaggedboolean | null

      true if this Event violated at least one Policy. Absent when no check ran.

    • tools.policiesobject | null

      Policy results keyed by Policy ID. Present only when status is completed. Contains only the Policies that Conditions selected for this Event.

      Show child attributes
      • tools.policies.{key}object

        Show child attributes
        • tools.policies.{key}.flaggedbooleanrequired

          Whether this Event violated the Policy.

        • tools.policies.{key}.namestringrequired

          Human-readable Policy name.

        • tools.policies.{key}.enabled_by_conditionsobject[] | null

          The Conditions that selected this Policy for this Event, which is why it was evaluated at all.

          Show child attributes
          • tools.policies.{key}.enabled_by_conditions.idstringrequired

          • tools.policies.{key}.enabled_by_conditions.namestringrequired

        • tools.policies.{key}.shadowboolean

          Present and true only for shadow policies surfaced via include_shadow. A shadow result never affects the top-level verdict.

    • tools.notestring | null

      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_idstring | null

      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.

  • functionsobject[]required

    Results for function Events, in request order.

    Show child attributes
    • functions.typeenum<string>required

      Kind of Event that was submitted.

      Available options: message, artifact, tool, function, agent, reasoning

    • functions.statusenum<string>required

      Outcome for this Event.

      Available options: completed, failed, referenced, not_found

    • functions.event_idstringrequired

      Your event_id, or the generated one when you omitted it.

    • functions.flaggedboolean | null

      true if this Event violated at least one Policy. Absent when no check ran.

    • functions.policiesobject | null

      Policy results keyed by Policy ID. Present only when status is completed. Contains only the Policies that Conditions selected for this Event.

      Show child attributes
      • functions.policies.{key}object

        Show child attributes
        • functions.policies.{key}.flaggedbooleanrequired

          Whether this Event violated the Policy.

        • functions.policies.{key}.namestringrequired

          Human-readable Policy name.

        • functions.policies.{key}.enabled_by_conditionsobject[] | null

          The Conditions that selected this Policy for this Event, which is why it was evaluated at all.

          Show child attributes
          • functions.policies.{key}.enabled_by_conditions.idstringrequired

          • functions.policies.{key}.enabled_by_conditions.namestringrequired

        • functions.policies.{key}.shadowboolean

          Present and true only for shadow policies surfaced via include_shadow. A shadow result never affects the top-level verdict.

    • functions.notestring | null

      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_idstring | null

      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.

  • agentsobject[]required

    Results for agent Events, in request order.

    Show child attributes
    • agents.typeenum<string>required

      Kind of Event that was submitted.

      Available options: message, artifact, tool, function, agent, reasoning

    • agents.statusenum<string>required

      Outcome for this Event.

      Available options: completed, failed, referenced, not_found

    • agents.event_idstringrequired

      Your event_id, or the generated one when you omitted it.

    • agents.flaggedboolean | null

      true if this Event violated at least one Policy. Absent when no check ran.

    • agents.policiesobject | null

      Policy results keyed by Policy ID. Present only when status is completed. Contains only the Policies that Conditions selected for this Event.

      Show child attributes
      • agents.policies.{key}object

        Show child attributes
        • agents.policies.{key}.flaggedbooleanrequired

          Whether this Event violated the Policy.

        • agents.policies.{key}.namestringrequired

          Human-readable Policy name.

        • agents.policies.{key}.enabled_by_conditionsobject[] | null

          The Conditions that selected this Policy for this Event, which is why it was evaluated at all.

          Show child attributes
          • agents.policies.{key}.enabled_by_conditions.idstringrequired

          • agents.policies.{key}.enabled_by_conditions.namestringrequired

        • agents.policies.{key}.shadowboolean

          Present and true only for shadow policies surfaced via include_shadow. A shadow result never affects the top-level verdict.

    • agents.notestring | null

      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_idstring | null

      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.

  • reasoningobject[]required

    Results for reasoning Events, in request order.

    Show child attributes
    • reasoning.typeenum<string>required

      Kind of Event that was submitted.

      Available options: message, artifact, tool, function, agent, reasoning

    • reasoning.statusenum<string>required

      Outcome for this Event.

      Available options: completed, failed, referenced, not_found

    • reasoning.event_idstringrequired

      Your event_id, or the generated one when you omitted it.

    • reasoning.flaggedboolean | null

      true if this Event violated at least one Policy. Absent when no check ran.

    • reasoning.policiesobject | null

      Policy results keyed by Policy ID. Present only when status is completed. Contains only the Policies that Conditions selected for this Event.

      Show child attributes
      • reasoning.policies.{key}object

        Show child attributes
        • reasoning.policies.{key}.flaggedbooleanrequired

          Whether this Event violated the Policy.

        • reasoning.policies.{key}.namestringrequired

          Human-readable Policy name.

        • reasoning.policies.{key}.enabled_by_conditionsobject[] | null

          The Conditions that selected this Policy for this Event, which is why it was evaluated at all.

          Show child attributes
          • reasoning.policies.{key}.enabled_by_conditions.idstringrequired

          • reasoning.policies.{key}.enabled_by_conditions.namestringrequired

        • reasoning.policies.{key}.shadowboolean

          Present and true only for shadow policies surfaced via include_shadow. A shadow result never affects the top-level verdict.

    • reasoning.notestring | null

      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_idstring | null

      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_idstringrequired

    Top-level run of the batch. Events that set their own run_id keep it.