---
title: "Tail and Query the Audit Stream"
url: "https://docs.caracal.run/guides/audit-stream/"
markdown_url: "https://docs.caracal.run/markdown/guides/audit-stream.md"
description: "Filter audit events, inspect diagnostics, and explain a specific request ID."
page_type: "page"
concepts: []
requires: []
---

# Tail and Query the Audit Stream

Canonical URL: https://docs.caracal.run/guides/audit-stream/
Markdown URL: https://docs.caracal.run/markdown/guides/audit-stream.md
Description: Filter audit events, inspect diagnostics, and explain a specific request ID.
Page type: page
Concepts: none
Requires: none

---

Use audit when a request is denied, step-up is triggered, delegation behaves unexpectedly, or an operator needs evidence for a run.

## Web Console Workflow

1. Open `caracal web`.
2. Select **Audit**.
3. Filter by zone, decision, event type, or request ID.
4. Open the event detail to inspect metadata, determining policies, and diagnostics.
5. Open the decision trace from the event for a full request-level view.

## Automation workflow

```ts
import { AdminClient } from "@caracalai/admin";

const admin = new AdminClient({
  apiUrl: process.env.CARACAL_API_URL!,
  adminToken: process.env.CARACAL_ADMIN_TOKEN!,
});

const events = await admin.audit.list(process.env.CARACAL_ZONE_ID!, {
  decision: "deny",
  limit: 25,
});

const trace = await admin.audit.explain(process.env.CARACAL_ZONE_ID!, events[0].request_id!);
console.log(trace.final_decision, trace.denied);
```

## Useful filters

| Filter | Use it for |
| --- | --- |
| Request ID | Stitch together STS, Gateway, connector, and explain events. |
| Decision | Find denies, allows, or partial decisions. |
| Event type | Focus on policy, session, delegation, step-up, or admin changes. |
| Time window | Investigate a run, incident, or rollout. |

## What to capture in incidents

- request ID;
- zone ID;
- application ID;
- resource identifier;
- requested scopes;
- final decision;
- determining policies;
- diagnostics;
- session or delegation edge IDs when present.

Related page: [Audit and Request Traces](/concepts/audit-ledger/).