API reference

Launch groups

Launches, ad sets and ads with override-only inheritance.

GET/launch-groups

List launch groups

Launch groups, the most recently changed first (a change to any of their campaigns counts). A launch group holds a launch's campaigns: one per platform, ad account, or objective or budget setup, each a launch of its own (children), with a status across them. Most launches have one. Guests see the groups with a campaign shared with them, and only those campaigns. Keyset-paged: pass nextAfter as after.

Permission: readGuests too

Parameters

NameTypeRequiredDescription
qquerystringOptionalPart of the name or description.
archivedquerystringOptionaltrue lists archived launch groups instead.
multiPlatformquerystringOptionaltrue: only those with two or more campaigns.
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
This page.
items[].archivedAtstring (date-time) or null
Archived (every campaign is).
items[].campaignCountintegerRequired
Listed campaigns.
items[].canDeletebooleanRequired
Deleting is allowed: every campaign of it (archived ones too) is a draft never published. Anything else is archived.
items[].childrenarray of objectsRequired
Its campaigns in the order they were added: the active ones (the archived ones of an archived group), on platforms the workspace may use.
items[].children[].adAccountIdstring or null
Its ad account.
items[].children[].adAccountNamestring or null
The ad account's name, as synced.
items[].children[].adCountintegerRequired
Ads.
items[].children[].adSetCountintegerRequired
Ad sets.
items[].children[].archivedAtstring (date-time) or null
Archived.
items[].children[].campaignIdstring or null
The existing campaign it publishes into.
items[].children[].canDeletebooleanRequired
Deleting is allowed: a draft never published, nothing of it at its platform. Anything else is archived.
items[].children[].createdAtstring (date-time)Required
Created.
items[].children[].currencystring or null
The ad account's currency (ISO 4217).
items[].children[].groupIdstring (uuid)Required
Its launch group.
items[].children[].idstring (uuid)Required
The campaign (a launch ID).
items[].children[].labelstringRequired
Its own name in the launch group: a person's, else the launch group's name, with no suffix.
items[].children[].namestringRequired
Its full name (what its campaign at the platform is named after).
items[].children[].newCampaignNamestring or null
The new campaign's name.
items[].children[].platformstringRequired
Its platform.
items[].children[].publishedAtstring (date-time) or null
First published.
items[].children[].scheduleAtstring (date-time) or null
Start.
items[].children[].sharedWithGuestsboolean
Shared with guests for review.
items[].children[].statusstringRequired
Status.One of draft, publishing, published, failed
items[].children[].updatedAtstring (date-time)Required
Last change.
items[].children[].versionintegerRequired
Version.
items[].createdAtstring (date-time)Required
Created.
items[].descriptionstringRequired
Description.
items[].idstring (uuid)Required
The launch group.
items[].namestringRequired
Its own name.
items[].ownerIdstring (uuid) or null
The member who owns it.
items[].publishedCountintegerRequired
Listed campaigns that published.
items[].statusstring or null
Across its listed campaigns: any publishing, else any failed, else all published, else some, else draft.One of draft, publishing, published, some_published, failed
items[].updatedAtstring (date-time)Required
Last change to the group itself.
items[].versionintegerRequired
Increments on every change; send as expectedVersion.
nextAfterstring or nullRequired
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.
  • 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/launch-groups" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/launch-groups

Create a launch group

A launch with one empty campaign per entry in children (default: one where POST /launches would start it; a 422 names the choice when there is one). A campaign is for another platform, ad account, or objective or budget setup; versions by audience, country, placement or creative are ad sets in one campaign. Each campaign's full name follows the naming rule: the launch's name while it has one campaign, "{name} {label}" with two or more.

Permission: writeCommand: 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

childrenarray of objects
One campaign each.
children[].adAccountIdstring
The ad account there.
children[].labelstring
Its own name in the launch (default: its platform's name when it's the launch's only campaign there, else its objective's, ad account's or both).
children[].platformstringRequired
A platform from GET /platforms; a platform this workspace can't use is refused like an unknown one (422).
descriptionstring
Description (up to 10,000 characters).
namestring
Name (1-120 characters).
ownerIdstring (uuid)
A workspace member who owns it.

Response201 Created

archivedAtstring (date-time) or null
Archived (every campaign is).
campaignCountintegerRequired
Listed campaigns.
canDeletebooleanRequired
Deleting is allowed: every campaign of it (archived ones too) is a draft never published. Anything else is archived.
childrenarray of objectsRequired
Its campaigns in the order they were added: the active ones (the archived ones of an archived group), on platforms the workspace may use.
children[].adAccountIdstring or null
Its ad account.
children[].adAccountNamestring or null
The ad account's name, as synced.
children[].adCountintegerRequired
Ads.
children[].adSetCountintegerRequired
Ad sets.
children[].archivedAtstring (date-time) or null
Archived.
children[].campaignIdstring or null
The existing campaign it publishes into.
children[].canDeletebooleanRequired
Deleting is allowed: a draft never published, nothing of it at its platform. Anything else is archived.
children[].createdAtstring (date-time)Required
Created.
children[].currencystring or null
The ad account's currency (ISO 4217).
children[].groupIdstring (uuid)Required
Its launch group.
children[].idstring (uuid)Required
The campaign (a launch ID).
children[].labelstringRequired
Its own name in the launch group: a person's, else the launch group's name, with no suffix.
children[].namestringRequired
Its full name (what its campaign at the platform is named after).
children[].newCampaignNamestring or null
The new campaign's name.
children[].platformstringRequired
Its platform.
children[].publishedAtstring (date-time) or null
First published.
children[].scheduleAtstring (date-time) or null
Start.
children[].sharedWithGuestsboolean
Shared with guests for review.
children[].statusstringRequired
Status.One of draft, publishing, published, failed
children[].updatedAtstring (date-time)Required
Last change.
children[].versionintegerRequired
Version.
createdAtstring (date-time)Required
Created.
descriptionstringRequired
Description.
idstring (uuid)Required
The launch group.
namestringRequired
Its own name.
ownerIdstring (uuid) or null
The member who owns it.
publishedCountintegerRequired
Listed campaigns that published.
statusstring or null
Across its listed campaigns: any publishing, else any failed, else all published, else some, else draft.One of draft, publishing, published, some_published, failed
updatedAtstring (date-time)Required
Last change to the group itself.
versionintegerRequired
Increments on every change; send as expectedVersion.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 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/launch-groups" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 61932ea8-ef9a-425a-b4bd-f47f5803997e" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {
        "adAccountId": "act_741877585619437",
        "label": "Vitamin C Serum, UGC 9x16",
        "platform": "422"
      }
    ],
    "description": "Two drops every morning for brighter, even skin.",
    "name": "Vitamin C Serum, UGC 9x16",
    "ownerId": "c7f25ce0-b477-48fc-9b7b-155702ae0ec2"
  }'
GET/launch-groups/{id}

Get a launch group

The launch group with its campaigns (each a launch: GET /launches/{id} has its ad sets and ads).

Permission: readGuests too

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch group'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

archivedAtstring (date-time) or null
Archived (every campaign is).
campaignCountintegerRequired
Listed campaigns.
canDeletebooleanRequired
Deleting is allowed: every campaign of it (archived ones too) is a draft never published. Anything else is archived.
childrenarray of objectsRequired
Its campaigns in the order they were added: the active ones (the archived ones of an archived group), on platforms the workspace may use.
children[].adAccountIdstring or null
Its ad account.
children[].adAccountNamestring or null
The ad account's name, as synced.
children[].adCountintegerRequired
Ads.
children[].adSetCountintegerRequired
Ad sets.
children[].archivedAtstring (date-time) or null
Archived.
children[].campaignIdstring or null
The existing campaign it publishes into.
children[].canDeletebooleanRequired
Deleting is allowed: a draft never published, nothing of it at its platform. Anything else is archived.
children[].createdAtstring (date-time)Required
Created.
children[].currencystring or null
The ad account's currency (ISO 4217).
children[].groupIdstring (uuid)Required
Its launch group.
children[].idstring (uuid)Required
The campaign (a launch ID).
children[].labelstringRequired
Its own name in the launch group: a person's, else the launch group's name, with no suffix.
children[].namestringRequired
Its full name (what its campaign at the platform is named after).
children[].newCampaignNamestring or null
The new campaign's name.
children[].platformstringRequired
Its platform.
children[].publishedAtstring (date-time) or null
First published.
children[].scheduleAtstring (date-time) or null
Start.
children[].sharedWithGuestsboolean
Shared with guests for review.
children[].statusstringRequired
Status.One of draft, publishing, published, failed
children[].updatedAtstring (date-time)Required
Last change.
children[].versionintegerRequired
Version.
createdAtstring (date-time)Required
Created.
descriptionstringRequired
Description.
idstring (uuid)Required
The launch group.
namestringRequired
Its own name.
ownerIdstring (uuid) or null
The member who owns it.
publishedCountintegerRequired
Listed campaigns that published.
statusstring or null
Across its listed campaigns: any publishing, else any failed, else all published, else some, else draft.One of draft, publishing, published, some_published, failed
updatedAtstring (date-time)Required
Last change to the group itself.
versionintegerRequired
Increments on every change; send as expectedVersion.

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/launch-groups/8f3e8466-e14a-4118-89d5-c2ff4f3d21d9" \
  -H "Authorization: Bearer $PLUTO_KEY"
PATCH/launch-groups/{id}

Update a launch group

Its own name, description or owner. The campaigns keep their labels; the full names of drafts that never published and still follow the naming rule follow the new name (a published campaign is never renamed by itself).

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch group'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.

Request body

descriptionstring
Description.
expectedVersioninteger
The version you edited; without it the change applies over any other.
namestring
Name.
ownerIdstring (uuid) or null
A workspace member who owns it; null for nobody.

Response200 OK

archivedAtstring (date-time) or null
Archived (every campaign is).
campaignCountintegerRequired
Listed campaigns.
canDeletebooleanRequired
Deleting is allowed: every campaign of it (archived ones too) is a draft never published. Anything else is archived.
childrenarray of objectsRequired
Its campaigns in the order they were added: the active ones (the archived ones of an archived group), on platforms the workspace may use.
children[].adAccountIdstring or null
Its ad account.
children[].adAccountNamestring or null
The ad account's name, as synced.
children[].adCountintegerRequired
Ads.
children[].adSetCountintegerRequired
Ad sets.
children[].archivedAtstring (date-time) or null
Archived.
children[].campaignIdstring or null
The existing campaign it publishes into.
children[].canDeletebooleanRequired
Deleting is allowed: a draft never published, nothing of it at its platform. Anything else is archived.
children[].createdAtstring (date-time)Required
Created.
children[].currencystring or null
The ad account's currency (ISO 4217).
children[].groupIdstring (uuid)Required
Its launch group.
children[].idstring (uuid)Required
The campaign (a launch ID).
children[].labelstringRequired
Its own name in the launch group: a person's, else the launch group's name, with no suffix.
children[].namestringRequired
Its full name (what its campaign at the platform is named after).
children[].newCampaignNamestring or null
The new campaign's name.
children[].platformstringRequired
Its platform.
children[].publishedAtstring (date-time) or null
First published.
children[].scheduleAtstring (date-time) or null
Start.
children[].sharedWithGuestsboolean
Shared with guests for review.
children[].statusstringRequired
Status.One of draft, publishing, published, failed
children[].updatedAtstring (date-time)Required
Last change.
children[].versionintegerRequired
Version.
createdAtstring (date-time)Required
Created.
descriptionstringRequired
Description.
idstring (uuid)Required
The launch group.
namestringRequired
Its own name.
ownerIdstring (uuid) or null
The member who owns it.
publishedCountintegerRequired
Listed campaigns that published.
statusstring or null
Across its listed campaigns: any publishing, else any failed, else all published, else some, else draft.One of draft, publishing, published, some_published, failed
updatedAtstring (date-time)Required
Last change to the group itself.
versionintegerRequired
Increments on every change; send as expectedVersion.

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 PATCH "$PLUTO_API/launch-groups/8f3e8466-e14a-4118-89d5-c2ff4f3d21d9" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: a4ecca55-d44b-44b6-b3e0-abd7d291973e" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Two drops every morning for brighter, even skin.",
    "expectedVersion": 3,
    "name": "Vitamin C Serum, UGC 9x16",
    "ownerId": "c7f25ce0-b477-48fc-9b7b-155702ae0ec2"
  }'
DELETE/launch-groups/{id}

Delete a launch group

Deletes the launch group and its campaigns when every campaign is a draft that never created anything at a provider; otherwise 409 (archive it instead).

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch group'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

deletedbooleanRequired
Deleted.
idstring (uuid)Required
The launch group.
launchIdsarray of strings (uuid)Required
The campaigns deleted with it.

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 DELETE "$PLUTO_API/launch-groups/8f3e8466-e14a-4118-89d5-c2ff4f3d21d9" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 2a604c78-a89e-4e75-b66d-d940a6a8586e"
POST/launch-groups/{id}/archive

Archive or restore a launch group

Archives every active campaign of the launch group and so the group; archived: false restores the group with every campaign of it, also ones archived on their own before.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch group'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.

Request body

archivedboolean
false restores.

Response200 OK

archivedAtstring (date-time) or null
Archived (every campaign is).
campaignCountintegerRequired
Listed campaigns.
canDeletebooleanRequired
Deleting is allowed: every campaign of it (archived ones too) is a draft never published. Anything else is archived.
childrenarray of objectsRequired
Its campaigns in the order they were added: the active ones (the archived ones of an archived group), on platforms the workspace may use.
children[].adAccountIdstring or null
Its ad account.
children[].adAccountNamestring or null
The ad account's name, as synced.
children[].adCountintegerRequired
Ads.
children[].adSetCountintegerRequired
Ad sets.
children[].archivedAtstring (date-time) or null
Archived.
children[].campaignIdstring or null
The existing campaign it publishes into.
children[].canDeletebooleanRequired
Deleting is allowed: a draft never published, nothing of it at its platform. Anything else is archived.
children[].createdAtstring (date-time)Required
Created.
children[].currencystring or null
The ad account's currency (ISO 4217).
children[].groupIdstring (uuid)Required
Its launch group.
children[].idstring (uuid)Required
The campaign (a launch ID).
children[].labelstringRequired
Its own name in the launch group: a person's, else the launch group's name, with no suffix.
children[].namestringRequired
Its full name (what its campaign at the platform is named after).
children[].newCampaignNamestring or null
The new campaign's name.
children[].platformstringRequired
Its platform.
children[].publishedAtstring (date-time) or null
First published.
children[].scheduleAtstring (date-time) or null
Start.
children[].sharedWithGuestsboolean
Shared with guests for review.
children[].statusstringRequired
Status.One of draft, publishing, published, failed
children[].updatedAtstring (date-time)Required
Last change.
children[].versionintegerRequired
Version.
createdAtstring (date-time)Required
Created.
descriptionstringRequired
Description.
idstring (uuid)Required
The launch group.
namestringRequired
Its own name.
ownerIdstring (uuid) or null
The member who owns it.
publishedCountintegerRequired
Listed campaigns that published.
statusstring or null
Across its listed campaigns: any publishing, else any failed, else all published, else some, else draft.One of draft, publishing, published, some_published, failed
updatedAtstring (date-time)Required
Last change to the group itself.
versionintegerRequired
Increments on every change; send as expectedVersion.

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/launch-groups/8f3e8466-e14a-4118-89d5-c2ff4f3d21d9/archive" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 6880d7f3-4828-47b1-a0d1-008bed538833" \
  -H "Content-Type: application/json" \
  -d '{
    "archived": false
  }'
POST/launch-groups/{id}/campaigns

Add a campaign

Adds a campaign (another platform, ad account, or objective or budget setup): empty, or with from a copy of one of its campaigns in that platform's own fields (what carries over, what that platform's defaults fill in and what's left out); on the source's own platform everything carries over and a new ad account brings its Page, pixel and audiences from its defaults. adAccountId is required unless the platform has exactly one active ad account in the workspace (then that one is used) or from is on the same platform (then the source's); otherwise 422 on adAccountId. Copied ads are linked to their originals (GET /ads/{id}/linked). dryRun: true with from answers the plan without adding (200). Answers the new campaign (a launch).

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch group'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.

Request body

adAccountIdstring
The ad account there. Required unless the platform has only one.
dryRunboolean
With from: the plan, without adding.
fromstring (uuid)
One of its campaigns (a launch ID) to copy; absent starts empty.
labelstring
Its own name in the launch.
platformstringRequired
A platform from GET /platforms; a platform this workspace can't use is refused like an unknown one (422).

Response200 OK

codestringRequired
Stable code.One of bad_request, unauthenticated, forbidden, not_found, conflict, invalid, rate_limited, unavailable, internal
currentobject
The current entity, on a stale expectedVersion (409).
errorsarray of objects
Every field problem (422).
errors[].codestring
A registered reason's stable code (such as ad_account_not_in_meta), so an app can say message in its own words; absent for a reason without one.
errors[].fieldstringRequired
JSON-pointer-like path.
errors[].messagestringRequired
Problem.
errors[].paramsobject
The values code's sentence names (maybe none), present exactly when code is.
requestIdstring
The request's ID, as in the x-request-id header. Include it when you report a problem.
statusintegerRequired
HTTP status.
titlestringRequired
What went wrong, for the person or agent reading it.
titleCodestring
A registered title's stable code (such as not_found_the_launch), for an app to say the title in its language; absent for a title without one. title reads the same either way.
titleParamsobject
The values titleCode's sentence names, present exactly when titleCode is.
traceIdstring
The request's trace ID, as in the x-trace-id header.
typestringRequired
Documentation URL for code.

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/launch-groups/8f3e8466-e14a-4118-89d5-c2ff4f3d21d9/campaigns" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 56975e5e-5015-447b-b96b-a0ddd559a535" \
  -H "Content-Type: application/json" \
  -d '{
    "adAccountId": "act_741877585619437",
    "dryRun": false,
    "from": "b0d53bab-77e5-487e-9baa-1f16677ab4a3",
    "label": "Vitamin C Serum, UGC 9x16",
    "platform": "422"
  }'
POST/launch-groups/{id}/duplicate

Duplicate a launch group

A new launch group with the same description and owner, and a draft copy of each active campaign (its ad sets, ads and settings, on the same platform and ad account); each keeps the name a person gave it, else reads the new launch's. Archived campaigns stay behind. Every copy creates its own campaign when it publishes. Without name, "<name> copy". 409 when the launch group has no active campaign.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch group'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.

Request body

namestring
The new launch group's name (default: "<name> copy").

Response201 Created

archivedAtstring (date-time) or null
Archived (every campaign is).
campaignCountintegerRequired
Listed campaigns.
canDeletebooleanRequired
Deleting is allowed: every campaign of it (archived ones too) is a draft never published. Anything else is archived.
childrenarray of objectsRequired
Its campaigns in the order they were added: the active ones (the archived ones of an archived group), on platforms the workspace may use.
children[].adAccountIdstring or null
Its ad account.
children[].adAccountNamestring or null
The ad account's name, as synced.
children[].adCountintegerRequired
Ads.
children[].adSetCountintegerRequired
Ad sets.
children[].archivedAtstring (date-time) or null
Archived.
children[].campaignIdstring or null
The existing campaign it publishes into.
children[].canDeletebooleanRequired
Deleting is allowed: a draft never published, nothing of it at its platform. Anything else is archived.
children[].createdAtstring (date-time)Required
Created.
children[].currencystring or null
The ad account's currency (ISO 4217).
children[].groupIdstring (uuid)Required
Its launch group.
children[].idstring (uuid)Required
The campaign (a launch ID).
children[].labelstringRequired
Its own name in the launch group: a person's, else the launch group's name, with no suffix.
children[].namestringRequired
Its full name (what its campaign at the platform is named after).
children[].newCampaignNamestring or null
The new campaign's name.
children[].platformstringRequired
Its platform.
children[].publishedAtstring (date-time) or null
First published.
children[].scheduleAtstring (date-time) or null
Start.
children[].sharedWithGuestsboolean
Shared with guests for review.
children[].statusstringRequired
Status.One of draft, publishing, published, failed
children[].updatedAtstring (date-time)Required
Last change.
children[].versionintegerRequired
Version.
createdAtstring (date-time)Required
Created.
descriptionstringRequired
Description.
idstring (uuid)Required
The launch group.
namestringRequired
Its own name.
ownerIdstring (uuid) or null
The member who owns it.
publishedCountintegerRequired
Listed campaigns that published.
statusstring or null
Across its listed campaigns: any publishing, else any failed, else all published, else some, else draft.One of draft, publishing, published, some_published, failed
updatedAtstring (date-time)Required
Last change to the group itself.
versionintegerRequired
Increments on every change; send as expectedVersion.

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/launch-groups/8f3e8466-e14a-4118-89d5-c2ff4f3d21d9/duplicate" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: d064e1d0-80c0-4734-9458-c5ccf6a4c790" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Vitamin C Serum, UGC 9x16"
  }'
GET/launch-groups/{id}/results

Compare across campaigns

Per linked creative (an unlinked ad is its own row), each published campaign's numbers from its platform's own insights over the period: spend, impressions, clicks, CTR and results in that platform's attribution and day basis (campaigns[].attribution, dayBasis). Campaigns are grouped by platform, then ad account. Numbers from different platforms are never added up, nor amounts in different currencies; subtotals per platform and currency are given only when exact in the currency's minor units (spend: null otherwise), counts as integers, never ratios.

Permission: read

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe launch group's ID.
sincequerystringOptionalFirst day (YYYY-MM-DD), in each ad account's days.
untilquerystringOptionalLast day.
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

campaignsarray of objectsRequired
Grouped by platform, then ad account.
campaigns[].adAccountIdstring or null
Its ad account.
campaigns[].adAccountNamestring or null
The account's name.
campaigns[].attributionstring or null
How its platform attributes results.
campaigns[].currencystring or null
The account's currency.
campaigns[].dayBasisstring or null
account (the ad account's time zone) or utc.
campaigns[].labelstringRequired
Its name in the launch group.
campaigns[].launchIdstring (uuid)Required
The campaign (a launch).
campaigns[].platformstringRequired
Its platform.
campaigns[].publishedbooleanRequired
It published; only published campaigns have numbers.
creativesarray of objectsRequired
The creatives.
creatives[].cellsarray of objectsRequired
One per ad, never added up across platforms.
creatives[].cells[].adIdstring (uuid)Required
Ad.
creatives[].cells[].currencystringRequired
Its amounts' currency.
creatives[].cells[].launchIdstring (uuid)Required
Campaign.
creatives[].cells[].metricsobjectRequired
Its platform's metrics: decimal strings for money, absent when the platform reported nothing.
creatives[].cells[].platformstringRequired
Platform.
creatives[].creativeLinkIdstring (uuid) or nullRequired
The link its ads share; null for an unlinked ad.
creatives[].mediaIdstring (uuid) or null
The first ad's file.
creatives[].namestringRequired
The first ad's name.
periodobjectRequired
period.sincestringRequired
First day.
period.untilstringRequired
Last day.
subtotalsarray of objectsRequired
Per platform and currency.
subtotals[].clicksinteger
Clicks.
subtotals[].currencystringRequired
Currency.
subtotals[].impressionsinteger
Impressions.
subtotals[].platformstringRequired
Platform.
subtotals[].spendstring or nullRequired
Exact in the currency's minor units, else null.

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/launch-groups/8f3e8466-e14a-4118-89d5-c2ff4f3d21d9/results" \
  -H "Authorization: Bearer $PLUTO_KEY"