> ## Documentation Index
> Fetch the complete documentation index at: https://docs.averta.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Investigate runtime decisions emitted by SDK wrappers and custom integrations.

Events are the audit trail for Averta runtime decisions. Use them to confirm traffic is protected and to debug blocks, tool restrictions, tool-result failures, and output decisions.

## What an Event Means

Each event is one checkpoint decision.

A single model turn can produce several events:

```text theme={null}
request -> tool_call -> tool_result -> output
```

Not every turn produces every checkpoint. If the model does not call a tool, there will be no tool-call or tool-result event. If the model returns another tool call, output may not run yet because the turn is not final.

## Fields to Check First

| Field           | Why it matters                                                                               |
| --------------- | -------------------------------------------------------------------------------------------- |
| API key         | Confirms which app, agent, or environment sent the request.                                  |
| Policy          | Shows which policy produced the decision.                                                    |
| Provider        | Shows provider, operation, model, and streaming mode when available.                         |
| Checkpoint      | Shows which lifecycle stage made the decision.                                               |
| Decision        | Shows `allow`, `block`, `restrict_tools`, or `rewrite`. The UI may display `restrict tools`. |
| Request context | Lets you search by `conversationId`, `requestId`, or `traceId`.                              |
| Time            | Confirms whether the event came from the run you are debugging.                              |
| Tool details    | Shows blocked tools or checked tool identity when available.                                 |
| Reasons         | Explains why a decision happened when policy returns reason data.                            |

## Investigation Order

1. Filter to the time range around your test run.
2. Filter by API key prefix or environment.
3. Search for `conversationId`, `requestId`, or `traceId`.
4. Narrow by checkpoint if you know where the failure happened.
5. Inspect `block`, `restrict_tools`, and `rewrite` decisions first.

Starting from policy settings before you find the relevant event is usually wasted time. Find the event, then tune the policy.

## Decision Meanings

| Decision         | What happened                                                                       |
| ---------------- | ----------------------------------------------------------------------------------- |
| `allow`          | The checkpoint allowed execution to continue.                                       |
| `block`          | The checkpoint stopped execution at that stage.                                     |
| `restrict_tools` | The request continued, but one or more tools were removed before the provider call. |
| `rewrite`        | Output policy requested a safer final answer.                                       |

For `restrict_tools`, inspect blocked tool names and then review the attached [tool exposure policy](/dashboard/tool-exposure-policy).

## Empty Events Checklist

If you expected events and the table is empty:

* confirm your app uses a wrapped client or calls `POST /v1/decide`
* confirm `AVERTA_API_KEY` is set in the same process that calls the provider
* confirm the key is not revoked
* confirm the key has an attached policy
* confirm your app sends traffic to `https://api.averta.io` or the intended `AVERTA_BASE_URL`
* confirm you are looking at the right organization and time range
* add `onDecision` logging to prove the SDK is receiving decisions

## Correlate with SDK Logs

Add `onDecision` while debugging:

<CodeGroup>
  ```typescript TypeScript theme={null}
  client = wrapOpenAI(client, {
    onDecision(event) {
      console.log(event.checkpointType, event.decision.decision);
    },
    requestContext: {
      conversationId: "conversation_123",
      requestId: "request_456",
      traceId: "trace_789",
    },
  });
  ```

  ```python Python theme={null}
  client = wrap_openai(
      client,
      on_decision=lambda event: print(
          event["checkpoint_type"],
          event["decision"].decision,
      ),
      request_context={
          "conversation_id": "conversation_123",
          "request_id": "request_456",
          "trace_id": "trace_789",
      },
  )
  ```
</CodeGroup>

Then search Events for the same `conversationId`, `requestId`, or `traceId`.

## Common Investigations

| Symptom                      | What to inspect                                             |
| ---------------------------- | ----------------------------------------------------------- |
| No event appears             | API key, wrapper usage, base URL, organization, time range. |
| Request blocked              | Request checkpoint reason and attached policy threshold.    |
| Tool disappeared             | Request event `blockedTools` and tool exposure rules.       |
| Tool execution never starts  | Tool-call checkpoint decision.                              |
| Tool result blocked          | Tool output content as untrusted input.                     |
| Output blocked or rewritten  | Output checkpoint decision and rewrite category.            |
| Event is hard to map to logs | `requestContext` and API key naming.                        |

## Next Steps

<CardGroup cols={2}>
  <Card title="Checkpoints" icon="shield-check" href="/concepts/checkpoints">
    Understand the lifecycle stage behind each event.
  </Card>

  <Card title="API keys" icon="key" href="/dashboard/api-keys">
    Confirm which key and policy produced the event.
  </Card>
</CardGroup>