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



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

Returns the partner-visible audit trail for the calling org: one row 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](/docs/trust/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`, `mutation.scheduled_post_canceled`). 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)', description: 'Lower bound inclusive on `occurredAt`.' },
  { name: 'until', type: 'string (ISO-8601)', 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 "X-Api-Key: $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": "2481fa5c-a404-44ed-a561-565392499abc",
        "projectId": "254a4ce1-f4ca-42b1-9e36-17ca45ef3d39",
        "apiKeyId": "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.

## Retention [#retention]

Layers' retention commitment for partner-visible audit events:

| Tier                     | Medium                                  | Access                                                                                                                                                                            |
| ------------------------ | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **90 days hot**          | Queryable online                        | `GET /v1/audit-log` returns rows directly.                                                                                                                                        |
| **2 years cold archive** | Same schema as hot, exported on request | Available for partner export on a **5-business-day** request via [legal@layers.com](mailto:legal@layers.com). The export is CSV or JSONL, delivered as a time-bounded signed URL. |

**For longer-than-2-year retention needs** (for example, 7-year retention 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`). Layers does not today offer 7-year retention on our side; partners treating this endpoint as their system-of-record should mirror events to a pipeline under their own control.

Longer Layers-side retention (up to 2 years hot, 7 years cold) 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
* [Security & compliance](/docs/api/operational/security-and-compliance)