Swap creatives
Replace the creatives on an existing ad set's ads while PRESERVING each ad's copy (primary text + headline).
Tool name: swap-creatives.
Replace the creatives on an existing ad set's ads while PRESERVING each ad's copy (primary text + headline). For each creative it edits an existing ad's creative in place (copy untouched); if there are more creatives than ads it clones an existing ad (inheriting its copy) and sets the new creative; if fewer, it removes the surplus. NEVER delete-and-re-add ads to change a creative, that drops the copy. Use this for "swap in these creatives" / "use these N videos on this ad set". Pass the Koast adset nodeId and the numeric creativeIds.
When to use
Change which creatives an ad set runs while keeping the existing copy. The copy-preserving creative swap, never delete + re-add ads to swap a creative. Equal count edits in place; overflow clones an ad (carries copy); underflow trims the surplus.
Access
| Property | Value |
|---|---|
| Required scope | write |
| Publishes | No |
| Read-only | No |
| Destructive | Yes |
| Idempotent | No |
| Open world | No |
Input
| Field | Type | Required | Description |
|---|---|---|---|
campaignLaunchId | string | Yes | Campaign launch ID (a.k.a. batch ID). Read it from the Current Context block when one is in scope, or resolve it from a mention via listAccountCampaigns / the campaign tree when the user @-mentioned a different launch. |
adsetNodeId | string | Yes | Koast adset node id whose ads should carry the new creatives. |
creativeIds | number[] | Yes | Numeric creative IDs to place on the ad set, in order. Copy on existing ads is preserved. At least 1 item, at most 100 items. |
Output
| Field | Type | Required | Description |
|---|---|---|---|
adsetId | string | Yes | Koast adset node id the creatives were placed on. |
ads | object[] | Yes | The ads the ad set carries after the swap, each with the creative it now runs. |
removedAdIds | string[] | Yes | Ids of surplus ads deleted from the Koast tree because fewer creatives were supplied than the ad set had ads. Empty when none were deleted. |
validation | object | No |
REST equivalent
POST /v1/brands/{brandId}/launches/{launchId}/ad-sets/{adsetNodeId}/creatives/swap, Swap creatives. CLI: koast swap-creatives.