Jobs
Background work, its per-item outcomes and the files exports write.
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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
status | string | Optional | active (queued or running) or recent (finished in the last 15 minutes); both when omitted. |
startedBy | string | Optional | me: only jobs your person started, directly or through their agents and API keys. |
kind | string | Optional | Only these job kinds, comma-separated. |
limit | string | Optional | At most this many (1-100, 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
jobs- Running jobs first, then finished ones.
jobs[].createdAt- Accepted at.
jobs[].error- Job-level error.
jobs[].errorCode- A registered
error's stable code (such asmeta_no_answer), for an app to say it in its language; absent for an error without one.errorreads the same either way. jobs[].errorParams- The values
errorCode's sentence names, present exactly whenerrorCodeis. jobs[].failed- Failed.
jobs[].finishedAtjobs[].id- Job.
jobs[].kind- What it does.
jobs[].metaNeed- When
erroris something only a person can do in Meta:need(asGET /integrations/meta/attentionnames 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) andnext(what to do). Absent otherwise. jobs[].status- Status.One of
queued,running,succeeded,failed,partially_failed,cancelled jobs[].subjectId- Subject.
jobs[].subjectType- Subject type.
jobs[].succeeded- Done.
jobs[].total- Items.
jobs[].updatedAt- Last change.
jobs[].canCancel- It runs and you may cancel it (a publish needs
ads:publishand is canceled withPOST /launches/{id}/publish/cancel; anything else withPOST /jobs/{id}/cancel, which needs what its work needs as it runs: a live change what it changes (delivery:writeto pause or resume,budgets:writefor budgets, bids and dates,ads:deleteto delete), comment repliessocial:write, other work that changes what runs on an ad platformads:publish, a spending limitintegrations:writeandbudgets:write, an audit log exportexports:createand the restlaunches:write). jobs[].canRetry- It finished with failures, its kind can be retried and you may (
POST /jobs/{id}/retry). jobs[].finished- Items no longer queued or running (succeeded, failed, skipped or cancelled);
totalonce the job finished. jobs[].launchId- The launch the job is about.
jobs[].nextAt- 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[].progress- 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.adAccountName- The ad account being read, once past the account list.
jobs[].progress.adSets- Ad sets found so far.
jobs[].progress.ads- Ads found so far.
jobs[].progress.campaigns- Campaigns found so far.
jobs[].progress.stepad_accounts(reading which ad accounts and Pages the connection has), then per ad accountcampaigns,ad_setsandads.One ofad_accounts,campaigns,ad_sets,adsjobs[].startedByjobs[].startedBy.id- Person, API key or agent.
jobs[].startedBy.kind- Actor kind.One of
person,api_key,agent,system jobs[].stoppedBecause- Why the job stopped without anyone cancelling it:
account_off(its ad account was turned off in Pluto),disconnected(Meta was disconnected) orreconnect_needed(Meta's access ended). What it did before stays.One ofaccount_off,disconnected,reconnect_needed jobs[].subjectName- 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[].throughput- Running jobs only:
itemsthat finished during the lastseconds(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.items- Finished items.
jobs[].throughput.seconds- Window length.
jobs[].units- What people count, when it isn't the items: a
publish_launchjob's ads (total, anddone: no longer queued or running). jobs[].units.done- Done.
jobs[].units.total- In the job.
curl "$PLUTO_API/jobs" \
-H "Authorization: Bearer $PLUTO_KEY"Get a job
A job's status and counts.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The job'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
createdAt- Accepted at.
error- Job-level error.
errorCode- A registered
error's stable code (such asmeta_no_answer), for an app to say it in its language; absent for an error without one.errorreads the same either way. errorParams- The values
errorCode's sentence names, present exactly whenerrorCodeis. failed- Failed.
finishedAtid- Job.
kind- What it does.
metaNeed- When
erroris something only a person can do in Meta:need(asGET /integrations/meta/attentionnames 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) andnext(what to do). Absent otherwise. status- Status.One of
queued,running,succeeded,failed,partially_failed,cancelled subjectId- Subject.
subjectType- Subject type.
succeeded- Done.
total- Items.
updatedAt- 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-Afterseconds. 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"Cancel queued items
Completed provider effects are not undone.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The job's ID. |
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. |
Response
createdAt- Accepted at.
error- Job-level error.
errorCode- A registered
error's stable code (such asmeta_no_answer), for an app to say it in its language; absent for an error without one.errorreads the same either way. errorParams- The values
errorCode's sentence names, present exactly whenerrorCodeis. failed- Failed.
finishedAtid- Job.
kind- What it does.
metaNeed- When
erroris something only a person can do in Meta:need(asGET /integrations/meta/attentionnames 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) andnext(what to do). Absent otherwise. status- Status.One of
queued,running,succeeded,failed,partially_failed,cancelled subjectId- Subject.
subjectType- Subject type.
succeeded- Done.
total- Items.
updatedAt- 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 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/jobs/8a2c8b96-7441-44d5-a00a-a07d58300b3b/cancel" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 09b6aa10-d0fe-4886-879a-0b794ef79d45"List a job's items
Per-item outcomes.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The job's ID. |
status | string | Optional | queued, running, succeeded, failed, skipped or cancelled. |
after | string | Optional | Cursor (position). |
limit | string | Optional | Page size. |
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- This page.
items[].attempts- Attempts so far.
items[].error- Why it failed; while queued again, what it waits for (a retry's reason, or Meta still processing a video).
items[].key- Stable item key.
items[].metaNeed- When
erroris something only a person can do in Meta:need(asGET /integrations/meta/attentionnames 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) andnext(what to do). Absent otherwise. items[].output- Result, once the item succeeded (
publish_launchmedia:{imageHash}, or{videoId, thumbnailHash}/{videoId, thumbnailUrl}for a video). items[].position- Order; the paging cursor.
items[].providerId- ID at the provider once created.
items[].stage- The stage it runs in; a stage starts when every earlier one is done. Its meaning is the job kind's:
publish_launch0 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_revisions0 campaign, 1 ad sets, 2 ads, 3 budget changes held for Meta's hourly limit;delete_at_meta0 ads, 1 ad sets. items[].status- Item status.
items[].updatedAt- Last change.
nextAfter- 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-Afterseconds. 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"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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The job's ID. |
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. |
Response
createdAt- Accepted at.
error- Job-level error.
errorCode- A registered
error's stable code (such asmeta_no_answer), for an app to say it in its language; absent for an error without one.errorreads the same either way. errorParams- The values
errorCode's sentence names, present exactly whenerrorCodeis. failed- Failed.
finishedAtid- Job.
kind- What it does.
metaNeed- When
erroris something only a person can do in Meta:need(asGET /integrations/meta/attentionnames 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) andnext(what to do). Absent otherwise. status- Status.One of
queued,running,succeeded,failed,partially_failed,cancelled subjectId- Subject.
subjectType- Subject type.
succeeded- Done.
total- Items.
updatedAt- Last change.
retried- 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;
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/jobs/8a2c8b96-7441-44d5-a00a-a07d58300b3b/retry" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: 67080912-4e35-430d-b9b8-3e5ba17a27a9"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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The job'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
jobId- The job.
stages- By stage, then kind (null last).
stages[].cancelled- Canceled.
stages[].failed- Failed.
stages[].kind- What the item keys name before their colon (
media,ad_set,creative,ad…); null for keys without one. stages[].queued- Waiting to run.
stages[].running- Running now.
stages[].skipped- Skipped.
stages[].stage- The stage, as
GET /jobs/{id}/itemsnumbers it. stages[].succeeded- Succeeded.
stages[].total- 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-Afterseconds. 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 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.
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
bom- The file starts with a UTF-8 byte order mark, so a spreadsheet reads accented and non-Latin letters correctly.
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 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.
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.
filters- What it applies, as checked.
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). kind- What it holds: the audit log, a workspace's launches, ad sets and ads, or usage events.One of
audit_log,workspace,usage organizationId- The organization it's of; null for a workspace's audit log.
rowsTotal- The rows it holds, once counted (null before); the file's own count once it's written.
rowsWritten- The rows in the file so far.
statusdone: the file is written and can be downloaded untilexpiresAt.One ofqueued,running,done,failedworkspaceId- 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-Afterseconds. 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"