API reference

Audit log

Every change in the workspace and where it came from.

GET/audit-log

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.

Permission: admin

Parameters

NameTypeRequiredDescription
actorKindquerystringOptionalperson, api_key, agent or system.
actorIdquerystringOptionalA person, API key or agent.
personquerystringOptionalA person (user ID): what they did, what was done for them, and what they approved.
originquerystringOptionalapp, api_key, mcp, agent_chat, loop or system.
originIdquerystringOptionalAn Agent chat or a loop run.
loopIdquerystringOptionalEvery run of a loop.
targetTypequerystringOptionalWhat kind of thing changed (launch, ad_set, loop, api_key, ...).
targetIdquerystringOptionalOne object.
actionquerystringOptionalAn action (launch.publish_requested), or a prefix ending in . (launch.).
commandIdquerystringOptionalThe entries of one command: the Idempotency-Key it was sent with.
sincequerystringOptionalFrom this time on (RFC 3339).
untilquerystringOptionalBefore this time (RFC 3339).
qquerystringOptionalWords to find in names, the target, the action and the details shown.
orderquerystringOptionalnewest (default) or oldest first, over every page; a cursor belongs to its order.
afterquerystringOptionalCursor: nextAfter from the previous page.
limitquerystringOptionalPage size (1-200, default 50).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
Entries, newest first.
items[].actionstringRequired
What happened, as a stable machine name (launch.publish_requested). Show summary to people instead.
items[].actorobjectRequired
items[].actor.idstring (uuid)Required
The person, API key or agent.
items[].actor.kindstringRequired
Who acted.One of person, api_key, agent, system
items[].actor.namestring or null
Their name.
items[].approvalobject or null
The approval that let it run, if one did.
items[].approval.approvedByobject or null
Who approved it.
items[].approval.approvedBy.idstring (uuid)Required
User ID.
items[].approval.approvedBy.namestring or null
Their name.
items[].approval.idstring (uuid)Required
The approval.
items[].approval.kindstringRequired
An Agent approval card, a loop's approval, or a plan (change set).One of agent, loop, change_set
items[].commandIdstring or null
The command (Idempotency-Key) it belongs to.
items[].createdAtstring (date-time)Required
When it happened.
items[].detailobject
What changed and why, where it says more than summary: before and after, changes, fields, from and to, a reason, a role, status or scopes, an amount and currency, a plan or cadence, a source, 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[].idstring (uuid)Required
Entry ID.
items[].onBehalfOfobject or null
The person accountable: the person themself, the person an agent acts for, an API key's creator, or a loop's owner.
items[].onBehalfOf.idstring (uuid)Required
User ID.
items[].onBehalfOf.namestring or null
Their name.
items[].originobjectRequired
items[].origin.idstring (uuid) or null
The Agent chat, or the loop run.
items[].origin.kindstringRequired
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.namestring or null
The loop's name, or the chat's title when you can open the chat.
items[].origin.parentIdstring (uuid) or null
The loop of a loop run.
items[].requestIdstring or null
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[].summarystringRequired
What happened, in one human sentence with the target's name.
items[].targetobjectRequired
items[].target.idstringRequired
Its ID (a Meta ID for objects only in Meta).
items[].target.launchIdstring (uuid) or null
The launch of an ad set, ad or comment.
items[].target.namestring or null
Its current name, or the one recorded.
items[].target.typestringRequired
What kind of thing changed (launch, ad_set, loop, api_key, ...).
items[].workspaceIdstring (uuid)
The workspace it happened in (an organization's log spans its workspaces).
nextAfterstring or nullRequired
Pass as after for the next page; null on the last.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 402plan_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-After seconds. 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"
POST/audit-log/exports

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.

Permission: adminCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

actionstring
An action, or a prefix ending in . (launch.).
actorIdstring (uuid)
Only this person, API key or agent.
actorKindstring
Only this kind of actor.One of person, api_key, agent, system
commandIdstring
Only the entries of this command (its Idempotency-Key).
gzipboolean
Compress the file with gzip (.csv.gz).
loopIdstring (uuid)
Only from runs of this loop.
orderstring
The file's order: newest first (default) or oldest.One of newest, oldest
originstring
Only from this channel.One of app, api_key, mcp, agent_chat, loop, system
originIdstring (uuid)
Only from this Agent chat or loop run.
personstring (uuid)
A person: what they did, what was done for them and what they approved.
qstring
Words to find in names, the target, the action and the details shown.
sincestring (date-time)
Only from this time on.
targetIdstring
Only changes to this object.
targetTypestring
Only changes to this kind of thing.
untilstring (date-time)
Only before this time.

Response202 Accepted

bytesinteger or nullRequired
The file's size, once written.
createdAtstring (date-time)Required
When it was asked for.
downloadUrlstring or nullRequired
A link to the file for 15 minutes, once it's written and until it expires; read the export again for a new one.
emailWhenReadybooleanRequired
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.
errorstring or nullRequired
Why it failed.
expiredbooleanRequired
Past expiresAt: the file is gone.
expiresAtstring (date-time) or nullRequired
When downloads end: 7 days after it was written.
fileNamestringRequired
The file's name: audit-log-<workspace or organization>-<date>.csv.
filtersobjectRequired
The filters it applies.
finishedAtstring (date-time) or nullRequired
When it was written, or failed.
gzipbooleanRequired
The file is gzipped (.csv.gz).
idstring (uuid)Required
The export.
jobIdstring (uuid) or nullRequired
The job that writes it: follow it with GET /jobs/{id} (MCP wait_for_job).
organizationIdstring (uuid) or nullRequired
The organization whose log it is; null for the workspace's.
rowsTotalinteger or nullRequired
The entries the filters match, once counted (null before); the file's own count once it's written.
rowsWrittenintegerRequired
The entries in the file so far.
statusstringRequired
done: the file is written and can be downloaded until expiresAt.One of queued, running, done, failed

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 402plan_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 carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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/audit-log/exports/{id}

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.

Permission: admin

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe export's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

bytesinteger or nullRequired
The file's size, once written.
createdAtstring (date-time)Required
When it was asked for.
downloadUrlstring or nullRequired
A link to the file for 15 minutes, once it's written and until it expires; read the export again for a new one.
emailWhenReadybooleanRequired
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.
errorstring or nullRequired
Why it failed.
expiredbooleanRequired
Past expiresAt: the file is gone.
expiresAtstring (date-time) or nullRequired
When downloads end: 7 days after it was written.
fileNamestringRequired
The file's name: audit-log-<workspace or organization>-<date>.csv.
filtersobjectRequired
The filters it applies.
finishedAtstring (date-time) or nullRequired
When it was written, or failed.
gzipbooleanRequired
The file is gzipped (.csv.gz).
idstring (uuid)Required
The export.
jobIdstring (uuid) or nullRequired
The job that writes it: follow it with GET /jobs/{id} (MCP wait_for_job).
organizationIdstring (uuid) or nullRequired
The organization whose log it is; null for the workspace's.
rowsTotalinteger or nullRequired
The entries the filters match, once counted (null before); the file's own count once it's written.
rowsWrittenintegerRequired
The entries in the file so far.
statusstringRequired
done: the file is written and can be downloaded until expiresAt.One of queued, 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-After seconds. 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"