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

# Admin Audit Log — Append-Only Record of Admin Actions

> Query the append-only audit log of all admin actions. Requires SUPER_ADMIN role. Each entry records the actor, action, target resource, and timestamp.

The Audit Log provides a tamper-proof, chronological record of every significant action taken by admin and super\_admin accounts on the platform. Each entry captures who performed an action, what was done, which resource was affected, and when it happened. Use the audit log to investigate incidents, satisfy compliance requirements, and monitor admin behaviour over time.

<Note>
  Audit log entries are **append-only**. They cannot be modified, soft-deleted, or hard-deleted through any API endpoint. The log is a permanent and authoritative record of admin activity.
</Note>

<Warning>
  This endpoint requires **SUPER\_ADMIN** role. Requests from ADMIN-level sessions will receive a `403 Forbidden` response.
</Warning>

***

## Authentication

The audit log endpoint requires:

* A valid `session` cookie (obtained via `POST /auth/login`)
* SUPER\_ADMIN role (ADMIN-level access is insufficient)

No write operations are available on this endpoint — it is read-only.

***

## Query the Audit Log

Retrieve a paginated, filterable view of the audit trail. Filter by the admin who performed the action, the action type, the resource type, a specific resource, or a date range to narrow down the log to the entries you need.

**`GET /admin/audit`**

<ParamField query="page" type="integer" default="1">
  Page number (1-based).
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Items per page. Minimum 1, maximum 100.
</ParamField>

<ParamField query="actor" type="string">
  Filter by the public ID of the admin who performed the action (e.g. `usr_01H`). Max 50 characters.
</ParamField>

<ParamField query="action" type="string">
  Filter by action name prefix. For example, passing `user.` returns all entries whose action starts with `user.`. Max 100 characters.
</ParamField>

<ParamField query="entity_type" type="string">
  Filter by the type of resource that was affected (e.g. `user`, `order`, `product`, `review`). Max 50 characters.
</ParamField>

<ParamField query="entity_public_id" type="string">
  Filter by the public ID of a specific resource to see all audit history for that record (e.g. `usr_01H`, `ord_01H`). Max 50 characters.
</ParamField>

<ParamField query="date_from" type="string">
  ISO 8601 datetime with UTC offset. Return entries created at or after this time.
</ParamField>

<ParamField query="date_to" type="string">
  ISO 8601 datetime with UTC offset. Return entries created at or before this time.
</ParamField>

<ParamField query="sort" type="string" default="-created_at">
  Sort by creation time. Use `created_at` for oldest-first or `-created_at` for newest-first.
</ParamField>

<CodeGroup>
  ```bash All Recent Entries theme={null}
  curl -X GET "https://api.example.com/api/v1/admin/audit?sort=-created_at&limit=50" \
    -H "Cookie: session=<your-super-admin-session>"
  ```

  ```bash Actions by a Specific Admin theme={null}
  curl -X GET "https://api.example.com/api/v1/admin/audit?actor=usr_01H&sort=-created_at" \
    -H "Cookie: session=<your-super-admin-session>"
  ```

  ```bash History for a Specific Resource theme={null}
  curl -X GET "https://api.example.com/api/v1/admin/audit?entity_public_id=ord_01H" \
    -H "Cookie: session=<your-super-admin-session>"
  ```

  ```bash Date-Range Query theme={null}
  curl -X GET "https://api.example.com/api/v1/admin/audit?date_from=2024-06-01T00:00:00.000Z&date_to=2024-06-30T23:59:59.000Z" \
    -H "Cookie: session=<your-super-admin-session>"
  ```
</CodeGroup>

***

## Response Structure

**`200 OK`**

<ResponseField name="success" type="boolean">
  Always `true` on a successful response.
</ResponseField>

<ResponseField name="data" type="array">
  Array of audit log entries.

  <Expandable title="Audit entry fields">
    <ResponseField name="public_id" type="string">
      Unique identifier for this audit entry (prefix: `aud_`). Use this to reference a specific log entry.
    </ResponseField>

    <ResponseField name="actor" type="string">
      The public ID of the admin or super\_admin who performed the action (e.g. `usr_01H`).
    </ResponseField>

    <ResponseField name="action" type="string">
      A dot-separated string describing what was done (e.g. `user.suspend`, `order.status.update`, `review.delete`). Max 100 characters.
    </ResponseField>

    <ResponseField name="entity_type" type="string">
      The type of resource that was targeted by this action (e.g. `user`, `order`, `product`, `review`, `coupon`). Max 50 characters.
    </ResponseField>

    <ResponseField name="entity_public_id" type="string">
      The public ID of the specific resource that was affected (e.g. `usr_01H`, `ord_01H`). Max 50 characters.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 UTC timestamp recording exactly when the action was performed.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Standard pagination metadata.

  <Expandable title="Pagination fields">
    <ResponseField name="page" type="integer">
      Current page number (1-based).
    </ResponseField>

    <ResponseField name="limit" type="integer">
      Items per page used in this request.
    </ResponseField>

    <ResponseField name="total" type="integer">
      Total number of audit entries matching the applied filters.
    </ResponseField>

    <ResponseField name="totalPages" type="integer">
      Total number of pages given the current `limit`.
    </ResponseField>

    <ResponseField name="hasNext" type="boolean">
      `true` if a subsequent page exists.
    </ResponseField>

    <ResponseField name="hasPrev" type="boolean">
      `true` if a previous page exists.
    </ResponseField>
  </Expandable>
</ResponseField>

**Example response:**

```json theme={null}
{
  "success": true,
  "data": [
    {
      "public_id": "aud_01H",
      "actor": "usr_01H",
      "action": "user.suspend",
      "entity_type": "user",
      "entity_public_id": "usr_02H",
      "created_at": "2024-06-12T14:35:22.000Z"
    },
    {
      "public_id": "aud_02H",
      "actor": "usr_01H",
      "action": "order.status.update",
      "entity_type": "order",
      "entity_public_id": "ord_01H",
      "created_at": "2024-06-12T13:10:05.000Z"
    },
    {
      "public_id": "aud_03H",
      "actor": "usr_03H",
      "action": "review.delete",
      "entity_type": "review",
      "entity_public_id": "rev_01H",
      "created_at": "2024-06-11T09:45:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 3,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}
```

***

## Error Responses

| Status Code | Meaning                                                             |
| ----------- | ------------------------------------------------------------------- |
| `200`       | Audit entries returned successfully.                                |
| `400`       | Invalid query parameters (e.g. malformed date, limit out of range). |
| `401`       | Missing or expired session.                                         |
| `403`       | Insufficient role — SUPER\_ADMIN required.                          |

***

## Usage Patterns

<Accordion title="Investigate a specific admin's actions">
  To audit everything an admin did during a time window, combine the `actor` filter with `date_from` and `date_to`:

  ```bash theme={null}
  curl -X GET "https://api.example.com/api/v1/admin/audit?actor=usr_01H&date_from=2024-06-01T00:00:00.000Z&date_to=2024-06-30T23:59:59.000Z" \
    -H "Cookie: session=<your-super-admin-session>"
  ```
</Accordion>

<Accordion title="Trace all changes to a resource">
  Pass `entity_public_id` to see the complete modification history of a specific order, product, user, or any other entity:

  ```bash theme={null}
  curl -X GET "https://api.example.com/api/v1/admin/audit?entity_public_id=usr_01H&sort=created_at" \
    -H "Cookie: session=<your-super-admin-session>"
  ```
</Accordion>

<Accordion title="Filter by action type">
  Use the `action` prefix filter to find all suspension events, for example:

  ```bash theme={null}
  curl -X GET "https://api.example.com/api/v1/admin/audit?action=user.suspend" \
    -H "Cookie: session=<your-super-admin-session>"
  ```
</Accordion>

<Accordion title="Export a compliance report">
  Page through the entire log for a fiscal period using date bounds and multiple pages:

  ```bash theme={null}
  curl -X GET "https://api.example.com/api/v1/admin/audit?date_from=2024-01-01T00:00:00.000Z&date_to=2024-03-31T23:59:59.000Z&limit=100&page=1&sort=created_at" \
    -H "Cookie: session=<your-super-admin-session>"
  ```

  Increment `page` until `meta.hasNext` is `false` to retrieve all entries.
</Accordion>