API reference

Jobs

Background work, its per-item outcomes and the files exports write.

GET/jobs

List jobs

Running and recently finished jobs.

What runs in the background, as the Activity tray shows it: running jobs and those that finished in the last 15 minutes, running first, newest first, with progress, recent throughput and whether you may cancel or retry each. Needs read (guests 403); webhook deliveries and derived stills are never listed. Every change is announced on the realtime socket as an invalidate of the jobs collection: refetch on it instead of polling.

Permission: read

Parameters

NameTypeRequiredDescription
statusquerystringOptionalactive (queued or running) or recent (finished in the last 15 minutes); both when omitted.
startedByquerystringOptionalme: only jobs your person started, directly or through their agents and API keys.
kindquerystringOptionalOnly these job kinds, comma-separated.
limitquerystringOptionalAt most this many (1-100, 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

jobsarray of objectsRequired
Running jobs first, then finished ones.
jobs[].createdAtstring (date-time)
Accepted at.
jobs[].errorstring or null
Job-level error.
jobs[].errorCodestring
A registered error's stable code (such as meta_no_answer), for an app to say it in its language; absent for an error without one. error reads the same either way.
jobs[].errorParamsobject
The values errorCode's sentence names, present exactly when errorCode is.
jobs[].failedintegerRequired
Failed.
jobs[].finishedAtstring (date-time) or null
jobs[].idstring (uuid)Required
Job.
jobs[].kindstringRequired
What it does.
jobs[].metaNeedobject
When error is something only a person can do in Meta: need (as GET /integrations/meta/attention names it), adAccountId, profile (the Meta profile Pluto publishes with, by name, when Meta said it), profileActs (only that profile can do it), who (who acts, in one sentence) and next (what to do). Absent otherwise.
jobs[].statusstringRequired
Status.One of queued, running, succeeded, failed, partially_failed, cancelled
jobs[].subjectIdstring or null
Subject.
jobs[].subjectTypestring or null
Subject type.
jobs[].succeededintegerRequired
Done.
jobs[].totalintegerRequired
Items.
jobs[].updatedAtstring (date-time)
Last change.
jobs[].canCancelbooleanRequired
It runs and you may cancel it (a publish needs ads:publish and is canceled with POST /launches/{id}/publish/cancel; anything else with POST /jobs/{id}/cancel, which needs what its work needs as it runs: a live change what it changes (delivery:write to pause or resume, budgets:write for budgets, bids and dates, ads:delete to delete), comment replies social:write, other work that changes what runs on an ad platform ads:publish, a spending limit integrations:write and budgets:write, an audit log export exports:create and the rest launches:write).
jobs[].canRetrybooleanRequired
It finished with failures, its kind can be retried and you may (POST /jobs/{id}/retry).
jobs[].finishedintegerRequired
Items no longer queued or running (succeeded, failed, skipped or cancelled); total once the job finished.
jobs[].launchIdstring (uuid) or null
The launch the job is about.
jobs[].nextAtstring (date-time) or null
A running job that waits (a scheduled publish, or items held back by a provider limit): when its next item is due. Null while an item runs, when something is due now, and for finished jobs.
jobs[].progressobject or null
A Meta sync (meta_sync, meta_sync_scheduled) while it reads and after: the step it's on, the ad account it reads and what Meta returned so far, summed over every ad account read. Null for other jobs and before the sync's first step.
jobs[].progress.adAccountNamestring or null
The ad account being read, once past the account list.
jobs[].progress.adSetsinteger
Ad sets found so far.
jobs[].progress.adsinteger
Ads found so far.
jobs[].progress.campaignsinteger
Campaigns found so far.
jobs[].progress.stepstring
ad_accounts (reading which ad accounts and Pages the connection has), then per ad account campaigns, ad_sets and ads.One of ad_accounts, campaigns, ad_sets, ads
jobs[].startedByobjectRequired
jobs[].startedBy.idstring (uuid)Required
Person, API key or agent.
jobs[].startedBy.kindstringRequired
Actor kind.One of person, api_key, agent, system
jobs[].stoppedBecausestring or null
Why the job stopped without anyone cancelling it: account_off (its ad account was turned off in Pluto), disconnected (Meta was disconnected) or reconnect_needed (Meta's access ended). What it did before stays.One of account_off, disconnected, reconnect_needed
jobs[].subjectNamestring or null
The launch's name for a job about a launch; the ad account's for an import from Meta or a sync of one ad account.
jobs[].throughputobject or null
Running jobs only: items that finished during the last seconds (two minutes, less for a younger job). Divide for a rate; it reflects provider pacing, so it is the honest base for an estimate.
jobs[].throughput.itemsinteger
Finished items.
jobs[].throughput.secondsnumber
Window length.
jobs[].unitsobject or null
What people count, when it isn't the items: a publish_launch job's ads (total, and done: no longer queued or running).
jobs[].units.doneinteger
Done.
jobs[].units.totalinteger
In the job.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 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/jobs" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/jobs/{id}

Get a job

A job's status and counts.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe job'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

createdAtstring (date-time)
Accepted at.
errorstring or null
Job-level error.
errorCodestring
A registered error's stable code (such as meta_no_answer), for an app to say it in its language; absent for an error without one. error reads the same either way.
errorParamsobject
The values errorCode's sentence names, present exactly when errorCode is.
failedintegerRequired
Failed.
finishedAtstring (date-time) or null
idstring (uuid)Required
Job.
kindstringRequired
What it does.
metaNeedobject
When error is something only a person can do in Meta: need (as GET /integrations/meta/attention names it), adAccountId, profile (the Meta profile Pluto publishes with, by name, when Meta said it), profileActs (only that profile can do it), who (who acts, in one sentence) and next (what to do). Absent otherwise.
statusstringRequired
Status.One of queued, running, succeeded, failed, partially_failed, cancelled
subjectIdstring or null
Subject.
subjectTypestring or null
Subject type.
succeededintegerRequired
Done.
totalintegerRequired
Items.
updatedAtstring (date-time)
Last change.

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/jobs/8a2c8b96-7441-44d5-a00a-a07d58300b3b" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/jobs/{id}/cancel

Cancel queued items

Completed provider effects are not undone.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe job's ID.
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.

Response200 OK

createdAtstring (date-time)
Accepted at.
errorstring or null
Job-level error.
errorCodestring
A registered error's stable code (such as meta_no_answer), for an app to say it in its language; absent for an error without one. error reads the same either way.
errorParamsobject
The values errorCode's sentence names, present exactly when errorCode is.
failedintegerRequired
Failed.
finishedAtstring (date-time) or null
idstring (uuid)Required
Job.
kindstringRequired
What it does.
metaNeedobject
When error is something only a person can do in Meta: need (as GET /integrations/meta/attention names it), adAccountId, profile (the Meta profile Pluto publishes with, by name, when Meta said it), profileActs (only that profile can do it), who (who acts, in one sentence) and next (what to do). Absent otherwise.
statusstringRequired
Status.One of queued, running, succeeded, failed, partially_failed, cancelled
subjectIdstring or null
Subject.
subjectTypestring or null
Subject type.
succeededintegerRequired
Done.
totalintegerRequired
Items.
updatedAtstring (date-time)
Last change.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this 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/jobs/8a2c8b96-7441-44d5-a00a-a07d58300b3b/cancel" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 09b6aa10-d0fe-4886-879a-0b794ef79d45"
GET/jobs/{id}/items

List a job's items

Per-item outcomes.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe job's ID.
statusquerystringOptionalqueued, running, succeeded, failed, skipped or cancelled.
afterquerystringOptionalCursor (position).
limitquerystringOptionalPage size.
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
This page.
items[].attemptsinteger
Attempts so far.
items[].errorstring or null
Why it failed; while queued again, what it waits for (a retry's reason, or Meta still processing a video).
items[].keystringRequired
Stable item key.
items[].metaNeedobject
When error is something only a person can do in Meta: need (as GET /integrations/meta/attention names it), adAccountId, profile (the Meta profile Pluto publishes with, by name, when Meta said it), profileActs (only that profile can do it), who (who acts, in one sentence) and next (what to do). Absent otherwise.
items[].outputobject or null
Result, once the item succeeded (publish_launch media: {imageHash}, or {videoId, thumbnailHash} / {videoId, thumbnailUrl} for a video).
items[].positionintegerRequired
Order; the paging cursor.
items[].providerIdstring or null
ID at the provider once created.
items[].stageinteger
The stage it runs in; a stage starts when every earlier one is done. Its meaning is the job kind's: publish_launch 0 media (a video uploads in chunks and waits here until Meta has processed it), 1 campaign, 2 ad sets, 3 creatives, 4 ads, 5 readback; apply_revisions 0 campaign, 1 ad sets, 2 ads, 3 budget changes held for Meta's hourly limit; delete_at_meta 0 ads, 1 ad sets.
items[].statusstringRequired
Item status.
items[].updatedAtstring (date-time)
Last change.
nextAfterstring or integer or null
Cursor for the next page; null at the end.

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/jobs/8a2c8b96-7441-44d5-a00a-a07d58300b3b/items" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/jobs/{id}/retry

Retry failed items

Queues a finished job's failed items again with fresh attempts and re-opens the job; the retrying credential owns the remaining work. Retryable kinds: publish_launch (needs publish; the launch must still match what was approved, and items skipped because of the failures plus the readback run again), import_media and apply_launch_spec (failed spec items apply again by external key, so nothing already applied is created twice). 409 when the job is still running, was canceled, has nothing failed, or its kind can't be retried.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe job's ID.
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.

Response200 OK

createdAtstring (date-time)
Accepted at.
errorstring or null
Job-level error.
errorCodestring
A registered error's stable code (such as meta_no_answer), for an app to say it in its language; absent for an error without one. error reads the same either way.
errorParamsobject
The values errorCode's sentence names, present exactly when errorCode is.
failedintegerRequired
Failed.
finishedAtstring (date-time) or null
idstring (uuid)Required
Job.
kindstringRequired
What it does.
metaNeedobject
When error is something only a person can do in Meta: need (as GET /integrations/meta/attention names it), adAccountId, profile (the Meta profile Pluto publishes with, by name, when Meta said it), profileActs (only that profile can do it), who (who acts, in one sentence) and next (what to do). Absent otherwise.
statusstringRequired
Status.One of queued, running, succeeded, failed, partially_failed, cancelled
subjectIdstring or null
Subject.
subjectTypestring or null
Subject type.
succeededintegerRequired
Done.
totalintegerRequired
Items.
updatedAtstring (date-time)
Last change.
retriedintegerRequired
Items queued again.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Not retryable now; the problem says why.
  • 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/jobs/8a2c8b96-7441-44d5-a00a-a07d58300b3b/retry" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 67080912-4e35-430d-b9b8-3e5ba17a27a9"
GET/jobs/{id}/stages

Count items per stage

A job's items counted per stage and item kind (what the item key names before its colon, e.g. ad_set or creative; null for keys without one), by status, in one read instead of paging through GET /jobs/{id}/items. Stages and kinds with no items are left out.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe job'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

jobIdstring (uuid)Required
The job.
stagesarray of objectsRequired
By stage, then kind (null last).
stages[].cancelledintegerRequired
Canceled.
stages[].failedintegerRequired
Failed.
stages[].kindstring or nullRequired
What the item keys name before their colon (media, ad_set, creative, ad…); null for keys without one.
stages[].queuedintegerRequired
Waiting to run.
stages[].runningintegerRequired
Running now.
stages[].skippedintegerRequired
Skipped.
stages[].stageintegerRequired
The stage, as GET /jobs/{id}/items numbers it.
stages[].succeededintegerRequired
Succeeded.
stages[].totalintegerRequired
Items.

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/jobs/8a2c8b96-7441-44d5-a00a-a07d58300b3b/stages" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/exports/{id}

Get an export

An export of this workspace, of any kind (kind: audit_log, workspace or usage): 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 start that export may read it: the audit log's for whoever may export that log (exports:create), a workspace's for the organization's owners and admins, the usage's for whoever may read all the usage it holds.

Permission: read

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

bombooleanRequired
The file starts with a UTF-8 byte order mark, so a spreadsheet reads accented and non-Latin letters correctly.
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 rows, 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.
filtersobjectRequired
What it applies, as checked.
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).
kindstringRequired
What it holds: the audit log, a workspace's launches, ad sets and ads, or usage events.One of audit_log, workspace, usage
organizationIdstring (uuid) or nullRequired
The organization it's of; null for a workspace's audit log.
rowsTotalinteger or nullRequired
The rows it holds, once counted (null before); the file's own count once it's written.
rowsWrittenintegerRequired
The rows in the file so far.
statusstringRequired
done: the file is written and can be downloaded until expiresAt.One of queued, running, done, failed
workspaceIdstring (uuid) or nullRequired
The workspace a workspace export is of; null for other kinds.

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/exports/591b4a91-0807-456c-a866-7ebbca042b12" \
  -H "Authorization: Bearer $PLUTO_KEY"