Launcher launch tools

Discover exact provider assets and targets before preparing a launch. Preview reserves nothing. Submission uses one stable request key and returns work to track. Read operation results before retrying; corrected replacement inputs require a new request key. The tables list arguments and common nested fields. Expand Full input schema for all fields and allowed values. Workspace and account permissions apply to every tool.

launcher_promotion_sources_list

Find ads created by earlier tests that are available for promotion. Access: mcp:read.

Parameter	Type	Required / default	Details
`ad_account_id`	uuid	Required	Superlaunch account UUID from `ad_accounts_list`.
`limit`	integer	`50`	minimum: `1`. maximum: `100`.
`after_id`	uuid or null	`null`	Pagination cursor from the preceding result.

Full input schema

{
  "additionalProperties": false,
  "properties": {
    "ad_account_id": {
      "format": "uuid",
      "type": "string"
    },
    "limit": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    },
    "after_id": {
      "anyOf": [
        {
          "format": "uuid",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "ad_account_id"
  ],
  "type": "object"
}

launcher_assets_list

Find Meta Pages, Instagram accounts, pixels, audiences, and other assets by name. Pages, apps, pixels, and audiences use the selected ad account. Forms, Instagram accounts, and catalogs require a Page ID in parent_id. Product sets require a catalog ID in parent_id plus a page_id. Pages and Instagram accounts use imported data; check sync_status and synced_at. Other asset types use live Meta reads. Follow next_cursor for more results. Launch validation checks whether the selected assets can be used. Access: mcp:read.

Parameter	Type	Required / default	Details
`ad_account_id`	uuid	Required	Superlaunch account UUID from `ad_accounts_list`.
`kind`	pages, instagram_accounts, pixels, applications, lead_forms, product_catalogs, product_sets, custom_audiences	Required	Supported discovery edges, never arbitrary Graph paths.
`parent_id`	string or null	`null`
`page_id`	string or null	`null`
`limit`	integer	`50`	minimum: `1`. maximum: `100`.
`cursor`	string or null	`null`

Full input schema

{
  "$defs": {
    "AssetKind": {
      "description": "Supported discovery edges, never arbitrary Graph paths.",
      "enum": [
        "pages",
        "instagram_accounts",
        "pixels",
        "applications",
        "lead_forms",
        "product_catalogs",
        "product_sets",
        "custom_audiences"
      ],
      "type": "string"
    }
  },
  "additionalProperties": false,
  "properties": {
    "ad_account_id": {
      "format": "uuid",
      "type": "string"
    },
    "kind": {
      "$ref": "#/$defs/AssetKind"
    },
    "parent_id": {
      "anyOf": [
        {
          "pattern": "^[0-9]{1,32}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "type": [
        "string",
        "null"
      ]
    },
    "page_id": {
      "anyOf": [
        {
          "pattern": "^[0-9]{1,32}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "type": [
        "string",
        "null"
      ]
    },
    "limit": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    },
    "cursor": {
      "anyOf": [
        {
          "maxLength": 4096,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "ad_account_id",
    "kind"
  ],
  "type": "object"
}

launcher_targets_list

List current ad sets for the account. Read the chosen target before previewing a launch. Access: mcp:read.

Parameter	Type	Required / default	Details
`ad_account_id`	uuid	Required	Superlaunch account UUID from `ad_accounts_list`.
`limit`	integer	`50`	minimum: `1`. maximum: `100`.
`cursor`	string or null	`null`

Full input schema

{
  "additionalProperties": false,
  "properties": {
    "ad_account_id": {
      "format": "uuid",
      "type": "string"
    },
    "limit": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    },
    "cursor": {
      "anyOf": [
        {
          "maxLength": 4096,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "ad_account_id"
  ],
  "type": "object"
}

launcher_targets_get

Read an ad set’s account, parent campaign, current settings, and validation fingerprint. Access: mcp:read.

Parameter	Type	Required / default	Details
`ad_account_id`	uuid	Required	Superlaunch account UUID from `ad_accounts_list`.
`adset_id`	string	Required	pattern: `^[0-9]{1,32}$`.
`campaign_id`	string or null	`null`

Full input schema

{
  "additionalProperties": false,
  "properties": {
    "ad_account_id": {
      "format": "uuid",
      "type": "string"
    },
    "adset_id": {
      "pattern": "^[0-9]{1,32}$",
      "type": "string"
    },
    "campaign_id": {
      "anyOf": [
        {
          "pattern": "^[0-9]{1,32}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "ad_account_id",
    "adset_id"
  ],
  "type": "object"
}

launcher_launches_preview

Check approved content, planned Meta objects, and estimated usage. A preview does not reserve capacity. Access: mcp:read.

Parameter	Type	Required / default	Details
`request`	object	Required	Launch inputs, including the account, content selection, template, and timing.

request fields

Parameter	Type	Required / default	Details
`schema_version`	1	`1`	Input format version.
`name`	string	`"Launch"`	minLength: `1`. maxLength: `200`.
`request_key`	string	Required	minLength: `1`. maxLength: `200`.
`ad_account_id`	uuid	Required	Superlaunch account UUID from `ad_accounts_list`.
`operation`	test, promote, refresh	Required	Launch type: test, promote, or refresh.
`purpose`	test, scale	Required	Purpose recorded for the launch.
`template_version_id`	uuid	Required	Exact saved template version to use.
`selection`	object	Required	Direct or pinned collection selection with explicit exclusions.
`repeat_across_groups`	boolean	`false`
`manual_groups`	array of object	`[]`	maxItems: `100`.
`requested_status`	PAUSED, ACTIVE	`"PAUSED"`	Requested provider status, distinct from actual delivery.
`scheduled_at`	date-time or null	`null`	Launch date and time, including the UTC offset.
`source_launch_item_ids`	array of uuid	`[]`	Earlier launch items selected for promotion.
`target`	object or null	`null`
`retest_reason`	string or null	`null`	Reason for testing previously used content again.
`replacement`	object or null	`null`	Failed-item replacement details from the replacement-candidates tool.

Full input schema

{
  "$defs": {
    "BudgetConfig": {
      "additionalProperties": false,
      "description": "One budget owner and period using integer currency minor units.",
      "properties": {
        "schema_version": {
          "const": 1,
          "default": 1,
          "type": "integer"
        },
        "owner": {
          "enum": [
            "campaign",
            "adset"
          ],
          "type": "string"
        },
        "period": {
          "enum": [
            "daily",
            "lifetime"
          ],
          "type": "string"
        },
        "amount_minor": {
          "exclusiveMinimum": 0,
          "maximum": 9223372036854775807,
          "type": "integer"
        },
        "currency": {
          "pattern": "^[A-Z]{3}$",
          "type": "string"
        }
      },
      "required": [
        "owner",
        "period",
        "amount_minor",
        "currency"
      ],
      "type": "object"
    },
    "ExistingTargetSpec": {
      "additionalProperties": false,
      "description": "Exact provider target chosen from fresh account reads.",
      "properties": {
        "schema_version": {
          "const": 1,
          "default": 1,
          "type": "integer"
        },
        "campaign_id": {
          "maxLength": 100,
          "minLength": 1,
          "type": "string"
        },
        "adset_id": {
          "maxLength": 100,
          "minLength": 1,
          "type": "string"
        },
        "settings_fingerprint": {
          "pattern": "^[0-9a-f]{64}$",
          "type": "string"
        }
      },
      "required": [
        "campaign_id",
        "adset_id",
        "settings_fingerprint"
      ],
      "type": "object"
    },
    "FilterCondition": {
      "additionalProperties": false,
      "description": "Conditions combine with AND; their values combine with OR.",
      "properties": {
        "schema_version": {
          "const": 1,
          "default": 1,
          "type": "integer"
        },
        "field": {
          "enum": [
            "name",
            "concept",
            "language",
            "format",
            "tags",
            "source",
            "imported_at"
          ],
          "type": "string"
        },
        "operator": {
          "enum": [
            "eq",
            "contains",
            "in",
            "gte",
            "lte"
          ],
          "type": "string"
        },
        "values": {
          "items": {
            "type": "string"
          },
          "maxItems": 100,
          "minItems": 1,
          "type": "array"
        }
      },
      "required": [
        "field",
        "operator",
        "values"
      ],
      "type": "object"
    },
    "FilterSpec": {
      "additionalProperties": false,
      "description": "Versioned server filter definition.",
      "properties": {
        "schema_version": {
          "const": 1,
          "default": 1,
          "type": "integer"
        },
        "conditions": {
          "default": [],
          "items": {
            "$ref": "#/$defs/FilterCondition"
          },
          "maxItems": 30,
          "type": "array"
        }
      },
      "type": "object"
    },
    "ManualGroup": {
      "additionalProperties": false,
      "description": "One stable user-assigned group over explicit creative families.",
      "properties": {
        "schema_version": {
          "const": 1,
          "default": 1,
          "type": "integer"
        },
        "group_key": {
          "maxLength": 200,
          "minLength": 1,
          "type": "string"
        },
        "creative_ids": {
          "default": [],
          "items": {
            "format": "uuid",
            "type": "string"
          },
          "maxItems": 1000,
          "type": "array"
        },
        "targeting": {
          "anyOf": [
            {
              "$ref": "#/$defs/TargetingConfig"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "budget": {
          "anyOf": [
            {
              "$ref": "#/$defs/BudgetConfig"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "required": [
        "group_key"
      ],
      "type": "object"
    },
    "ProviderLocation": {
      "additionalProperties": false,
      "description": "Exact location-search reference with optional city radius.",
      "properties": {
        "schema_version": {
          "const": 1,
          "default": 1,
          "type": "integer"
        },
        "kind": {
          "enum": [
            "region",
            "city",
            "zip"
          ],
          "type": "string"
        },
        "key": {
          "maxLength": 100,
          "minLength": 1,
          "type": "string"
        },
        "radius": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "maximum": 1000,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "distance_unit": {
          "anyOf": [
            {
              "enum": [
                "kilometer",
                "mile"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "required": [
        "kind",
        "key"
      ],
      "type": "object"
    },
    "ReplacementItem": {
      "additionalProperties": false,
      "description": "Fence one failed assignment and the exact approved corrected version.",
      "properties": {
        "schema_version": {
          "const": 1,
          "default": 1,
          "type": "integer"
        },
        "source_item_id": {
          "format": "uuid",
          "type": "string"
        },
        "creative_version_id": {
          "format": "uuid",
          "type": "string"
        },
        "expected_ad_attempt": {
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "source_item_id",
        "creative_version_id",
        "expected_ad_attempt"
      ],
      "type": "object"
    },
    "ReplacementSpec": {
      "additionalProperties": false,
      "description": "A new request links a bounded corrected subset to retained source history.",
      "properties": {
        "schema_version": {
          "const": 1,
          "default": 1,
          "type": "integer"
        },
        "launch_id": {
          "format": "uuid",
          "type": "string"
        },
        "expected_version": {
          "minimum": 1,
          "type": "integer"
        },
        "items": {
          "items": {
            "$ref": "#/$defs/ReplacementItem"
          },
          "maxItems": 1000,
          "minItems": 1,
          "type": "array"
        }
      },
      "required": [
        "launch_id",
        "expected_version",
        "items"
      ],
      "type": "object"
    },
    "RequestedStatus": {
      "description": "Requested provider status, distinct from actual delivery.",
      "enum": [
        "PAUSED",
        "ACTIVE"
      ],
      "type": "string"
    },
    "SelectionSpec": {
      "additionalProperties": false,
      "description": "Direct or pinned collection selection with explicit exclusions.",
      "properties": {
        "schema_version": {
          "const": 1,
          "default": 1,
          "type": "integer"
        },
        "kind": {
          "enum": [
            "direct",
            "fixed",
            "smart"
          ],
          "type": "string"
        },
        "creative_ids": {
          "default": [],
          "items": {
            "format": "uuid",
            "type": "string"
          },
          "maxItems": 1000,
          "type": "array"
        },
        "excluded_ids": {
          "default": [],
          "items": {
            "format": "uuid",
            "type": "string"
          },
          "maxItems": 1000,
          "type": "array"
        },
        "collection_id": {
          "anyOf": [
            {
              "format": "uuid",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "source_lock_version": {
          "anyOf": [
            {
              "minimum": 1,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "filter_spec": {
          "anyOf": [
            {
              "$ref": "#/$defs/FilterSpec"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "required": [
        "kind"
      ],
      "type": "object"
    },
    "TargetingConfig": {
      "additionalProperties": false,
      "description": "Country and audience controls with independent exclusions.",
      "properties": {
        "schema_version": {
          "const": 1,
          "default": 1,
          "type": "integer"
        },
        "countries": {
          "default": [],
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "excluded_countries": {
          "default": [],
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "included_locations": {
          "default": [],
          "items": {
            "$ref": "#/$defs/ProviderLocation"
          },
          "maxItems": 100,
          "type": "array"
        },
        "excluded_locations": {
          "default": [],
          "items": {
            "$ref": "#/$defs/ProviderLocation"
          },
          "maxItems": 100,
          "type": "array"
        },
        "genders": {
          "default": [],
          "items": {
            "enum": [
              1,
              2
            ],
            "type": "integer"
          },
          "type": "array"
        },
        "user_os": {
          "default": [],
          "items": {
            "type": "string"
          },
          "maxItems": 10,
          "type": "array"
        },
        "user_device": {
          "default": [],
          "items": {
            "type": "string"
          },
          "maxItems": 100,
          "type": "array"
        },
        "advantage_audience": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "custom_audiences": {
          "default": [],
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "excluded_custom_audiences": {
          "default": [],
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "locales": {
          "default": [],
          "items": {
            "type": "integer"
          },
          "type": "array"
        },
        "age_min": {
          "anyOf": [
            {
              "maximum": 65,
              "minimum": 13,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "age_max": {
          "anyOf": [
            {
              "maximum": 65,
              "minimum": 13,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "audience_semantics": {
          "default": "control",
          "enum": [
            "control",
            "suggestion"
          ],
          "type": "string"
        }
      },
      "type": "object"
    },
    "WorkspaceLaunchSubmit": {
      "additionalProperties": false,
      "description": "Brandless public schema with legacy receipt parsing for exact retries.",
      "properties": {
        "schema_version": {
          "const": 1,
          "default": 1,
          "type": "integer"
        },
        "name": {
          "default": "Launch",
          "maxLength": 200,
          "minLength": 1,
          "type": "string"
        },
        "request_key": {
          "maxLength": 200,
          "minLength": 1,
          "type": "string"
        },
        "ad_account_id": {
          "format": "uuid",
          "type": "string"
        },
        "operation": {
          "enum": [
            "test",
            "promote",
            "refresh"
          ],
          "type": "string"
        },
        "purpose": {
          "enum": [
            "test",
            "scale"
          ],
          "type": "string"
        },
        "template_version_id": {
          "format": "uuid",
          "type": "string"
        },
        "selection": {
          "$ref": "#/$defs/SelectionSpec"
        },
        "repeat_across_groups": {
          "default": false,
          "type": "boolean"
        },
        "manual_groups": {
          "default": [],
          "items": {
            "$ref": "#/$defs/ManualGroup"
          },
          "maxItems": 100,
          "type": "array"
        },
        "requested_status": {
          "$ref": "#/$defs/RequestedStatus",
          "default": "PAUSED"
        },
        "scheduled_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "source_launch_item_ids": {
          "default": [],
          "items": {
            "format": "uuid",
            "type": "string"
          },
          "type": "array"
        },
        "target": {
          "anyOf": [
            {
              "$ref": "#/$defs/ExistingTargetSpec"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "retest_reason": {
          "anyOf": [
            {
              "maxLength": 2000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "replacement": {
          "anyOf": [
            {
              "$ref": "#/$defs/ReplacementSpec"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "required": [
        "request_key",
        "ad_account_id",
        "operation",
        "purpose",
        "template_version_id",
        "selection"
      ],
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "request": {
      "$ref": "#/$defs/WorkspaceLaunchSubmit",
      "type": "object"
    }
  },
  "required": [
    "request"
  ],
  "type": "object"
}

launcher_launches_submit

Submit a launch with one stable request_key, then track its result. To replace a failed item with corrected content, include the replacement details, approved creative version IDs, exact target, and a new request key. Access: mcp:read and mcp:write.

Parameter	Type	Required / default	Details
`request`	object	Required	Launch inputs, including the account, content selection, template, and timing.

request fields

Parameter	Type	Required / default	Details
`schema_version`	1	`1`	Input format version.
`name`	string	`"Launch"`	minLength: `1`. maxLength: `200`.
`request_key`	string	Required	minLength: `1`. maxLength: `200`.
`ad_account_id`	uuid	Required	Superlaunch account UUID from `ad_accounts_list`.
`operation`	test, promote, refresh	Required	Launch type: test, promote, or refresh.
`purpose`	test, scale	Required	Purpose recorded for the launch.
`template_version_id`	uuid	Required	Exact saved template version to use.
`selection`	object	Required	Direct or pinned collection selection with explicit exclusions.
`repeat_across_groups`	boolean	`false`
`manual_groups`	array of object	`[]`	maxItems: `100`.
`requested_status`	PAUSED, ACTIVE	`"PAUSED"`	Requested provider status, distinct from actual delivery.
`scheduled_at`	date-time or null	`null`	Launch date and time, including the UTC offset.
`source_launch_item_ids`	array of uuid	`[]`	Earlier launch items selected for promotion.
`target`	object or null	`null`
`retest_reason`	string or null	`null`	Reason for testing previously used content again.
`replacement`	object or null	`null`	Failed-item replacement details from the replacement-candidates tool.

Retries: reuse the same request_key with unchanged inputs for the same operation.

Full input schema

{
  "$defs": {
    "BudgetConfig": {
      "additionalProperties": false,
      "description": "One budget owner and period using integer currency minor units.",
      "properties": {
        "schema_version": {
          "const": 1,
          "default": 1,
          "type": "integer"
        },
        "owner": {
          "enum": [
            "campaign",
            "adset"
          ],
          "type": "string"
        },
        "period": {
          "enum": [
            "daily",
            "lifetime"
          ],
          "type": "string"
        },
        "amount_minor": {
          "exclusiveMinimum": 0,
          "maximum": 9223372036854775807,
          "type": "integer"
        },
        "currency": {
          "pattern": "^[A-Z]{3}$",
          "type": "string"
        }
      },
      "required": [
        "owner",
        "period",
        "amount_minor",
        "currency"
      ],
      "type": "object"
    },
    "ExistingTargetSpec": {
      "additionalProperties": false,
      "description": "Exact provider target chosen from fresh account reads.",
      "properties": {
        "schema_version": {
          "const": 1,
          "default": 1,
          "type": "integer"
        },
        "campaign_id": {
          "maxLength": 100,
          "minLength": 1,
          "type": "string"
        },
        "adset_id": {
          "maxLength": 100,
          "minLength": 1,
          "type": "string"
        },
        "settings_fingerprint": {
          "pattern": "^[0-9a-f]{64}$",
          "type": "string"
        }
      },
      "required": [
        "campaign_id",
        "adset_id",
        "settings_fingerprint"
      ],
      "type": "object"
    },
    "FilterCondition": {
      "additionalProperties": false,
      "description": "Conditions combine with AND; their values combine with OR.",
      "properties": {
        "schema_version": {
          "const": 1,
          "default": 1,
          "type": "integer"
        },
        "field": {
          "enum": [
            "name",
            "concept",
            "language",
            "format",
            "tags",
            "source",
            "imported_at"
          ],
          "type": "string"
        },
        "operator": {
          "enum": [
            "eq",
            "contains",
            "in",
            "gte",
            "lte"
          ],
          "type": "string"
        },
        "values": {
          "items": {
            "type": "string"
          },
          "maxItems": 100,
          "minItems": 1,
          "type": "array"
        }
      },
      "required": [
        "field",
        "operator",
        "values"
      ],
      "type": "object"
    },
    "FilterSpec": {
      "additionalProperties": false,
      "description": "Versioned server filter definition.",
      "properties": {
        "schema_version": {
          "const": 1,
          "default": 1,
          "type": "integer"
        },
        "conditions": {
          "default": [],
          "items": {
            "$ref": "#/$defs/FilterCondition"
          },
          "maxItems": 30,
          "type": "array"
        }
      },
      "type": "object"
    },
    "ManualGroup": {
      "additionalProperties": false,
      "description": "One stable user-assigned group over explicit creative families.",
      "properties": {
        "schema_version": {
          "const": 1,
          "default": 1,
          "type": "integer"
        },
        "group_key": {
          "maxLength": 200,
          "minLength": 1,
          "type": "string"
        },
        "creative_ids": {
          "default": [],
          "items": {
            "format": "uuid",
            "type": "string"
          },
          "maxItems": 1000,
          "type": "array"
        },
        "targeting": {
          "anyOf": [
            {
              "$ref": "#/$defs/TargetingConfig"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "budget": {
          "anyOf": [
            {
              "$ref": "#/$defs/BudgetConfig"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "required": [
        "group_key"
      ],
      "type": "object"
    },
    "ProviderLocation": {
      "additionalProperties": false,
      "description": "Exact location-search reference with optional city radius.",
      "properties": {
        "schema_version": {
          "const": 1,
          "default": 1,
          "type": "integer"
        },
        "kind": {
          "enum": [
            "region",
            "city",
            "zip"
          ],
          "type": "string"
        },
        "key": {
          "maxLength": 100,
          "minLength": 1,
          "type": "string"
        },
        "radius": {
          "anyOf": [
            {
              "exclusiveMinimum": 0,
              "maximum": 1000,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "distance_unit": {
          "anyOf": [
            {
              "enum": [
                "kilometer",
                "mile"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "required": [
        "kind",
        "key"
      ],
      "type": "object"
    },
    "ReplacementItem": {
      "additionalProperties": false,
      "description": "Fence one failed assignment and the exact approved corrected version.",
      "properties": {
        "schema_version": {
          "const": 1,
          "default": 1,
          "type": "integer"
        },
        "source_item_id": {
          "format": "uuid",
          "type": "string"
        },
        "creative_version_id": {
          "format": "uuid",
          "type": "string"
        },
        "expected_ad_attempt": {
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "source_item_id",
        "creative_version_id",
        "expected_ad_attempt"
      ],
      "type": "object"
    },
    "ReplacementSpec": {
      "additionalProperties": false,
      "description": "A new request links a bounded corrected subset to retained source history.",
      "properties": {
        "schema_version": {
          "const": 1,
          "default": 1,
          "type": "integer"
        },
        "launch_id": {
          "format": "uuid",
          "type": "string"
        },
        "expected_version": {
          "minimum": 1,
          "type": "integer"
        },
        "items": {
          "items": {
            "$ref": "#/$defs/ReplacementItem"
          },
          "maxItems": 1000,
          "minItems": 1,
          "type": "array"
        }
      },
      "required": [
        "launch_id",
        "expected_version",
        "items"
      ],
      "type": "object"
    },
    "RequestedStatus": {
      "description": "Requested provider status, distinct from actual delivery.",
      "enum": [
        "PAUSED",
        "ACTIVE"
      ],
      "type": "string"
    },
    "SelectionSpec": {
      "additionalProperties": false,
      "description": "Direct or pinned collection selection with explicit exclusions.",
      "properties": {
        "schema_version": {
          "const": 1,
          "default": 1,
          "type": "integer"
        },
        "kind": {
          "enum": [
            "direct",
            "fixed",
            "smart"
          ],
          "type": "string"
        },
        "creative_ids": {
          "default": [],
          "items": {
            "format": "uuid",
            "type": "string"
          },
          "maxItems": 1000,
          "type": "array"
        },
        "excluded_ids": {
          "default": [],
          "items": {
            "format": "uuid",
            "type": "string"
          },
          "maxItems": 1000,
          "type": "array"
        },
        "collection_id": {
          "anyOf": [
            {
              "format": "uuid",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "source_lock_version": {
          "anyOf": [
            {
              "minimum": 1,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "filter_spec": {
          "anyOf": [
            {
              "$ref": "#/$defs/FilterSpec"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "required": [
        "kind"
      ],
      "type": "object"
    },
    "TargetingConfig": {
      "additionalProperties": false,
      "description": "Country and audience controls with independent exclusions.",
      "properties": {
        "schema_version": {
          "const": 1,
          "default": 1,
          "type": "integer"
        },
        "countries": {
          "default": [],
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "excluded_countries": {
          "default": [],
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "included_locations": {
          "default": [],
          "items": {
            "$ref": "#/$defs/ProviderLocation"
          },
          "maxItems": 100,
          "type": "array"
        },
        "excluded_locations": {
          "default": [],
          "items": {
            "$ref": "#/$defs/ProviderLocation"
          },
          "maxItems": 100,
          "type": "array"
        },
        "genders": {
          "default": [],
          "items": {
            "enum": [
              1,
              2
            ],
            "type": "integer"
          },
          "type": "array"
        },
        "user_os": {
          "default": [],
          "items": {
            "type": "string"
          },
          "maxItems": 10,
          "type": "array"
        },
        "user_device": {
          "default": [],
          "items": {
            "type": "string"
          },
          "maxItems": 100,
          "type": "array"
        },
        "advantage_audience": {
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "custom_audiences": {
          "default": [],
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "excluded_custom_audiences": {
          "default": [],
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "locales": {
          "default": [],
          "items": {
            "type": "integer"
          },
          "type": "array"
        },
        "age_min": {
          "anyOf": [
            {
              "maximum": 65,
              "minimum": 13,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "age_max": {
          "anyOf": [
            {
              "maximum": 65,
              "minimum": 13,
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "audience_semantics": {
          "default": "control",
          "enum": [
            "control",
            "suggestion"
          ],
          "type": "string"
        }
      },
      "type": "object"
    },
    "WorkspaceLaunchSubmit": {
      "additionalProperties": false,
      "description": "Brandless public schema with legacy receipt parsing for exact retries.",
      "properties": {
        "schema_version": {
          "const": 1,
          "default": 1,
          "type": "integer"
        },
        "name": {
          "default": "Launch",
          "maxLength": 200,
          "minLength": 1,
          "type": "string"
        },
        "request_key": {
          "maxLength": 200,
          "minLength": 1,
          "type": "string"
        },
        "ad_account_id": {
          "format": "uuid",
          "type": "string"
        },
        "operation": {
          "enum": [
            "test",
            "promote",
            "refresh"
          ],
          "type": "string"
        },
        "purpose": {
          "enum": [
            "test",
            "scale"
          ],
          "type": "string"
        },
        "template_version_id": {
          "format": "uuid",
          "type": "string"
        },
        "selection": {
          "$ref": "#/$defs/SelectionSpec"
        },
        "repeat_across_groups": {
          "default": false,
          "type": "boolean"
        },
        "manual_groups": {
          "default": [],
          "items": {
            "$ref": "#/$defs/ManualGroup"
          },
          "maxItems": 100,
          "type": "array"
        },
        "requested_status": {
          "$ref": "#/$defs/RequestedStatus",
          "default": "PAUSED"
        },
        "scheduled_at": {
          "anyOf": [
            {
              "format": "date-time",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "source_launch_item_ids": {
          "default": [],
          "items": {
            "format": "uuid",
            "type": "string"
          },
          "type": "array"
        },
        "target": {
          "anyOf": [
            {
              "$ref": "#/$defs/ExistingTargetSpec"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "retest_reason": {
          "anyOf": [
            {
              "maxLength": 2000,
              "minLength": 1,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "replacement": {
          "anyOf": [
            {
              "$ref": "#/$defs/ReplacementSpec"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "required": [
        "request_key",
        "ad_account_id",
        "operation",
        "purpose",
        "template_version_id",
        "selection"
      ],
      "type": "object"
    }
  },
  "additionalProperties": false,
  "properties": {
    "request": {
      "$ref": "#/$defs/WorkspaceLaunchSubmit",
      "type": "object"
    }
  },
  "required": [
    "request"
  ],
  "type": "object"
}

launcher_launches_list

List launches with the newest first. For the next page, pass the returned next_cursor as after_id and keep the same account. Access: mcp:read.

Parameter	Type	Required / default	Details
`ad_account_id`	uuid	Required	Superlaunch account UUID from `ad_accounts_list`.
`limit`	integer	`50`	minimum: `1`. maximum: `100`.
`after_id`	uuid or null	`null`	Pagination cursor from the preceding result.

Full input schema

{
  "additionalProperties": false,
  "properties": {
    "ad_account_id": {
      "format": "uuid",
      "type": "string"
    },
    "limit": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    },
    "after_id": {
      "anyOf": [
        {
          "format": "uuid",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "ad_account_id"
  ],
  "type": "object"
}

launcher_launches_get

Read launch status and links to the operation results. Access: mcp:read.

Parameter	Type	Required / default	Details
`ad_account_id`	uuid	Required	Superlaunch account UUID from `ad_accounts_list`.
`launch_id`	uuid	Required	Launch UUID from submission or `launcher_launches_list`.

Full input schema

{
  "additionalProperties": false,
  "properties": {
    "ad_account_id": {
      "format": "uuid",
      "type": "string"
    },
    "launch_id": {
      "format": "uuid",
      "type": "string"
    }
  },
  "required": [
    "ad_account_id",
    "launch_id"
  ],
  "type": "object"
}

launcher_launches_change_status

Hold or resume an unstarted run; a missed time requires Run now or a new time. Access: mcp:read and mcp:write.

Parameter	Type	Required / default	Details
`ad_account_id`	uuid	Required	Superlaunch account UUID from `ad_accounts_list`.
`launch_id`	uuid	Required	Launch UUID from submission or `launcher_launches_list`.
`enabled`	boolean	Required
`expected_version`	integer	Required	minimum: `1`.
`scheduled_at`	date-time or null	`null`	Launch date and time, including the UTC offset.
`run_now`	boolean	`false`	Run a held launch now rather than wait for a new time.

Retries: read the current state after a timeout. If the change has already applied, do not submit it again with an old version.

Full input schema

{
  "additionalProperties": false,
  "properties": {
    "ad_account_id": {
      "format": "uuid",
      "type": "string"
    },
    "launch_id": {
      "format": "uuid",
      "type": "string"
    },
    "enabled": {
      "type": "boolean"
    },
    "expected_version": {
      "minimum": 1,
      "type": "integer"
    },
    "scheduled_at": {
      "anyOf": [
        {
          "format": "date-time",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "type": [
        "string",
        "null"
      ]
    },
    "run_now": {
      "default": false,
      "type": "boolean"
    }
  },
  "required": [
    "ad_account_id",
    "launch_id",
    "enabled",
    "expected_version"
  ],
  "type": "object"
}

launcher_launches_cancel

Request cancellation of a launch. Existing Meta objects remain, and a write already in progress may still finish. Read the result to confirm what stopped. Access: mcp:read and mcp:write.

Parameter	Type	Required / default	Details
`ad_account_id`	uuid	Required	Superlaunch account UUID from `ad_accounts_list`.
`launch_id`	uuid	Required	Launch UUID from submission or `launcher_launches_list`.
`expected_version`	integer	Required	minimum: `1`.

Retries: read the current state after a timeout. If the change has already applied, do not submit it again with an old version.

Full input schema

{
  "additionalProperties": false,
  "properties": {
    "ad_account_id": {
      "format": "uuid",
      "type": "string"
    },
    "launch_id": {
      "format": "uuid",
      "type": "string"
    },
    "expected_version": {
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "ad_account_id",
    "launch_id",
    "expected_version"
  ],
  "type": "object"
}

launcher_launches_replacement_candidates

Find failed items eligible for replacement with corrected content. Approve the new version, check the target, then preview and submit with the returned replacement details and a new request key. Leave successful items and items with uncertain outcomes unchanged. Access: mcp:read.

Parameter	Type	Required / default	Details
`ad_account_id`	uuid	Required	Superlaunch account UUID from `ad_accounts_list`.
`launch_id`	uuid	Required	Launch UUID from submission or `launcher_launches_list`.
`limit`	integer	`50`	minimum: `1`. maximum: `100`.
`after_id`	uuid or null	`null`	Pagination cursor from the preceding result.

Full input schema

{
  "additionalProperties": false,
  "properties": {
    "ad_account_id": {
      "format": "uuid",
      "type": "string"
    },
    "launch_id": {
      "format": "uuid",
      "type": "string"
    },
    "limit": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    },
    "after_id": {
      "anyOf": [
        {
          "format": "uuid",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "ad_account_id",
    "launch_id"
  ],
  "type": "object"
}

launcher_run_operations

Read the result and attempt history of each launch operation. Access: mcp:read.

Parameter	Type	Required / default	Details
`ad_account_id`	uuid	Required	Superlaunch account UUID from `ad_accounts_list`.
`launch_id`	uuid	Required	Launch UUID from submission or `launcher_launches_list`.
`limit`	integer	`50`	minimum: `1`. maximum: `100`.
`after_id`	uuid or null	`null`	Pagination cursor from the preceding result.

Full input schema

{
  "additionalProperties": false,
  "properties": {
    "ad_account_id": {
      "format": "uuid",
      "type": "string"
    },
    "launch_id": {
      "format": "uuid",
      "type": "string"
    },
    "limit": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    },
    "after_id": {
      "anyOf": [
        {
          "format": "uuid",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "ad_account_id",
    "launch_id"
  ],
  "type": "object"
}

launcher_launches_retry

Retry eligible failed operations with their original inputs. Superlaunch blocks retries when it cannot confirm whether Meta already changed. For operations that failed before any attempt, use attempt 0 in expected_attempts. Access: mcp:read and mcp:write.

Parameter	Type	Required / default	Details
`ad_account_id`	uuid	Required	Superlaunch account UUID from `ad_accounts_list`.
`launch_id`	uuid	Required	Launch UUID from submission or `launcher_launches_list`.
`expected_version`	integer	Required	minimum: `1`.
`expected_attempts`	object	Required	Current attempt number for each operation selected for retry.

Retries: read the current state after a timeout. If the change has already applied, do not submit it again with an old version.

Full input schema

{
  "additionalProperties": false,
  "properties": {
    "ad_account_id": {
      "format": "uuid",
      "type": "string"
    },
    "launch_id": {
      "format": "uuid",
      "type": "string"
    },
    "expected_version": {
      "minimum": 1,
      "type": "integer"
    },
    "expected_attempts": {
      "additionalProperties": {
        "minimum": 0,
        "type": "integer"
      },
      "maxProperties": 5000,
      "minProperties": 1,
      "propertyNames": {
        "format": "uuid"
      },
      "type": "object"
    }
  },
  "required": [
    "ad_account_id",
    "launch_id",
    "expected_version",
    "expected_attempts"
  ],
  "type": "object"
}

Start here

Workspace

Workflows

Launcher

MCP

MCP reference

Support

Launcher launch tools

launcher_promotion_sources_list

launcher_assets_list

launcher_targets_list

launcher_targets_get

launcher_launches_preview

request fields

launcher_launches_submit

request fields

launcher_launches_list

launcher_launches_get

launcher_launches_change_status

launcher_launches_cancel

launcher_launches_replacement_candidates

launcher_run_operations

launcher_launches_retry

​launcher_promotion_sources_list

​launcher_assets_list

​launcher_targets_list

​launcher_targets_get

​launcher_launches_preview

​request fields

​launcher_launches_submit

​request fields

​launcher_launches_list

​launcher_launches_get

​launcher_launches_change_status

​launcher_launches_cancel

​launcher_launches_replacement_candidates

​launcher_run_operations

​launcher_launches_retry

launcher_promotion_sources_list

launcher_assets_list

launcher_targets_list

launcher_targets_get

launcher_launches_preview

request fields

launcher_launches_submit

request fields

launcher_launches_list

launcher_launches_get

launcher_launches_change_status

launcher_launches_cancel

launcher_launches_replacement_candidates

launcher_run_operations

launcher_launches_retry