# Audit logs Who did what, when, and where to read it. The audit log shows who changed what in your org, and when: admin and collaboration actions such as team changes, sharing and sign-ins. Read and export it at `/settings/org/audit-logs`, or feed it to your SIEM (security monitoring system) with the [Compliance API](https://docs.privatemind.com/audit-logs.html#compliance-api). You see only your own org's events. ## What is logged The audit log records actions that **change state**. Reads such as listing teams or viewing a member, and calls to a chat model, are not logged. The table below is the core set, and the [event types](https://docs.privatemind.com/audit-logs.html#event-types) endpoint lists every action name. Some rows are stored under an older name for the same action. Filtering on the action name finds those rows too, and the endpoint lists the older names as `legacy_actions`. | Action | Resource type | When it fires | | --------------------------------- | -------------------------- | ------------------------------------------------------------ | | `team_created` | `team` | A new team is created | | `team_updated` | `team` | A team's name, description, or settings change | | `team_deleted` | `team` | A team is deleted | | `team_member_added` | `team` | A user is added to a team | | `team_member_removed` | `team` | A user is removed from a team | | `team_member_role_updated` | `team` | A team member's role changes | | `source_shared` | `source` | A source is shared with another user or team | | `source_share_responded` | `source` | A user accepts or declines a share invitation | | `source_share_revoked` | `source` | A share is revoked | | `conversation_participant_invited` | `conversation_participant` | A user is invited into a conversation | | `conversation_team_invited` | `conversation_participant` | A team is invited into a conversation | | `conversation_invite_responded` | `conversation_invite` | A user accepts or declines a conversation invitation | | `conversation_participant_removed` | `conversation_participant` | A participant is removed from a conversation | | `global_source_activated` | `global_source` | A platform-managed source is activated for the org | | `global_source_deactivated` | `global_source` | A platform-managed source is deactivated | | `global_source_config_updated` | `global_source` | A platform-managed source's configuration changes | When your organisation has [Secrets](https://docs.privatemind.com/secrets.html) on, Secrets actions are logged too, including each time PrivateMind delivers a value to a workspace or job. Entries name the secret and never hold its value. [What is recorded](https://docs.privatemind.com/secrets.html#what-is-recorded) lists them. Workspace actions are logged too, among them `workspace_started` and `workspace_stopped`. A start or stop is logged whether it came from the Workspaces page, the [API or `pm`](https://docs.privatemind.com/workspaces.html#stop-and-start-without-the-browser), or an automation. Sign-ins have their own events: `user_signed_in`, `user_sign_in_failed` and `user_signed_out`, plus the passkey events (`user_passkey_added`, `user_passkey_removed`, `user_backup_codes_regenerated`, `user_backup_code_used`). **Settings → Org → Login History** shows the same sign-in records. Each entry stores: - **Timestamp** (UTC) - **User** (email and display name, looked up when the log is read) - **Action** and **resource type** (from the table above) - **Resource ID** (the affected team, source, conversation, etc.) - **Detail**: a small JSON object, usually `{ method, path }` of the HTTP request that caused the event - **IP address** of the request ## Layout The page has four parts, from top to bottom: - **Summary cards**: total events, unique users and unique actions over the selected range - **Top Actions**: the most frequent actions, by count - **Filters and export**: date range, action filter, page size and the export menu - **Log entries table**: paginated, newest first Click a row to see its `detail` JSON. Rows with no detail don't expand. ## Filtering Three filters control what you see: - **Date range.** Presets are 7, 30 and 90 days, or choose "Custom range" and pick two dates. The picker shows dates in your browser's time zone, but each date you pick covers a whole UTC day. Pick the same date for both to get that one full day. - **Action.** "All actions" (the default) or one of the actions in the current summary. Clicking a badge in Top Actions sets this filter, and clicking it again clears it. - **Page size.** 25, 50, or 100 rows per page. Changing any filter resets pagination to page 1. ## Exporting **Export** offers two formats: - **CSV**: one row per event, flattened, with the `detail` JSON as text in its own column. - **JSON**: every field, including the nested detail. Set the filters first: the export contains what they select, and there is no separate "download everything" option. The download uses your browser session, so you don't need an API key. > [!TIP] > A busy org can produce tens of thousands of rows over 90 days. To feed a SIEM regularly, use the Compliance API in place of nightly exports: it paginates predictably and supports incremental sync. ## Retention Audit log entries are kept indefinitely, with no automatic purge, and the Compliance API can read any record in your org's history. If you need a retention policy enforced, such as automatic deletion after 365 days for GDPR, ask your PrivateMind account contact. You can't set one in the app. ## Compliance API The Compliance API lets a script read your org's audit log and usage, for SIEM ingestion, reporting and automated compliance checks. The audit feed returns the same records as the page. The [usage endpoint](https://docs.privatemind.com/audit-logs.html#org-usage) returns daily or hourly request, token and cost totals for the whole org. Both use cursor-based pagination and authenticate with a compliance key, so they need no session cookie. ### Enabling the API An org admin turns on the Compliance API at **Settings → Org → Compliance API** (`/settings/org/compliance-api`), then mints compliance keys on the same page. Each key carries the scopes you pick when you mint it: `audit_logs:read` for the audit feed and `usage:read` for org usage. Neither includes the other, so a key minted for your SIEM can't read usage unless you grant it. Compliance keys are separate from the API keys used for inference. Turning the toggle off stops every compliance key at once, without revoking them one by one. ### Authentication A compliance key is an access key ID and a secret joined by a colon. Send the whole string, exactly as shown when you minted it, as a bearer token: ```text Authorization: Bearer : ``` Don't split the two halves across headers, and don't add or remove a prefix. A token that isn't exactly two parts separated by a colon returns `401`. ### Endpoint ```bash curl -s "https://privatemind.com/api/v1/compliance/audit-logs?from=2026-08-01&page_size=100" \ -H "Authorization: Bearer $COMPLIANCE_KEY" ``` The Compliance API is on `privatemind.com`. Don't send these requests to `api.privatemind.com`, which serves the inference API. ### Query parameters All parameters are optional. Without filters the endpoint returns the most recent events for your org. | Param | Type | Meaning | | --- | --- | --- | | `from` | RFC 3339 datetime or `YYYY-MM-DD` date | Lower bound, **inclusive** (`created_at >= from`). | | `to` | RFC 3339 datetime or `YYYY-MM-DD` date | Upper bound, **exclusive** (`created_at < to`). | | `action` | string | Filter to a single action, e.g. `user_signed_in`. Get valid values from [event types](https://docs.privatemind.com/audit-logs.html#event-types). | | `page_size` | integer | Page size. Default 100, maximum 1000. A larger value is treated as 1000. | | `cursor` | opaque string | Continuation token from the previous page's `next_cursor`. | There is no `resource_type` filter and no `limit`/`offset`. A `from` or `to` value that isn't a valid date is **silently ignored**, so the response is unfiltered on that side. Check your date format before you trust a result. Older names match too: a filter on `login` also returns rows stored as `user_signed_in`, and the other way round. ### Response ```json { "data": [ { "id": "18472", "timestamp": "2026-08-15T09:31:12.442Z", "actor": "jane.smith@example.com", "api_key_id": null, "action": "team_created", "resource_type": "team", "resource_id": "team-abc123", "metadata": { "method": "POST", "path": "/v1/teams" } } ], "pagination": { "next_cursor": "eyJ0IjoiMjAyNi0wOC0xNVQwOTozMToxMi40NDJaIiwiaSI6MTg0NzJ9", "has_more": true } } ``` | Field | Meaning | | --- | --- | | `id` | Record id, serialised as a **string**. | | `timestamp` | UTC timestamp of the event. | | `actor` | For an action made with a key, the key's label, or its id if it has no label. For an action by a person, their email. `null` for events the system started. | | `api_key_id` | The key that performed the action, or `null` when a human did. | | `action` | The action name. | | `resource_type` | The type of resource affected. | | `resource_id` | Id of the affected team, source, conversation, and so on. | | `metadata` | A small JSON object: `{ method, path }` of the HTTP request that caused the event. A row the platform wrote itself has its own detail in place of that: a workspace start or stop, or a job submitted, by an automation has `{ automation_run_id, workflow_id }`. `{}` when there is no detail. | Records are sorted newest first: by `timestamp` descending, then by `id` descending, so pages stay stable when several rows share a millisecond. Success responses have no `success` field, and no `user_email`, `user_display_name`, `detail`, `ip_address` or `created_at` field. PrivateMind records the caller's IP but doesn't return it here. ### Pagination Pagination is **cursor based, not offset based**. To walk the full set, pass each response's `next_cursor` back as `cursor`, and stop when `has_more` is `false`: ```bash CURSOR="" while : ; do PAGE=$(curl -s "https://privatemind.com/api/v1/compliance/audit-logs?page_size=1000${CURSOR:+&cursor=$CURSOR}" \ -H "Authorization: Bearer $COMPLIANCE_KEY") echo "$PAGE" | jq -c '.data[]' [ "$(echo "$PAGE" | jq -r '.pagination.has_more')" = "true" ] || break CURSOR=$(echo "$PAGE" | jq -r '.pagination.next_cursor') done ``` `next_cursor` is `null` on the last page. Pass the cursor back unchanged: don't decode, build or increment it. A malformed or stale cursor returns `400 invalid_cursor`. > [!TIP] > For incremental sync, don't keep a cursor between runs. It marks a position in a newest-first scan, so it can't tell the next run where new records begin. Store the newest `timestamp` you ingested and pass it as `from` on the next poll. ### Event types ```bash curl -s "https://privatemind.com/api/v1/compliance/audit-logs/event-types" \ -H "Authorization: Bearer $COMPLIANCE_KEY" ``` This returns every declared event type, so you can build filters and dashboards from the list without scanning stored history: ```json { "data": [ { "action": "team_created", "category": "org", "resource_type": "team", "description": "A team was created.", "legacy_actions": ["create"] } ] } ``` `legacy_actions` lists the older names an event is also stored under. ### Rate limits Requests are limited per compliance key, at the key's configured rate (60 per minute by default). Every response carries: - `x-ratelimit-limit-requests` - `x-ratelimit-remaining-requests` A throttled request returns `429`, with `Retry-After` (seconds) and `x-ratelimit-reset-requests` (an ISO timestamp) as well. ### Org usage `GET /api/v1/compliance/usage` returns your org's usage in daily or hourly UTC buckets, optionally broken down by model, user, team, API key or workspace. The key needs the `usage:read` scope. ```bash curl -s "https://privatemind.com/api/v1/compliance/usage?from=2026-09-01&group_by=model" \ -H "Authorization: Bearer $COMPLIANCE_KEY" curl -s "https://privatemind.com/api/v1/compliance/usage?bucket=hour&group_by=team" \ -H "Authorization: Bearer $COMPLIANCE_KEY" ``` All parameters are optional. A parameter not listed here, repeated or sent empty returns `400 invalid_parameter`. | Param | Type | Meaning | | --- | --- | --- | | `bucket` | `day` or `hour` | Bucket size. Default `day`. | | `from` | RFC 3339 datetime or `YYYY-MM-DD` date | Start of the range, rounded down to the UTC day or hour. Default: the last seven days ending with today, or the last 24 hours ending with the current hour. | | `to` | RFC 3339 datetime or `YYYY-MM-DD` date | End of the range, **exclusive**. Default: now. A value in the future is treated as now. | | `group_by` | `model`, `user`, `team`, `api_key` or `workspace` | Break each bucket down by one dimension. Without it, each bucket carries a single total. | | `model` | string | Only usage of this model. | | `user_id` | string | Only usage by this user id. | | `api_key_id` | string | Only usage made with this API key id. | | `limit` | integer | Buckets per page. Daily: default 7, maximum 31. Hourly: default 24, maximum 168. | | `cursor` | opaque string | Continuation token from the previous page's `next_cursor`. | The range can span at most 90 days with daily buckets and 31 days with hourly buckets. `from` and `to` must be ISO 8601. Unlike the audit feed, this endpoint rejects any other value with `400`. ```json { "data": [ { "start": "2026-09-01T00:00:00.000Z", "end": "2026-09-02T00:00:00.000Z", "results": [ { "model": "kimi-k3", "requests": 470, "input_tokens": 141201, "cached_input_tokens": 52000, "output_tokens": 9756, "total_tokens": 150957, "cost_usd": 12.34 } ] } ], "pagination": { "next_cursor": null, "has_more": false } } ``` | Field | Meaning | | --- | --- | | `start`, `end` | The bucket's UTC day or hour. The last bucket ends at `to`, so the current day or hour is partial and keeps growing. | | `results` | One row per group, most expensive first. Empty for a bucket with no usage; every bucket in the range is present. | | `model` / `api_key_id` / `workspace` | The group, when grouping by that dimension. `workspace` is the traffic source: `chat`, `default` (API and programmatic use), `embeddings`, `rerank` and so on. | | `user_id`, `user_email` | The user, when grouping by `user`. An org application key appears under its own service id with a `null` email. Usage by people who are no longer members of the org is combined into one row with `user_id` `former_user`, so each day still adds up. | | `team_id`, `team_name` | The team, when grouping by `team`. Usage is attributed by each user's current team membership: a user in two teams counts in both, so team totals can add up to more than the org total. Usage by users in no team, org application keys and former members is combined into one row with `team_id` `null`. | | `requests` | Number of calls. | | `input_tokens` | Prompt tokens, including cached ones. | | `cached_input_tokens` | The part of `input_tokens` served from the prompt cache. | | `output_tokens` | Completion tokens. For image generation, the number of images generated, so `output_tokens` and `total_tokens` include images on days with image usage. Group by `workspace` to separate them: image generation reports under `image`. | | `total_tokens` | `input_tokens + output_tokens`. | | `cost_usd` | Cost in USD, rounded for reporting. Omitted when your org's billing setup hides cost, in which case rows are ordered by tokens instead. | To walk a range longer than one page, pass `next_cursor` back as `cursor` with the **same** other parameters until `has_more` is `false`. A cursor belongs to the key and the query that produced it. Changing any parameter, or using it with another key, returns `400 invalid_cursor`. Each org has a limit on how fast it can read usage, shared by all its compliance keys. A request over that limit returns `429 rate_limited` with `Retry-After`. A page with too many groups for one response, such as thousands of users or keys, returns `422 too_many_groups`: lower `limit` or add a filter. ### Reads are themselves audited Every successful audit feed call writes its own audit record, with action `compliance_audit_logs_read` and resource type `compliance_api_key`, against the calling key. Your own polling shows up in the feed, and you can see who read the audit log. Usage reads are audited once per query. The first page writes a `compliance_usage_read` record naming the range, bucket, grouping and filters. Later pages fetched with its cursor add nothing. ### Error responses | Status | `error.type` | Meaning | | --- | --- | --- | | `400` | `invalid_cursor` | The `cursor` is malformed or no longer decodable, or (on the usage endpoint) does not match the query or key. Restart the walk without a cursor. | | `400` | `invalid_parameter` | Usage endpoint only: an unknown, repeated or malformed parameter, or a range over 90 days. | | `401` | none | Malformed, expired, or invalid key. The body has a `message` field and no `error` object. | | `403` | `insufficient_scope` | The key does not carry the endpoint's scope (`audit_logs:read` or `usage:read`). Also returned when no bearer token is supplied at all. | | `403` | `forbidden` | Usage endpoint only: the key is not an org compliance key. | | `403` | `feature_disabled` | The Compliance API is not enabled for the org, or the key resolves to no org context. | | `422` | `too_many_groups` | Usage endpoint only: too many groups for one page. Lower `limit` or add a filter. | | `429` | `rate_limit_error` | Rate limit exceeded. Honour `Retry-After`. | | `429` | `rate_limited` | Usage endpoint only: the org's usage read budget is spent. Honour `Retry-After`. | | `500` | none | The query failed. Safe to retry. | | `502` | `upstream_error` | Usage endpoint only: usage could not be read. Safe to retry. | | `503` | none | Key authentication is temporarily unavailable. Retry with backoff. | [Errors](https://docs.privatemind.com/errors.html) describes the general error format. This endpoint's success responses differ from it on purpose. ## What is **not** logged - Chat messages and model calls. Prompts and model responses are not in the audit log. Conversation history is stored separately, with its own retention. - Reads, such as listing teams, viewing a user's profile or opening a conversation. - Failed requests, with two exceptions. Admin and collaboration actions are recorded only when they succeed, so a `403` attempt to delete someone else's team is not logged. A failed sign-in (`user_sign_in_failed`) and a request refused by your organisation's network rules (`network_access_blocked`) are recorded. ## Where next - [Org settings](https://docs.privatemind.com/org-settings.html): the feature toggles whose flips you'd often want to cross-reference here - [Users and teams](https://docs.privatemind.com/users-and-teams.html): what the `team_member_added` / `team_member_role_updated` entries refer to