> ## Documentation Index
> Fetch the complete documentation index at: https://growi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Launch an ad
> Turns a published ad on, with its ad set and campaign. An ad that is still publishing launches as soon as it publishes (deferred: true). Already active ads are left as they are. Needs an owner or admin key.
Turns an ad on, with its ad set and campaign, and starts spend. An ad that is still publishing launches as soon as it publishes (`deferred: true`). An ad that is already active is left as it is.
Step 5 of the [Meta ads automation flow](/essentials/meta-ads-automation). You do not need this call for ads created with `launch_state: "active"`.
## Authentication
Needs a **full-access** API key whose creator is an owner or admin. Legacy keys that are not tied to a person also work. View-only keys, and keys whose creator has the viewer role, get `403`. See [Rate limits and authentication](/api-reference/introduction).
## Errors
| Status | When |
| - | - |
| `401` | Missing or invalid API key, or the person who created the key is no longer an owner, admin or viewer of the organization |
| `403` | View-only API key, or the key's user is not an owner or admin |
| `404` | No ad with this id in your organization, or organization\_id is not a child brand of the key's organization |
| `422` | Meta refused the launch, or the ad was deleted (`AD_DELETED`). `data` shows the ad as it is now. |
| `429` | Rate limited: 2 seconds between requests, and 40 requests per hour per key by default |
```bash cURL theme={"dark"}
curl -X POST "https://api.growi.io/api/public/v1/meta_ads/5012/launch" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```json 200 theme={"dark"}
{
"success": true,
"data": {
"id": 5012,
"name": "Ava ad",
"meta_ad_id": "120214567890123456",
"state": "active",
"status": "ACTIVE",
"published": true,
"failed": false,
"error_message": null,
"last_step": "ad",
"meta_ad_set_id": 78552828,
"meta_ad_set_name": "Broad US",
"campaign_affiliate_id": 3490313,
"external": false,
"created_at": "2026-10-14T13:05:11Z",
"deferred": false
}
}
```
```json 422 theme={"dark"}
{
"success": false,
"data": {
"id": 5012,
"name": "Ava ad",
"meta_ad_id": "120214567890123456",
"state": "published",
"status": "DELETED",
"published": true,
"failed": false,
"error_message": null,
"last_step": "ad",
"meta_ad_set_id": 78552828,
"meta_ad_set_name": "Broad US",
"campaign_affiliate_id": 3490313,
"external": false,
"created_at": "2026-10-14T13:05:11Z"
},
"error": {
"code": "AD_DELETED",
"message": "This ad was deleted."
}
}
```
## OpenAPI
````yaml POST /meta_ads/{id}/launch
openapi: 3.0.1
info:
title: Growi API
description: >-
API documentation for Growi platform, showcasing the public tracking event
endpoint
license:
name: MIT
version: 1.0.0
servers:
- url: https://api.growi.io/api/public/v1
security:
- bearerAuth: []
paths:
/meta_ads/{id}/launch:
post:
summary: Launches a Meta ad (starts spend)
description: >-
Turns a published ad on, with its ad set and campaign. An ad that is
still publishing launches as soon as it publishes (deferred: true).
Already active ads are left as they are. Needs an owner or admin key.
parameters:
- name: organization_id
in: query
required: false
schema:
type: integer
description: >-
Act on a child brand of the API key's organization. Omit it to act
on the key's own organization. Any other id returns 404.
- name: id
in: path
required: true
schema:
type: integer
description: Growi ad id
example: 5012
responses:
'200':
description: Launched, or queued to launch after publish
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
allOf:
- type: object
properties:
id:
type: integer
description: Growi ad id
name:
type: string
meta_ad_id:
type: string
nullable: true
description: Meta's ad id, once published
state:
type: string
enum:
- queued
- publishing
- published
- active
- failed
description: Growi publish state
status:
type: string
description: 'Meta delivery status: PAUSED, ACTIVE, DELETED, ...'
published:
type: boolean
description: true once the ad exists on Meta
failed:
type: boolean
error_message:
type: string
nullable: true
description: Why publishing or launching failed
last_step:
type: string
nullable: true
description: >-
The publish step that ran last (for example
launch)
meta_ad_set_id:
type: integer
nullable: true
meta_ad_set_name:
type: string
nullable: true
campaign_affiliate_id:
type: integer
nullable: true
description: >-
The creator enrollment credited for this ad's
spend
external:
type: boolean
description: true for ads imported from Ads Manager
created_at:
type: string
format: date-time
- type: object
properties:
deferred:
type: boolean
description: >-
launch only: true when the ad is still publishing
and will launch once it publishes
error:
type: object
properties:
code:
type: string
message:
type: string
details:
type: object
additionalProperties: true
examples:
launched:
summary: Published ad turned on
value:
success: true
data:
id: 5012
name: Ava ad
meta_ad_id: '120214567890123456'
state: active
status: ACTIVE
published: true
failed: false
error_message: null
last_step: ad
meta_ad_set_id: 78552828
meta_ad_set_name: Broad US
campaign_affiliate_id: 3490313
external: false
created_at: '2026-10-14T13:05:11Z'
deferred: false
deferred:
summary: Still publishing
value:
success: true
data:
id: 5012
name: Ava ad
meta_ad_id: null
state: queued
status: PAUSED
published: false
failed: false
error_message: null
last_step: null
meta_ad_set_id: 78552828
meta_ad_set_name: Broad US
campaign_affiliate_id: 3490313
external: false
created_at: '2026-10-14T13:05:11Z'
deferred: true
'401':
description: >-
Missing or invalid API key, or the person who created the key is no
longer an owner, admin or viewer of the organization
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
error:
type: string
examples:
missing_key:
summary: Missing or invalid key
value:
error: Not Authenticated
creator_left:
summary: Key creator no longer in the organization
value:
success: false
error: >-
The user who created this API key no longer has access to
this organization.
'403':
description: View-only API key, or the key's user is not an owner or admin
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
error:
type: string
examples:
viewer_key:
summary: View-only API key
value:
error: This API key is read-only and cannot modify data.
viewer_role:
summary: The key's user is not an owner or admin
value:
success: false
error: >-
Only an organization owner or admin can make changes with
this API key.
'404':
description: No ad with this id in your organization
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
error:
type: string
examples:
ad:
summary: No ad with this id in your organization
value:
success: false
error: Meta ad not found
organization:
summary: organization_id is not a child brand
value:
success: false
error: Organization not found
'422':
description: >-
Meta refused the launch, or the ad was deleted. data carries the ad
as it is now.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
allOf:
- type: object
properties:
id:
type: integer
description: Growi ad id
name:
type: string
meta_ad_id:
type: string
nullable: true
description: Meta's ad id, once published
state:
type: string
enum:
- queued
- publishing
- published
- active
- failed
description: Growi publish state
status:
type: string
description: 'Meta delivery status: PAUSED, ACTIVE, DELETED, ...'
published:
type: boolean
description: true once the ad exists on Meta
failed:
type: boolean
error_message:
type: string
nullable: true
description: Why publishing or launching failed
last_step:
type: string
nullable: true
description: >-
The publish step that ran last (for example
launch)
meta_ad_set_id:
type: integer
nullable: true
meta_ad_set_name:
type: string
nullable: true
campaign_affiliate_id:
type: integer
nullable: true
description: >-
The creator enrollment credited for this ad's
spend
external:
type: boolean
description: true for ads imported from Ads Manager
created_at:
type: string
format: date-time
- type: object
properties:
deferred:
type: boolean
description: >-
launch only: true when the ad is still publishing
and will launch once it publishes
error:
type: object
properties:
code:
type: string
message:
type: string
details:
type: object
additionalProperties: true
examples:
meta_error:
summary: Meta refused the launch
value:
success: false
data:
id: 5012
name: Ava ad
meta_ad_id: '120214567890123456'
state: failed
status: PAUSED
published: true
failed: true
error_message: Ad account has no payment method
last_step: launch
meta_ad_set_id: 78552828
meta_ad_set_name: Broad US
campaign_affiliate_id: 3490313
external: false
created_at: '2026-10-14T13:05:11Z'
error:
code: META_API_ERROR
message: Ad account has no payment method
step: launch
deleted:
summary: Deleted ad
value:
success: false
data:
id: 5012
name: Ava ad
meta_ad_id: '120214567890123456'
state: published
status: DELETED
published: true
failed: false
error_message: null
last_step: ad
meta_ad_set_id: 78552828
meta_ad_set_name: Broad US
campaign_affiliate_id: 3490313
external: false
created_at: '2026-10-14T13:05:11Z'
error:
code: AD_DELETED
message: This ad was deleted.
'429':
description: >-
Rate limited: 2 seconds between requests, and 40 requests per hour
per key by default
content:
application/json:
schema:
type: object
properties:
error:
type: string
retry_after:
type: integer
reset_time:
type: string
examples:
burst:
summary: Under 2 seconds since the last request
value:
error: >-
Rate limit exceeded. Please wait 2 seconds between
requests.
retry_after: 2
hourly:
summary: Hourly cap reached
value:
error: Hourly rate limit of 40 requests exceeded.
retry_after: 1520
reset_time: '2026-10-12T15:00:00Z'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.