---
title: "Tail and Query the Audit Stream"
url: "https://docs.caracal.run/v1.0/guides/audit-stream/"
markdown_url: "https://docs.caracal.run/markdown/v1.0/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/v1.0/guides/audit-stream/
Markdown URL: https://docs.caracal.run/markdown/v1.0/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, Approval is required, Delegation behaves unexpectedly, or an operator needs evidence for a run.

## Prerequisites

* A zone and known time window or request ID.
* A trusted Admin client for automation; application credentials cannot read zone audit.
* Durable event-ID deduplication if exporting continuously.

## Web Console Workflow

1. Open the web console for your deployment.
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, adapter, and explain events.       |
| Decision    | Find denies, allows, or partial decisions.                       |
| Event type  | Focus on Policy, Session, Delegation, Approval, or admin changes. |
| Time window | Investigate a run, incident, or rollout.                         |

## Ship events to a SIEM

Poll `admin.audit.list` with a bounded time window and persist the last processed event identity. Caracal does not expose a supported external audit-stream subscription API; Redis topics are runtime internals, not an application integration contract. Use Admin API list/export surfaces and forward events after deduplication.

| Field                         | Type           | Meaning                                                                           |
| ----------------------------- | -------------- | --------------------------------------------------------------------------------- |
| `id`                          | string         | Unique event id; use as the dedup key.                                            |
| `zone_id`                     | string         | Zone the event belongs to.                                                        |
| `event_type`                  | string         | What happened: exchange, decision, replay\_detected, revocation, lifecycle events. |
| `request_id`                  | string | null | Correlates every event from one request across STS, Gateway, and adapters.        |
| `decision`                    | string | null | `allow`, `deny`, or `partial` for decision-bearing events.                        |
| `evaluation_status`           | string | null | How policy evaluation concluded.                                                  |
| `metadata_json`               | object | null | Event-specific attributes: session, resource, scopes, client identity.            |
| `occurred_at` / `ingested_at` | string         | Event time and audit-service ingest time (RFC 3339).                              |

Event detail (`admin.audit.explain`) adds the determining policies, policy-set version, manifest hash, and diagnostics for decision events - fetch it lazily from the SIEM for alerts rather than shipping it wholesale. Alert first on `decision: "deny"` spikes, `replay_detected`, and delegation events for sessions outside your expected label set.

## What to capture in incidents

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

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

## Validate the export

Generate one allow, deny, approval, Delegation, and Gateway result. Confirm request correlation, ordering in the destination, replay-safe deduplication by event ID, and credential redaction. Expected result: an operator can move from a SIEM alert to the Caracal request trace without querying internal Redis.

:::caution[Failure point: polling cursor]
Do not use wall-clock time alone as an exactly-once cursor. Re-read an overlap window and deduplicate by event ID so late ingestion does not create gaps.
:::

## Next Step

Use [Debug Authorization Decisions](/v1.0/guides/authorize-access/) to turn a correlated deny into a focused correction.