# List audit trail entries (ids, codes and chain fields only)

Requires the `audit_log:read` scope.

`GET /audit-trail`

Scope `audit_log:read` | Plan **Growth+**

Requires the `audit_log:read` scope. Needs the `audit_trail` plan feature.

## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `limit` | integer | no | Page size. minimum 1, maximum 100, default 25 |
| `offset` | integer | no | Rows to skip (offset mode). Cannot be combined with cursor. minimum 0, maximum 10000, default 0 |
| `cursor` | string | no | An opaque cursor taken from meta.nextCursor of the previous page (cursor mode). Valid for 24 hours and bound to the token and the query; do not parse or construct it. |
| `sort[createdAt]` | string | no | Sort direction for createdAt. One of `asc`, `desc`. |
| `sort[id]` | string | no | Sort direction for id. One of `asc`, `desc`. |
| `sort[seqNum]` | string | no | Sort direction for seqNum. One of `asc`, `desc`. |
| `filter[action][eq]` | string | no | Filter action (eq). |
| `filter[action][in]` | string | no | Filter action (in). Comma-separated, at most 50 values. |
| `filter[actorId][eq]` | string | no | Filter actorId (eq). |
| `filter[actorId][in]` | string | no | Filter actorId (in). Comma-separated, at most 50 values. |
| `filter[createdAt][gte]` | string (date-time) | no | Filter createdAt (gte). |
| `filter[createdAt][lt]` | string (date-time) | no | Filter createdAt (lt). |
| `filter[id][eq]` | string | no | Filter id (eq). |
| `filter[id][in]` | string | no | Filter id (in). Comma-separated, at most 50 values. |
| `filter[seqNum][gte]` | integer | no | Filter seqNum (gte). |
| `filter[seqNum][lt]` | integer | no | Filter seqNum (lt). |
| `filter[subjectType][eq]` | string | no | Filter subjectType (eq). |
| `filter[subjectType][in]` | string | no | Filter subjectType (in). Comma-separated, at most 50 values. |

## Returns

The `data` field of the standard `{ data, error, meta }` envelope:

An array of object:
- `action`: object Action code and group.
  - `code`: string
  - `group`: string
  - No other fields.
- `actorId`: string or null Actor id: usr_<id> for a user, apitoken:<id> for an API token, system:<job> for the platform; null when the stored value is not an id.
- `chainStatus`: string verified, accepted (a reviewed, approved chain exception) or unverified (legacy entry or a break on this page).
- `createdAt`: string (date-time) When the entry was recorded (UTC). The trail is append-only: use createdAt (or seqNum) to sync.
- `id`: string Opaque entry id (24 hex characters); the cursor tie-break.
- `seqNum`: integer or null Position in the hash chain; null for legacy entries recorded before the chain.
- `subjectId`: string or null Subject id; null when the stored value is not an id.
- `subjectType`: string Kind of the subject.
- No other fields.

## Errors

| Status | Code | Retry | Meaning |
|---|---|---|---|
| 400 | - | no | The request is invalid. |
| 401 | - | no | The token is missing, malformed, expired or revoked. |
| 402 | - | no | The organisation's plan does not include the feature this route needs. |
| 403 | - | no | The token may not use this route. |
| 429 | - | yes | Rate limit or row budget exceeded; retry after the time in Retry-After. |
| 500 | - | no | Unexpected server error. |
| 503 | - | yes | A dependency is temporarily unavailable; retry later. |

## Example

### curl

```bash
curl "https://api.autociso.io/api/v1/audit-trail" \
  -H "Authorization: Bearer <your-api-token>"
```

### Python

```python
import requests

response = requests.get(
    "https://api.autociso.io/api/v1/audit-trail",
    headers={"Authorization": "Bearer <your-api-token>"},
)
print(response.json())
```

### JavaScript

```javascript
const response = await fetch("https://api.autociso.io/api/v1/audit-trail", {
  method: "GET",
  headers: { "Authorization": "Bearer <your-api-token>" },
});
console.log(await response.json());
```

## Response (200)

```json
{
  "data": [
    {
      "action": {
        "code": "employee.updated",
        "group": "employee"
      },
      "actorId": "usr_1hgyq7m2k9xa",
      "chainStatus": "verified",
      "createdAt": "2026-10-12T09:15:22Z",
      "id": "6707c3a91f4e2b0012ab34cd",
      "seqNum": 10482,
      "subjectId": "empl_1hgyun41rx48",
      "subjectType": "employee"
    },
    {
      "action": {
        "code": "asset.created",
        "group": "asset"
      },
      "actorId": "apitoken:tok_1hj4w2c8n6pz",
      "chainStatus": "verified",
      "createdAt": "2026-10-12T09:16:05Z",
      "id": "6707c3b41f4e2b0012ab34d0",
      "seqNum": 10483,
      "subjectId": "ast_1hk40c2n8v3r",
      "subjectType": "asset"
    }
  ],
  "error": null,
  "meta": {
    "hasMore": true,
    "limit": 2,
    "nextCursor": "c2VxOjEwNDgz"
  }
}
```