Organisations

Read an organisation's audit log

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`.
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`
400	A filter or the cursor is not valid.	`ErrorResponse`
401	Not signed in, or the key is not valid.	`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`
404	No such organisation, the caller is not a member of it, or the key is another organisation's.	`ErrorResponse`
429	Too many requests.	`ErrorResponse`
503	Organisations are not set up on this server.	`ErrorResponse`

Response body

A 200 answer has the type 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.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.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.

Doc	Why
API reference	Every endpoint, and the error envelope
Schemas	Every request and response type
Tool reference	The operations as callable tools