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

# Audit Logs API

The Audit Logs API returns a structured record of events that occurred in your Fireblocks workspace. Use it to feed compliance tooling, SIEM platforms, monitoring dashboards, and automation pipelines. For the full endpoint reference, see [Get audit logs](/api-reference/audit-logs/get-audit-logs).

<Note>
  If you are already using the legacy `timePeriod` and `cursor` parameters, your integration continues to work without code changes.
</Note>

***

## Endpoint

```text theme={"system"}
GET /v1/management/audit_logs
```

***

## Permissions

The caller's API key must be associated with one of the following workspace user roles:

* Admin
* Non-Signing Admin
* Auditor
* Security Admin
* Security Auditor

Any other role returns a `403 Forbidden` error.

***

## Query parameters

### Date range

| Parameter   | Type               | Description                                                                                                    |
| :---------- | :----------------- | :------------------------------------------------------------------------------------------------------------- |
| `startTime` | integer (epoch ms) | Start of the query window.                                                                                     |
| `endTime`   | integer (epoch ms) | End of the query window. Must be strictly greater than `startTime`. Defaults to the current time when omitted. |

If neither `startTime` nor the deprecated `timePeriod` are supplied, the endpoint returns events from the last 24 hours.

**Example:**

```text theme={"system"}
?startTime=1735689600000    // 2026-01-01T00:00:00Z
&endTime=1738367999000      // 2026-01-31T23:59:59Z
```

***

### Filters

| Parameter  | Type   | Description                                              |
| :--------- | :----- | :------------------------------------------------------- |
| `category` | string | The event category. See [Filter values](#filter-values). |
| `subject`  | string | The event subject.                                       |
| `event`    | string | The event type.                                          |
| `user`     | string | The user name that triggered the event.                  |
| `userId`   | string | The ID of the user who triggered the event.              |

**Usage notes:**

* Each filter accepts one or more values by repeating the query key.
* Values are case-sensitive and must match exactly.
* Values that contain spaces or special characters must be URL-encoded — for example, `Outgoing transaction` becomes `Outgoing%20transaction`.

**Combination logic:**

* Multiple values for the **same** field combine as **OR**. For example, `?category=Administration&category=Security` returns events in either category.
* Values across **different** fields combine as **AND**. For example, `?category=Security&userId=abc123` returns events that are in the Security category **and** triggered by user `abc123`.
* OR logic across different fields is not supported. You cannot retrieve events that are either by user X or in category Y in a single query.

***

### Sorting and pagination

| Parameter    | Type                     | Default | Description                                                                                             |
| :----------- | :----------------------- | :------ | :------------------------------------------------------------------------------------------------------ |
| `order`      | string (`ASC` or `DESC`) | `DESC`  | Sort direction. Case-sensitive. Results are always sorted by event timestamp.                           |
| `pageSize`   | integer                  | `200`   | Number of results per page. Minimum `1`, maximum `500`.                                                 |
| `pageCursor` | string                   | —       | The cursor returned in the previous response's `next` field. Pass this value to retrieve the next page. |

Pagination is cursor-based. When more results exist, the response includes a non-null `next` value. The response does not include a total count.

***

## Response

### Top-level shape

```json theme={"system"}
{
  "data": [ /* audit log events */ ],
  "next": "eyJjdXJzb3IiOiAi..."
}
```

`next` is `null` when no further pages exist.

<Note>
  For backward compatibility, the response also includes a deprecated `cursor` field with the same value as `next`. New integrations should read `next`.
</Note>

***

### Per-event fields

| Field       | Type     | Description                                 |
| :---------- | :------- | :------------------------------------------ |
| `id`        | string   | Unique identifier for the event.            |
| `timestamp` | ISO 8601 | The time in which the event occurred.       |
| `category`  | string   | The event category.                         |
| `subject`   | string   | The event subject.                          |
| `event`     | string   | The event type.                             |
| `userId`    | string   | The ID of the user who triggered the event. |
| `tenantId`  | string   | The workspace tenant ID.                    |

***

## Filter values

All filter values are drawn from a controlled vocabulary maintained by Fireblocks. Filtering against values not in the vocabulary returns an empty result set.

### `category` (15 values)

`Administration` · `Whitelist` · `Wallets` · `Exchanges` · `Settlements` · `Policies` · `Compliance` · `Transactions` · `Web3` · `Developers` · `Assets` · `Keys` · `Automation` · `Orders` · `Security`

### `subject` (61 values)

Subjects describe the kind of entity an event acted on. Common values include: `Transaction`, `Policy`, `Vault`, `Wallet`, `User`, `Sign in`, `Webhook endpoint`, and `Report`. See [Audit Log Events](/reference/audit-log-events) for the full list.

### `event` (\~200 values)

Events describe the action taken — for example, `Submitted`, `Completed`, `Failed`, `Created`, `Approved`, `Changed password`. Event values are scoped to a subject; the same event name can appear under multiple subjects. Filter by `category` or `subject` first to narrow the relevant set. See [Audit Log Events](/reference/audit-log-events) for the full list.

***

## Examples

### Filter by multiple categories within a date range

```text theme={"system"}
GET /v1/management/audit_logs
    ?category=Administration
    &category=Security
    &startTime=1735689600000
    &endTime=1738367999000
```

Returns events in the `Administration` or `Security` category between January 1 and January 31, 2026.

***

### Query everything a specific user did in a date range

```text theme={"system"}
GET /v1/management/audit_logs
    ?userId=abc123
    &startTime=1735689600000
    &endTime=1738367999000
```

***

### Filter by category, subject, and event together

```text theme={"system"}
GET /v1/management/audit_logs
    ?category=Transactions
    &subject=Outgoing%20transaction
    &event=Completed
    &startTime=1735689600000
```

Returns only completed outgoing transactions.

***

### Paginate through results

**First request:**

```text theme={"system"}
GET /v1/management/audit_logs?category=Security&pageSize=100&order=DESC
```

**Response:**

```json theme={"system"}
{
  "data": [ /* ... */ ],
  "next": "eyJjdXJzb3IiOiAi..."
}
```

**Next page:**

```text theme={"system"}
GET /v1/management/audit_logs?category=Security&pageSize=100&order=DESC&pageCursor=eyJjdXJzb3IiOiAi...
```

When `next` is `null`, you have retrieved all results.

***

## Errors

| Status            | When                                                                                                                                                                                              |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400 Bad Request` | `startTime` or `endTime` is not a finite integer; `endTime` is not strictly greater than `startTime`; `order` is not exactly `ASC` or `DESC`; `pageSize` is not an integer between `1` and `500`. |
| `403 Forbidden`   | The caller's role is not permitted to access audit logs.                                                                                                                                          |

Error responses include a machine-readable code and a human-readable message:

```json theme={"system"}
{
  "message": "Invalid pageSize. Must be between 1 and 500.",
  "code": 2903
}
```

***

## Backward compatibility

| Legacy parameter                     | Status                                                                                        | Use instead             |
| :----------------------------------- | :-------------------------------------------------------------------------------------------- | :---------------------- |
| `timePeriod` (values: `DAY`, `WEEK`) | Deprecated. Ignored when `startTime` is provided. Defaults to `DAY` when neither is supplied. | `startTime` / `endTime` |
| `cursor`                             | Deprecated alias of `pageCursor`. If both are sent, `pageCursor` wins.                        | `pageCursor`            |