---
title: "Audit Events API | Gazebo Docs"
description: "Retrieve account-scoped Gazebo credential access events for security review, troubleshooting, and audit export."
url: "https://gazebohq.com/docs/api/audit-events"
---

The audit log is made up of individual **audit events**. Each event records an agent credential request and its outcome without including the credential value.

## List credential-access events

```
GET /api/v1/audit-events
```

Requires an [account API token](/docs/api/authentication).

```bash
curl "https://app.gazebohq.com/api/v1/audit-events?limit=50&service=stripe&outcome=success" \
  -H "Authorization: Bearer YOUR_ACCOUNT_API_TOKEN"
```

## Query parameters

| Parameter | Description |
|---|---|
| `limit` | Events per page, from 1 to 200. Defaults to 50 |
| `cursor` | Opaque cursor returned by the previous page |
| `agent_id` | Filter by one agent ID |
| `service` | Filter by normalized service identifier |
| `outcome` | Filter by `success`, `denied`, or `not_found` |
| `from` | Include events at or after this ISO 8601 timestamp |
| `to` | Include events at or before this ISO 8601 timestamp |

Filters can be combined. All results remain scoped to the account that owns the API token.

### Response

```json
{
  "events": [
    {
      "id": "event-id",
      "agentId": "agent-id",
      "agentName": "Support triage",
      "service": "stripe",
      "keyName": "primary",
      "action": "read",
      "outcome": "success",
      "method": "GET",
      "createdAt": "2026-09-04T05:45:12.000Z"
    }
  ],
  "nextCursor": "eyJjcmVhdGVkQXQiOi...",
  "hasMore": true
}
```

| Field | Description |
|---|---|
| `id` | Stable event identifier |
| `agentId` | Agent that made the request |
| `agentName` | Current agent name, or `null` if unavailable |
| `service` | Requested service |
| `keyName` | Requested credential name, `primary`, or `all` |
| `action` | Recorded operation; currently `read` |
| `outcome` | `success`, `denied`, or `not_found` |
| `method` | Intended HTTP method |
| `createdAt` | Event time as an ISO 8601 timestamp |

Events are account-scoped, ordered newest first, and never contain credential values.

## Pagination

When `hasMore` is `true`, pass `nextCursor` unchanged as the next request's `cursor`:

```bash
curl "https://app.gazebohq.com/api/v1/audit-events?limit=50&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer YOUR_ACCOUNT_API_TOKEN"
```

Keep the same filters while following cursors. A cursor is opaque and should not be parsed or modified by clients. When `hasMore` is `false`, `nextCursor` is `null`.

Plan-specific retention windows are not yet enforced. Retention limits shown on the pricing page are beta limits and will apply when entitlement enforcement is introduced.

## Legacy endpoint

`GET /api/v1/agents/credential-events` remains available for existing integrations. It returns a plain array containing up to the 200 newest events, but does not support filters or pagination. New integrations should use `/api/v1/audit-events`.