List Audit Events

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

GET /api/v1/audit/events

cURL

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"

Response

{
  "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
}

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.

cURL

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"

Response

{
  "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 and Splunk: packaged pollers for this endpoint.
• Amazon S3 and Security Lake and HTTPS receiver: push the same events to your own storage or endpoint instead of polling.