# Audit events

The audit log records every change and every refusal in the workspace, with who did it and with which credential.

Belongs to: [Credential](https://sparklogs.com/docs/api/reference/credential.md)

Ids: uuid.

- `GET /workspaces/{workspace_id}/audit-events` [List audit events](#list-audit-events)
- `GET /workspaces/{workspace_id}/audit-events/{id}` [Read an audit event](#read-audit-event)

## AuditEvent object

An audit event records one call that changed something or was refused: who made it, with which credential, on what, and how it ended.

- `id` (uuid, required): The event's id.
- `occurred_at` (date-time, required): When the event first happened.
- `last_occurred_at` (date-time, required): When it last happened: the same refusal repeated within a minute folds into one event, which keeps the first call's details, an MCP tool call's `mcp_operation_id` included.
- `occurrences` (integer, required): How many times it happened.
- `actor_kind` (string, required): What acted: user for a person, `workspace_key` for a workspace token, and others.
- `actor_id` (string, required): The id of who acted.
- `actor_desc` (string or null, required): Who acted, for a person to read. In a signed-in session, the member's email address. With an API token, the token's kind and the first 8 characters of its id (an OAuth token's app registration id), after the email address of the member it acts as: '<name@example.com> (API token 1a2b3c4d)', '<name@example.com> (connected app 9f8e7d6c)', 'workspace token 1a2b3c4d'. Null on older events and for someone outside the workspace.
- `credential_kind` (string, required): The credential used: session, `user_key`, oauth or `workspace_key`.
- `credential_id` (uuid or null, required): The API token used; null for a session.
- `action` (string, required): What was done, such as `organization.create`.
- `privileges` (array of string, required): The privileges the route asks for, not what the actor holds.
- `target_kind` (string or null, required): The kind of thing acted on.
- `target_id` (string or null, required): The id of the thing acted on; null when you are not shown it.
- `target_desc` (string or null, required): The thing acted on, for a person to read; null when you are not shown it.
- `target_hidden` (boolean): Sent as true when the target's id or name is withheld from you.
- `org_ids` (array of uuid or null, required): The organizations the event touched that you can see; null when the event names no organization.
- `all_orgs` (boolean, required): Whether the event covered every organization; `org_ids` then lists only those its details name.
- `other_orgs` (boolean): Sent as true when the event touched an organization you cannot see, left out without an id or a count.
- `details_withheld` (boolean): Sent as true when the event has details you are not shown.
- `outcome` (string, required): How the call ended, such as allowed, denied or failed.
- `reason` (string or null, required): Why a call was refused or failed: on a refusal, `token_scope` when only the API token's scopes refused it, else the privileges the call needs; on a failure, the error code.
- `details` (map of any or null, required): What the event recorded about the call, as an object whose keys depend on the action. A call made with an API token adds `credential_short_id`, as in `actor_desc`, and `credential_label`, the token's label or the OAuth app's name as it was when the event was written, or {"hidden": true} when the token covers an organization you cannot see. Null when the event recorded no details, or when you are not shown them (`details_withheld`).
- `details_v` (integer): Sent as 1 when details are shown field by field as the action declares them; left out on an older event, shown whole or withheld whole.
- `ip` (string or null, required): The address the call came from. For a call made through the SparkLogs MCP server, the address of the MCP client.
- `user_agent` (string or null, required): The user agent the call sent. For a call made through the SparkLogs MCP server, the user agent of the MCP client.
- `invocation_method` (one of the values below, required): How the call reached SparkLogs.
  - `direct`: The call came to the REST API or the app directly.
  - `mcp`: An MCP client made the call through the SparkLogs MCP server.

## List audit events

`GET https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/audit-events`

Preview

Returns the workspace's audit log a page at a time, newest first, filtered by actor, credential, organization, target, action, outcome and time; filters combine, a row passing every one given. Needs `auditlog.query`. Held over every organization, it shows every event. Held at some organizations, it shows a change when one of its organizations is inside them, a data read when one of its organizations is inside them or above them, or it covers every organization, and no event that names no organization, such as a change to the workspace itself; organizations you cannot see are left out of each event shown. Pages follow with `cursor`, as on every list.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: any of `admin:read`, `admin:write`
- Privilege: `auditlog.query`

Needs `auditlog.query`. `auditlog.query` applies at each organization a grant covers and every organization below it.

### Behavior

- Retry: Safe to send again
- Paging: Cursor · 500 a page by default, up to 5000 · newest first

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.

### Query parameters

- `actor_id` (string): Only events done by this actor: a user id, or a workspace token's id.
- `credential_id` (uuid): Only events done with this API token: what one token did, and so what it created.
- `organization_id` (uuid): Only events touching this organization.
- `target_id` (string): Only events done to this thing, such as one agent, group or member: what happened to it. An event whose target you are not shown never matches.
- `action` (array of string): Only events of these actions, such as `member.remove`. Each operation states the action it is recorded under as `audit_action`. A SparkLogs Agent changed before the `agent.` actions existed is recorded under the `ingest_key.` ones. A restore recorded before the `.restore` actions reached the workspace's region is under `<kind>.undelete`. A comma-separated list matches any of its values, each exactly and ignoring case.
- `action_prefix` (string): Only events whose action starts with this, ignoring case, such as `organization.`.
- `outcome` (array of one of the values below): Only events with one of these outcomes. A comma-separated list matches any of its values.
  - `allowed`: The call was allowed.
  - `denied`: The call was refused.
  - `failed`: The call failed.
- `invocation_method` (array of one of the values below): Only events whose call reached SparkLogs one of these ways. A comma-separated list matches any of its values.
  - `direct`: Calls made to the REST API or in the app directly.
  - `mcp`: Calls an MCP client made through the SparkLogs MCP server: its tool calls, and the REST calls it made through them.
- `occurred_since` (date-time): Only events at or after this time. An RFC 3339 time.
- `occurred_before` (date-time): Only events before this time. An RFC 3339 time.
- `cursor` (string): The `next_cursor` of the previous page, sent with the same filters: the page after it.
- `limit` (integer): How many events a page holds: 1 to 5000, 500 by default. It may change between pages.
  Default: `500` · 1 to 5000

### Response (200)

- `audit_events` (array of AuditEvent, required): The events, newest first.
- `next_cursor` (string or null, required): Null on the last page. Otherwise pass it as `cursor`, with the same filters, for the next page of older events.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A query parameter it does not take, or one given twice. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A filter's value is empty, names an empty item, is not one of the values the filter takes, or is not an id or a time where the filter asks for one; `parameter` names the filter. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `limit` is not 1 to 5000, `organization_id` is not a UUID, or `cursor` cannot be read or was sent with other filters. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You do not hold `auditlog.query`, or it covers no organization. The same refusal comes when the path names a workspace other than the token's own. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | `organization_id` names an organization outside your audit reach. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [Read an audit event](https://sparklogs.com/docs/api/reference/audit-events.md#read-audit-event)

### Example

List what a workspace token did in the last 30 days

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/audit-events?credential_id=4b1d0000-0000-4000-8000-000000000801&occurred_since=2026-10-11T00%3A00%3A00Z&limit=1" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "audit events retrieved",
  "audit_events": [
    {
      "id": "ad170000-0000-4000-8000-000000000701",
      "occurred_at": "2026-11-09T16:00:00Z",
      "last_occurred_at": "2026-11-09T16:00:00Z",
      "occurrences": 1,
      "actor_kind": "workspace_key",
      "actor_id": "4b1d0000-0000-4000-8000-000000000801",
      "actor_desc": null,
      "credential_kind": "workspace_key",
      "credential_id": "4b1d0000-0000-4000-8000-000000000801",
      "action": "organization.update",
      "privileges": [
        "organization.write"
      ],
      "target_kind": "organization",
      "target_id": "0a9e0000-0000-4000-8000-000000000105",
      "target_desc": "Harbor Dental",
      "org_ids": [
        "0a9e0000-0000-4000-8000-000000000105"
      ],
      "all_orgs": false,
      "outcome": "allowed",
      "reason": null,
      "details": {
        "changes": [
          {
            "field": "psa_client_id",
            "new": "10057",
            "old": null
          }
        ]
      },
      "details_v": 1,
      "ip": "203.0.113.24",
      "user_agent": "psa-sync/2.3",
      "invocation_method": "direct"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJleGFtcGxlIjoiYXVkaXQifQ"
}
```

## Read an audit event

`GET https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/audit-events/{id}`

Preview

Returns one audit event as the list shows it, its lists whole. Needs `auditlog.query`. One you cannot see returns 404, as one that does not exist does.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: any of `admin:read`, `admin:write`
- Privilege: `auditlog.query`

Needs `auditlog.query`. `auditlog.query` applies at each organization a grant covers and every organization below it.

### Behavior

- Retry: Safe to send again

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.
- `id` (uuid, required): The audit event's id.

### Response (200)

- `audit_event` (AuditEvent, required): The event, its lists whole.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A query parameter it does not take, or one given twice. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `id` is not a UUID. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You do not hold `auditlog.query`. The same refusal comes when the path names a workspace other than the token's own. | No |
| 404 | `APP_API_ERR_RECORD_NOT_FOUND` | No such event, or one you cannot see. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [List audit events](https://sparklogs.com/docs/api/reference/audit-events.md#list-audit-events)

### Example

Read an audit event

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/audit-events/ad170000-0000-4000-8000-000000000701" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "audit event retrieved",
  "audit_event": {
    "id": "ad170000-0000-4000-8000-000000000701",
    "occurred_at": "2026-11-09T16:00:00Z",
    "last_occurred_at": "2026-11-09T16:00:00Z",
    "occurrences": 1,
    "actor_kind": "workspace_key",
    "actor_id": "4b1d0000-0000-4000-8000-000000000801",
    "actor_desc": null,
    "credential_kind": "workspace_key",
    "credential_id": "4b1d0000-0000-4000-8000-000000000801",
    "action": "organization.update",
    "privileges": [
      "organization.write"
    ],
    "target_kind": "organization",
    "target_id": "0a9e0000-0000-4000-8000-000000000105",
    "target_desc": "Harbor Dental",
    "org_ids": [
      "0a9e0000-0000-4000-8000-000000000105"
    ],
    "all_orgs": false,
    "outcome": "allowed",
    "reason": null,
    "details": {
      "changes": [
        {
          "field": "psa_client_id",
          "new": "10057",
          "old": null
        }
      ]
    },
    "details_v": 1,
    "ip": "203.0.113.24",
    "user_agent": "psa-sync/2.3",
    "invocation_method": "direct"
  }
}
```

---

Source: <https://sparklogs.com/docs/api/reference/audit-events>
All SparkLogs documentation in Markdown: <https://sparklogs.com/llms.txt>
