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

# List Audit Events

> Read your organisation's audit events in order, for a SIEM or any other poller.

> [!NOTE]
>
> **Preview.** This endpoint is available to organisations with the audit log. Organisations that do not record audit events receive `409 recording_disabled`.

Returns your organisation's audit events in the order Wordsmith recorded them, oldest first. It is built for security tools such as Microsoft Sentinel and Splunk, which poll it every few minutes and keep the `next_cursor` of each page.

1. Make the first request with `start_time`, or with no parameters to start at the oldest event still kept.
2. Store `next_cursor` from every response, including an empty one.
3. While `has_more` is `true`, request again at once with that cursor.
4. When `has_more` is `false`, wait for your polling interval, then request again with the stored cursor.

Each event is delivered **at least once**. If a request fails or your tool crashes before it stores the cursor, the next request returns some events again, so deduplicate by `event_id`. Events can arrive out of `occurred_at` order: a sign-in event can be recorded minutes or hours after it happened, and it is then returned after events that occurred later. Order and resume by the cursor, never by `occurred_at`.

## Authentication

Send an API key with the `audit:read` scope, or a full-access key, as a bearer token in the `Authorization` header. The key's owner must be allowed to export the audit log; this is checked on every request, so a key stops working when its owner loses that permission. An OAuth access token with `audit:read` also works for organisations in the OAuth pilot.

The cursor belongs to your organisation, not to the key, so you can rotate the key and carry on from the same cursor.

## Query parameters

**cursor** `string`

The `next_cursor` from the previous response. When it is present, `start_time` and `end_time` are ignored.

**start\_time** `string`

RFC 3339 timestamp with a time zone, such as `2026-10-22T14:00:00Z`. Without a cursor, start at events recorded at or after this time.

**end\_time** `string`

RFC 3339 timestamp with a time zone. Without a cursor, stop at events recorded at or before this time. The `next_cursor` of the last page then continues after the window.

**limit** `integer` (default: 100)

Events per page, from 1 to 100.

**categories** `string`

Comma-separated categories to return: `authentication`, `identity_management`, `access`, `credentials`, `tool_execution`, `internal_tool_execution`, `audit_access` and `configuration`. Defaults to every category except `internal_tool_execution`, the calls the Wordsmith agent makes to its own tools.

## Response

**data** `array`

The events, oldest first. A page can hold fewer than `limit` events, or none, while `has_more` is `true`: the request stops after reading a bounded part of the feed.

**next\_cursor** `string`

Always present. Store it and send it with the next request, even when `data` is empty.

**has\_more** `boolean`

`true` when more events may be ready now. Request again at once.

Each event is a stream envelope (`stream_schema_version` 1). Every key is always present, and a field with no value is `null`:

| Field | Meaning |
| - | - |
| `event_id` | Unique ID of the event. Use it to deduplicate. |
| `organisation_id` | Your organisation's ID. |
| `occurred_at` | When the action happened, RFC 3339 UTC with milliseconds. |
| `category`, `action` | The event family and the action, such as `authentication` and `auth.signed_in`. Tolerate categories and actions you do not know. |
| `outcome` | `succeeded` or `failed`. |
| `actor` | `kind` (`user` or `system`), `id` and `name`. |
| `resource` | `type`, `id` and `name` of what was acted on. |
| `source` | `origin` (`wordsmith`, or `auth0` for sign-in events), `ip`, `user_agent` and `request_id`. `ip` and `user_agent` are `null` unless your organisation has enabled request metadata. |
| `context` | Extra fields that are safe to share, as strings, such as the MCP server and tool of a tool call, or the scopes of a new API key. |
| `changes` | The names of the fields an action changed. Values are never included, so `before` and `after` are always `null` and `values_omitted` is `true`. |

## Freshness and rate limits

The feed is read up to two minutes behind the current time, so an event reaches this endpoint up to two minutes after it is recorded. A cursor never expires: every event your organisation's audit log keeps stays readable.

Each API key, or each OAuth app and user, can make 60 requests a minute to this endpoint. These requests do not count towards your organisation's [API request limit](https://wordsmithai.mintlify.site/rate-limits.md).

```bash cURL theme={null}
curl "https://api.wordsmith.ai/api/v1/audit/events?start_time=2026-10-22T00:00:00Z&limit=100" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"
```

```json Response theme={null}
{
  "data": [
    {
      "stream_schema_version": 1,
      "event_id": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",
      "organisation_id": "7b1e9c40-2d3f-4a5b-8c6d-9e0f1a2b3c4d",
      "occurred_at": "2026-10-22T15:03:11.482Z",
      "category": "credentials",
      "action": "api_key.created",
      "outcome": "succeeded",
      "actor": { "kind": "user", "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Alex Admin" },
      "resource": { "type": "api_key", "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "name": "SIEM" },
      "source": { "origin": "wordsmith", "ip": null, "user_agent": null, "request_id": "req-7f3a" },
      "context": { "scopes": "audit:read" },
      "changes": [
        { "field": "name", "before": null, "after": null, "values_omitted": true },
        { "field": "scopes", "before": null, "after": null, "values_omitted": true }
      ]
    }
  ],
  "next_cursor": "eyJ2IjoyLCJjIjoiN2IxZTljNDAtMmQzZi00YTViLThjNmQtOWUwZjFhMmIzYzRkIiwicCI6IjAwMDAwMDAxNzkyNjgxMzkxNTAwI2F1ZGl0X2V2ZW50IzViNmM3ZDhlLTlmMGEtNGIxYy04ZDJlLTNmNGE1YjZjN2Q4ZSJ9",
  "has_more": false
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `invalid_cursor` | `cursor` is not one this API returned to your organisation. |
| 400 | `bad_request` | `start_time` or `end_time` is not an RFC 3339 timestamp with a time zone, `end_time` is before `start_time`, `limit` is outside 1 to 100, or `categories` names an unknown category. |
| 403 | `insufficient_scope` | The key or token does not have `audit:read`. |
| 403 | `forbidden` | The key's owner may not export the audit log. |
| 409 | `recording_disabled` | Your organisation does not record audit events. |
| 429 | `rate_limit_exceeded` | More than 60 requests a minute with this key. Wait for the `Retry-After` seconds. |

## Related pages

* [Microsoft Sentinel](https://wordsmithai.mintlify.site/siem/sentinel.md) and [Splunk](https://wordsmithai.mintlify.site/siem/splunk.md): packaged pollers for this endpoint.
* [Amazon S3 and Security Lake](https://wordsmithai.mintlify.site/siem/aws.md) and [HTTPS receiver](https://wordsmithai.mintlify.site/siem/https.md): push the same events to your own storage or endpoint instead of polling.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.