Audit log
Every change in the workspace and where it came from.
List audit log entries
Every change in the workspace, newest first (or order=oldest): what people, the in-app Agent, loops, API keys and MCP clients did. Each entry names who acted, the person it was for (onBehalfOf: the person themself, the person an agent acts for, an API key's creator or a loop's owner), where it came from (origin: the app, the API, MCP, an Agent chat or a loop run) and who approved it, with a human summary, what changed (detail) and the request it came from (requestId). Workspace admins only; a credential needs admin, and its reads are logged too. The audit log comes with Business and Enterprise: 402 plan_limit (feature: audit_log, upgradeTo: business) on other plans. Keyset-paged: pass nextAfter as after. The organization's own entries (organization. and billing. actions: its people, invitations, roles and billing) are listed only for its owners and admins; a credential needs organization.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
actorKind | string | Optional | person, api_key, agent or system. |
actorId | string | Optional | A person, API key or agent. |
person | string | Optional | A person (user ID): what they did, what was done for them, and what they approved. |
origin | string | Optional | app, api_key, mcp, agent_chat, loop or system. |
originId | string | Optional | An Agent chat or a loop run. |
loopId | string | Optional | Every run of a loop. |
targetType | string | Optional | What kind of thing changed (launch, ad_set, loop, api_key, ...). |
targetId | string | Optional | One object. |
action | string | Optional | An action (launch.publish_requested), or a prefix ending in . (launch.). |
commandId | string | Optional | The entries of one command: the Idempotency-Key it was sent with. |
since | string | Optional | From this time on (RFC 3339). |
until | string | Optional | Before this time (RFC 3339). |
q | string | Optional | Words to find in names, the target, the action and the details shown. |
order | string | Optional | newest (default) or oldest first, over every page; a cursor belongs to its order. |
after | string | Optional | Cursor: nextAfter from the previous page. |
limit | string | Optional | Page size (1-200, default 50). |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- Entries, newest first.
items[].action- What happened, as a stable machine name (
launch.publish_requested). Showsummaryto people instead. items[].actoritems[].actor.id- The person, API key or agent.
items[].actor.kind- Who acted.One of
person,api_key,agent,system items[].actor.name- Their name.
items[].approval- The approval that let it run, if one did.
items[].approval.approvedBy- Who approved it.
items[].approval.approvedBy.id- User ID.
items[].approval.approvedBy.name- Their name.
items[].approval.id- The approval.
items[].approval.kind- An Agent approval card, a loop's approval, or a plan (change set).One of
agent,loop,change_set items[].commandId- The command (Idempotency-Key) it belongs to.
items[].createdAt- When it happened.
items[].detail- What changed and why, where it says more than
summary:beforeandafter,changes,fields,fromandto, areason, arole,statusorscopes, anamountandcurrency, aplanorcadence, asource, and the IDs it touched (launchId,jobId, ...). Only these kinds of keys are shown, never a secret, and an email only on an entry about that invitation or person.{}when there's nothing to add. items[].id- Entry ID.
items[].onBehalfOf- The person accountable: the person themself, the person an agent acts for, an API key's creator, or a loop's owner.
items[].onBehalfOf.id- User ID.
items[].onBehalfOf.name- Their name.
items[].originitems[].origin.id- The Agent chat, or the loop run.
items[].origin.kind- Where it came from: the app, the REST API, an MCP client, the in-app Agent, a loop run, or Pluto itself.One of
app,api_key,mcp,agent_chat,loop,system items[].origin.name- The loop's name, or the chat's title when you can open the chat.
items[].origin.parentId- The loop of a loop run.
items[].requestId- The request (
x-request-id) or tool call it came from, to find it in your logs; null for entries recorded before requests were kept. items[].summary- What happened, in one human sentence with the target's name.
items[].targetitems[].target.id- Its ID (a Meta ID for objects only in Meta).
items[].target.launchId- The launch of an ad set, ad or comment.
items[].target.name- Its current name, or the one recorded.
items[].target.type- What kind of thing changed (
launch,ad_set,loop,api_key, ...). items[].workspaceId- The workspace it happened in (an organization's log spans its workspaces).
nextAfter- Pass as
afterfor the next page; null on the last.
Errors
- 400The request is malformed.
- 401No valid credential.
- 402
plan_limit(feature: audit_log,upgradeTo: business): the audit log comes with Business. - 403The credential lacks the permission, or belongs to another workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/audit-log" \
-H "Authorization: Bearer $PLUTO_KEY"Export the audit log
Starts a CSV export of the workspace's audit log with the list's filters (gzip: true for .csv.gz) and answers 202 with the export. It runs in the background: the job (jobId) counts the entries, then writes every one of them, and rowsWritten of rowsTotal says how far it got. Read it with GET /audit-log/exports/{id}, which gives downloadUrl once it's done; downloads end 7 days later. Asking again with the same filters while one is queued or running returns that one. The person who asked gets an Inbox notice when it's ready, and an email too when it ran longer than 30 seconds or holds more than 250,000 entries (emailWhenReady). Every export is audited (audit_log.export_requested, audit_log.exported). Workspace admins; a credential needs admin.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
action- An action, or a prefix ending in
.(launch.). actorId- Only this person, API key or agent.
actorKind- Only this kind of actor.One of
person,api_key,agent,system commandId- Only the entries of this command (its Idempotency-Key).
gzip- Compress the file with gzip (
.csv.gz). loopId- Only from runs of this loop.
order- The file's order: newest first (default) or oldest.One of
newest,oldest origin- Only from this channel.One of
app,api_key,mcp,agent_chat,loop,system originId- Only from this Agent chat or loop run.
person- A person: what they did, what was done for them and what they approved.
q- Words to find in names, the target, the action and the details shown.
since- Only from this time on.
targetId- Only changes to this object.
targetType- Only changes to this kind of thing.
until- Only before this time.
Response
bytes- The file's size, once written.
createdAt- When it was asked for.
downloadUrl- A link to the file for 15 minutes, once it's written and until it expires; read the export again for a new one.
emailWhenReady- It runs longer than 30 seconds or holds more than 250,000 entries, or the app's page that asked for it was left before it was ready: the person who asked also gets an email when it's ready.
error- Why it failed.
expired- Past
expiresAt: the file is gone. expiresAt- When downloads end: 7 days after it was written.
fileName- The file's name:
audit-log-<workspace or organization>-<date>.csv. filters- The filters it applies.
finishedAt- When it was written, or failed.
gzip- The file is gzipped (
.csv.gz). id- The export.
jobId- The job that writes it: follow it with
GET /jobs/{id}(MCPwait_for_job). organizationId- The organization whose log it is; null for the workspace's.
rowsTotal- The entries the filters match, once counted (null before); the file's own count once it's written.
rowsWritten- The entries in the file so far.
statusdone: the file is written and can be downloaded untilexpiresAt.One ofqueued,running,done,failed
Errors
- 400The request is malformed.
- 401No valid credential.
- 402
plan_limit(feature: audit_log,upgradeTo: business): the audit log comes with Business. - 403The credential lacks the permission, or belongs to another workspace.
- 409Conflict: a stale
expectedVersion(the body carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/audit-log/exports" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: d25e27b9-7d7a-476b-ae1e-8396578d6ab2" \
-H "Content-Type: application/json" \
-d '{
"action": "launch.",
"actorId": "6c125817-4e50-4eb9-8477-114ed6c3f69e",
"actorKind": "person",
"commandId": "ca4b1318-93a6-403c-9e0c-0e2ff51907bd",
"gzip": true,
"loopId": "94956d8d-acdf-4e32-b384-25d0b605c2a9",
"order": "newest",
"origin": "app",
"originId": "17f4a382-2c27-4e34-a66f-6c98e0d379dd",
"person": "917f53a3-2f30-4f02-a755-31a2d4a5799f",
"q": "vitamin c serum",
"since": "2026-09-21T14:05:00Z",
"targetId": "01af096e-7668-46f6-8a67-e1ee7742b6fc",
"targetType": "video",
"until": "2026-09-30T13:00:00Z"
}'Get an audit log export
An export of this workspace's audit log, or of its organization's: its status and progress (rowsWritten of rowsTotal), size, when downloads end and, once it's done and until then, downloadUrl, a link to the file for 15 minutes (read the export again for a new one). Whoever may read that log may read its exports: the workspace's admins, or the organization's owners and admins for the organization's.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The export's ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
bytes- The file's size, once written.
createdAt- When it was asked for.
downloadUrl- A link to the file for 15 minutes, once it's written and until it expires; read the export again for a new one.
emailWhenReady- It runs longer than 30 seconds or holds more than 250,000 entries, or the app's page that asked for it was left before it was ready: the person who asked also gets an email when it's ready.
error- Why it failed.
expired- Past
expiresAt: the file is gone. expiresAt- When downloads end: 7 days after it was written.
fileName- The file's name:
audit-log-<workspace or organization>-<date>.csv. filters- The filters it applies.
finishedAt- When it was written, or failed.
gzip- The file is gzipped (
.csv.gz). id- The export.
jobId- The job that writes it: follow it with
GET /jobs/{id}(MCPwait_for_job). organizationId- The organization whose log it is; null for the workspace's.
rowsTotal- The entries the filters match, once counted (null before); the file's own count once it's written.
rowsWritten- The entries in the file so far.
statusdone: the file is written and can be downloaded untilexpiresAt.One ofqueued,running,done,failed
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/audit-log/exports/591b4a91-0807-456c-a866-7ebbca042b12" \
-H "Authorization: Bearer $PLUTO_KEY"