# Read an organisation's audit log

> Page: https://docs.plotwork.dev/api/get-orgs-org-audit. Index of every page: https://docs.plotwork.dev/llms.txt

One page of the audit log, newest first: who did what to what, and when.

`GET /orgs/{org}/audit`

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | Read an organisation's audit log. |
| What does it take? | `org` in the path, and `actor`, `action`, `target`, `from`, `to`, `cursor`, `limit` in the query string. |
| What does it return? | Status 200 with a body of type [`OrgAuditPage`](https://docs.plotwork.dev/api/schemas.md#orgauditpage). |
| What can go wrong? | `400` a filter or the cursor is not valid; `401` not signed in, or the key is not valid; `403` a member or a reader, or a key without `audit:read` (orgs.forbidden), or a plan that keeps no audit log (plan.audit_not_included); `404` no such organisation, the caller is not a member of it, or the key is another organisation's; `429` too many requests; `503` organisations are not set up on this server. Every failure uses the one error envelope. |

## What it does

One page of the audit log, newest first: who did what to what, and when. Filter by actor, action or group, target and time. The owner and admins, or an organisation key with `audit:read`. Pro keeps 30 days, Enterprise 365; Free records nothing.

## Path parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `org` | `string` | yes | The organisation's id or its slug. |

## Query parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `actor` | `string` | no | An actor's account or key id, or their address or key name, matched whole and without regard to case. |
| `action` | `string` | no | An action, or a group of them by its first two parts. |
| `target` | `string` | no | A target's id, or its name, matched whole and without regard to case. |
| `from` | `string` | no | From this time on (inclusive). |
| `to` | `string` | no | Before this time (exclusive). |
| `cursor` | `string` | no | The page's `nextCursor` from the page before, for the next, older page. |
| `limit` | `integer` | no | Events in the page, 1 to 200. Default 50. |

## Responses

| Status | Meaning | Body |
|---|---|---|
| 200 | The page. | [`OrgAuditPage`](https://docs.plotwork.dev/api/schemas.md#orgauditpage) |
| 400 | A filter or the cursor is not valid. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 401 | Not signed in, or the key is not valid. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 403 | A member or a reader, or a key without `audit:read` (orgs.forbidden), or a plan that keeps no audit log (plan.audit_not_included). | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 404 | No such organisation, the caller is not a member of it, or the key is another organisation's. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 429 | Too many requests. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 503 | Organisations are not set up on this server. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |

## Response body

A 200 answer has the type [`OrgAuditPage`](https://docs.plotwork.dev/api/schemas.md#orgauditpage).

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | `OrgAuditEvent[]` | yes |  |
| `items[].version` | `1` | yes | The version of this shape. A change that is not only an addition gets a new number. |
| `items[].id` | `string` | yes |  |
| `items[].orgId` | `string` | yes |  |
| `items[].at` | `string` | yes | When it happened: an ISO 8601 time in UTC with milliseconds. |
| `items[].action` | `"orgs.org.create" \| "orgs.org.rename" \| "orgs.member.add" \| "orgs.member.remove" \| "orgs.member.leave" \| "orgs.member.role" \| "orgs.owner.transfer" \| "orgs.invite.create" \| "orgs.invite.revoke" \| "orgs.invite.accept" \| "orgs.key.create" \| "orgs.key.reveal" \| "orgs.key.revoke" \| "orgs.connection.create" \| "orgs.connection.revoke" \| "orgs.diagram.publish" \| "orgs.diagram.update" \| "orgs.diagram.edit" \| "orgs.diagram.restore" \| "orgs.diagram.lock" \| "orgs.diagram.unlock" \| "orgs.diagram.delete" \| "orgs.folder_rule.set" \| "orgs.folder_rule.clear" \| "orgs.brand.set" \| "orgs.brand.clear" \| "orgs.icon.set" \| "orgs.icon.delete" \| "orgs.avatar.set" \| "orgs.avatar.clear" \| "orgs.style_rules.set" \| "orgs.style_rules.clear" \| "orgs.settings.editable" \| "orgs.settings.publishing" \| "orgs.settings.agents" \| "orgs.publishing.move" \| "orgs.publishing.unpublish" \| "orgs.drift.report" \| "orgs.drift.settings" \| "orgs.integration.create" \| "orgs.integration.update" \| "orgs.integration.delete" \| "orgs.contract.set" \| "orgs.contract.end" \| "orgs.audit.export" \| "orgs.sso.signin" \| "orgs.sso.config" \| "orgs.sso.domain_add" \| "orgs.sso.domain_verify" \| "orgs.sso.domain_remove" \| "orgs.sso.signin_failed" \| "orgs.sso.jit" \| "orgs.sso.break_glass" \| "orgs.scim.token" \| "orgs.scim.user_create" \| "orgs.scim.user_update" \| "orgs.scim.user_deactivate" \| "orgs.scim.user_delete" \| "orgs.scim.group" \| "orgs.scim.role"` | yes | What happened. Never reused for another meaning. |
| `items[].actor` | `object` | yes |  |
| `items[].actor.kind` | `"user" \| "key" \| "ci" \| "operator"` | yes |  |
| `items[].actor.id` | `string \| null` | yes | The account id (`user`), the key id (`key`, `ci`), or null (`operator`). |
| `items[].actor.name` | `string \| null` | yes | The address or key name when it was recorded, "Plotwork support" for the operator, null once a deleted account is forgotten. |
| `items[].target` | `object` | yes |  |
| `items[].target.type` | `"org" \| "member" \| "invite" \| "key" \| "diagram" \| "folder" \| "brand" \| "icon" \| "avatar" \| "style_rules" \| "settings" \| "drift" \| "contract" \| "sso" \| null` | yes |  |
| `items[].target.id` | `string \| null` | yes |  |
| `items[].target.name` | `string \| null` | yes | A member's address, an invited address, a key's, a diagram's or an icon's name, or a folder. |
| `items[].metadata` | `object` | yes | A few facts about the event, such as `role` or `keepEditable`. Never a diagram source, a key, a token or a color. |
| `items[].ip` | `string \| null` | yes | The network the request came from: the IPv4 /24 or the IPv6 /48, never the full address. |
| `items[].userAgent` | `string \| null` | yes | The first 200 characters of the user agent. |
| `items[].requestId` | `string \| null` | yes | The request id, which Plotwork support can look up in the API's logs. |
| `nextCursor` | `string \| null` | yes | Send as `cursor` for the next, older page; null on the last. |
| `retentionDays` | `integer` | yes | How many days the organisation's plan keeps an event. |
| `canExport` | `boolean` | yes | Whether the organisation's plan may export the log. |

## See also

| Doc | Why |
|---|---|
| [API reference](https://docs.plotwork.dev/api/reference.md) | Every endpoint, and the error envelope |
| [Schemas](https://docs.plotwork.dev/api/schemas.md) | Every request and response type |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | The operations as callable tools |