# Audit Logs

> Audit logs record every state-changing action taken inside an org. Filter, page, and export immutable event history across platform, scheduling, cost, provisioning, and deployment scopes.

Source: https://zop.dev/developer-docs/administration/audit-logs

---

Audit logs record every state-changing action taken inside an org — whether it came from a user via the UI, a script via the API, a schedule, or a webhook. Logs are immutable once written and can be filtered, paged, and exported.

**Info**

Anything that mutates state — create, update, delete, attach, detach, accept, reject, deploy, rollback, schedule, cancel. Read-only requests are not logged at this layer (use access logs or your gateway logs for those).

## Product Scopes

Every audit log entry is tagged with a product scope so you can filter the noise from one area without affecting another.

| Scope | Covers |
|---|---|
| `platform` | Org settings, users, teams, roles, RBAC, integrations |
| `scheduling` | Schedules, resource groups, overrides, manual actions, autoscaler policies, event readiness |
| `cost` | Budgets, billing connections, dashboards, showback configuration |
| `provisioning` | Spaces, provisioning jobs, databases, connections, catalog component installs |
| `deployment` | Projects, environments, deployment spaces, deployments, revisions, rollbacks, service connections |

## List Audit Logs

### GET /audit-logs

List audit log entries with filtering and pagination.

  #### Query Parameters

  | Parameter | Description |
  |---|---|
  | `scope` | Filter by product scope (comma-separated) |
  | `action` | Filter by action verb (create, update, delete, deploy, ...) |
  | `actor` | Filter by acting user email or "system:..." |
  | `resourceType` | Filter by the object type acted upon (deployment, schedule, ...) |
  | `resourceID` | Filter to events on a specific object |
  | `from` | ISO 8601 — start of time range |
  | `to` | ISO 8601 — end of time range |
  | `page` | Page number (default: 1) |
  | `limit` | Items per page (default: 50, max: 200) |

```json title="Response"
{
  "data": {
    "items": [
      {
        "id": "log_001",
        "scope": "deployment",
        "action": "rollback",
        "actor": "user@company.com",
        "resourceType": "deployment",
        "resourceID": "dep_xyz",
        "metadata": {
          "fromRevisionID": "rev_005",
          "toRevisionID": "rev_004",
          "reason": "regressing latency"
        },
        "createdAt": "2026-04-29T11:30:00Z"
      },
      {
        "id": "log_002",
        "scope": "scheduling",
        "action": "delete",
        "actor": "system:scheduler",
        "resourceType": "override",
        "resourceID": "ovr_abc",
        "metadata": { "reason": "expired" },
        "createdAt": "2026-04-29T11:25:00Z"
      }
    ],
    "total": 8421,
    "page": 1,
    "limit": 50
  }
}
```

## Export

### POST /audit-logs/export

Export audit logs matching a filter as CSV. Returns a signed download URL valid for 24 hours.

```bash title="Request"
curl -X POST https://zopnight.com/api/audit-logs/export \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "deployment",
    "from": "2026-04-01T00:00:00Z",
    "to": "2026-04-30T23:59:59Z",
    "format": "csv"
  }'
```

```json title="Response"
{
  "data": {
    "downloadURL": "https://zopnight.com/exports/audit-2026-04.csv",
    "expiresAt": "2026-04-30T01:00:00Z"
  }
}
```

## Retention

Audit logs are retained for 13 months by default. Contact your CSM if you need a longer retention window for compliance reasons — ZopNight can stream logs to your S3 / GCS / ABS bucket on a daily cadence.

See [Organizations](https://zop.dev/docs/administration/organizations) for the org-level audit settings and [Roles & Permissions](https://zop.dev/docs/administration/roles-permissions) for who can read and export audit logs.