# GET /v1/audit-log (/docs/api/reference/audit-log/list)



<Endpoint method="GET" path="/v1/audit-log" auth="Bearer" phase="1" />

Returns the partner-visible audit trail for the calling org: one event per material action (API request, auth event, mutation, kill-switch flip). The schema is designed to feed your own compliance review or SIEM without a support ticket - Layers itself does not publish a SOC 2 attestation today; see Certifications.

Rows are newest-first. Cursor-paginated using a keyset on `(occurredAt DESC, eventId ASC)` so deep iteration stays fast regardless of offset. Default limit 50, max 200. The cursor is opaque base64-url; treat it as a black box and pass it back unmodified on the next call.

<Parameters
  title="Query"
  rows="[
  { name: 'eventType', type: 'string', description: 'Filter to one event type (e.g. `api.request`, `auth.key_rejected`, `content.approved`, `content_review_policy.updated`, `scheduled_post.cancelled`). See operational/errors for the catalog.' },
  { name: 'projectId', type: 'string (UUID)', description: 'Filter to events scoped to one project.' },
  { name: 'apiKeyId', type: 'string (UUID)', description: 'Filter to events attributed to one API key. Useful for leaked-key forensics.' },
  { name: 'since', type: 'string (ISO 8601, UTC Z)', description: 'Lower bound inclusive on `occurredAt`.' },
  { name: 'until', type: 'string (ISO 8601, UTC Z)', description: 'Upper bound inclusive on `occurredAt`.' },
  { name: 'cursor', type: 'string', description: 'Opaque base64-url keyset cursor returned as `nextCursor` on a previous response. A malformed cursor returns 422 `VALIDATION`.' },
  { name: 'limit', type: 'integer', description: 'Default 50, max 200.' },
]"
/>

## Example [#example]

```bash
# Every auth failure in the last hour
curl "https://api.layers.com/v1/audit-log?eventType=auth.key_rejected&since=$(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ)&limit=100" \
  -H "Authorization: Bearer $LAYERS_API_KEY"
```

<Response status="200" description="OK">
  ```json
  {
    "items": [
      {
        "eventId": "7c2f1a3e-0b4c-4a11-9f7e-33c0a2c1bd55",
        "eventType": "api.request",
        "occurredAt": "2026-04-20T18:14:02.187Z",
        "requestId": "req_01HXA1NHKJZXPV8R7Q6WSM5BCD",
        "organizationId": "org_2481fa5c-a404-44ed-a561-565392499abc",
        "projectId": "prj_254a4ce1-f4ca-42b1-9e36-17ca45ef3d39",
        "apiKeyId": "key_c2037bb9-354d-4662-96b7-97a28ad6b6e1",
        "actor": "partner_api",
        "data": {
          "path": "/api/partner/v1/projects/254a4ce1.../content",
          "method": "POST",
          "status": 202,
          "latency_ms": 1907,
          "endpoint_class": "long-running"
        },
        "piiRedacted": true,
        "schemaVersion": 1
      }
    ],
    "nextCursor": "eyJvY2N1cnJlZEF0IjoiMjAyNi0wNC0yMFQxODoxNDowMi4xODdaIiwiZXZlbnRJZCI6IjdjMmYxYTNlLTBiNGMtNGExMS05ZjdlLTMzYzBhMmMxYmQ1NSJ9"
  }
  ```
</Response>

## Use cases [#use-cases]

* **Compliance review** - pull a time-bounded CSV via cursor iteration for your own audit-evidence needs.
* **Leaked-key forensics** - filter on `apiKeyId` to get every call the key made before you revoked it.
* **Incident response** - `since=&lt;30min ago>&eventType=auth.kill_switch_tripped` shows exactly what fired when.
* **Partner-side dashboards** - mirror Layers' audit trail into your own SIEM without a support ticket.

## Common event types [#common-event-types]

Subset of the catalog (see [Errors](/docs/api/operational/errors) for the full enum):

| `eventType`                     | Emitted when                                                     | Key `data` fields                                          |
| ------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------- |
| `api.request`                   | Every partner-API request that traverses the wrapper.            | `path`, `method`, `status`, `latency_ms`, `endpoint_class` |
| `auth.key_rejected`             | Bearer token rejected at the auth wrapper.                       | `reason`, `path`, `method`                                 |
| `auth.kill_switch_tripped`      | Kill-switch fired for a key, organization, or globally.          | `scope`, `path`                                            |
| `content.approved`              | Container flipped `pending` → `approved`.                        | `container_id`, `project_id`, `approval_source`            |
| `content.rejected`              | Container flipped `pending` → `rejected`.                        | `container_id`, `project_id`, `reason`                     |
| `content_review_policy.updated` | `PATCH /v1/projects/:projectId/content-review-policy` succeeded. | `project_id`, `diff.before`, `diff.after`                  |
| `scheduled_post.cancelled`      | Scheduled post cancelled before publish.                         | `scheduled_post_id`, `project_id`, `reason`                |

## Retention [#retention]

Layers' retention commitment for partner-visible audit events:

| Tier          | Medium                                               | Access                                                                                                                               |
| ------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Queryable** | Online                                               | `GET /v1/audit-log` returns rows directly.                                                                                           |
| **Archive**   | Same schema as queryable events, exported on request | Available for partner export via [legal@layers.com](mailto:legal@layers.com). The export is CSV or JSONL, delivered as a signed URL. |

For retention needs under your own compliance program, stream events to your own SIEM in real time. The `api.request` event carries every field needed to reconstruct a request (`requestId`, `apiKeyId`, `path`, `method`, `status`, `latency_ms`, `endpoint_class`, `occurredAt`). Partners treating this endpoint as their system-of-record should mirror events to a pipeline under their own control.

Longer Layers-side retention is available on the Enterprise tier under contract. Contact [legal@layers.com](mailto:legal@layers.com).

## Errors [#errors]

| Status | Code              | When                                                          |
| ------ | ----------------- | ------------------------------------------------------------- |
| 401    | `UNAUTHENTICATED` | Missing or invalid key.                                       |
| 422    | `VALIDATION`      | Unknown `eventType`, malformed timestamp, limit out of range. |

## See also [#see-also]

* [Errors](/docs/api/operational/errors) - canonical event-type catalog