> ## 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.
# List ads
> Newest first. Pass ids to poll the ads you created with POST /meta_ads/bulk. Only ads built in Growi are listed unless include_external=true.
Lists your Meta ads with their publish status, newest first. Pass `ids` to poll the ads you created with [Create ads in bulk](/api-reference/endpoint/meta-ads/bulk-create-ads). Only ads built in Growi are listed unless `include_external=true`.
Step 4 of the [Meta ads automation flow](/essentials/meta-ads-automation).
## Polling publish status
Ads usually publish within a few minutes. Poll every few minutes, not every few seconds: each poll counts against the hourly limit.
| `state` | What to do |
| - | - |
| `queued`, `publishing` | Wait and poll again |
| `published` | On Meta and paused. [Launch it](/api-reference/endpoint/meta-ads/launch-ad) if you sent `launch_state: "paused"`. |
| `active` | Live and spending |
| `failed` | Read `error_message` and `last_step`, fix the content or settings, and create the ad again |
## Ad fields
| Field | Meaning |
| - | - |
| `id` | Growi ad id. Use it with get, launch and pause. |
| `meta_ad_id` | Meta's ad id, once the ad is on Meta |
| `state` | Growi publish state: `queued`, `publishing`, `published`, `active` or `failed` |
| `status` | Meta delivery status, such as `PAUSED`, `ACTIVE` or `DELETED` |
| `published` | `true` once the ad exists on Meta |
| `failed`, `error_message`, `last_step` | Why and where publishing or launching failed |
| `campaign_affiliate_id` | The creator enrollment credited for this ad's spend |
| `external` | `true` for ads imported from Ads Manager |
## Authentication
Any organization API key works, including view-only keys. A key acts as the person who created it, so that person needs the owner, admin or viewer role. 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 |
| `404` | organization\_id is not a child brand of the key's organization |
| `422` | Unknown `state`, or more than 200 `ids` |
| `429` | Rate limited: 2 seconds between requests, and 40 requests per hour per key by default |
```bash cURL theme={"dark"}
curl -X GET "https://api.growi.io/api/public/v1/meta_ads?ids=5012,5013" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```json 200 theme={"dark"}
{
"success": true,
"data": [
{
"id": 5012,
"name": "Ava ad",
"meta_ad_id": "120214567890123456",
"state": "published",
"status": "PAUSED",
"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"
},
{
"id": 5013,
"name": "Mia ad",
"meta_ad_id": null,
"state": "failed",
"status": "PAUSED",
"published": false,
"failed": true,
"error_message": "The video is too short for this placement",
"last_step": "ensure_video",
"meta_ad_set_id": 78552828,
"meta_ad_set_name": "Broad US",
"campaign_affiliate_id": 3490320,
"external": false,
"created_at": "2026-10-14T13:05:12Z"
}
],
"meta": {
"page": 1,
"per_page": 25,
"total_count": 2,
"total_pages": 1,
"has_more": false
},
"by_state": {
"published": 1,
"failed": 1
}
}
```
## OpenAPI
````yaml GET /meta_ads
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:
get:
summary: Lists Meta ads with publish status
description: >-
Newest first. Pass ids to poll the ads you created with POST
/meta_ads/bulk. Only ads built in Growi are listed unless
include_external=true.
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: ids
in: query
required: false
schema:
type: string
description: Comma separated Growi ad ids (up to 200)
example: 5012,5013
- name: state
in: query
required: false
schema:
type: string
enum:
- queued
- publishing
- published
- active
- failed
- name: status
in: query
required: false
schema:
type: string
description: Meta delivery status, such as ACTIVE or PAUSED (case insensitive)
- name: meta_ad_set_id
in: query
required: false
schema:
type: integer
- name: include_external
in: query
required: false
schema:
type: boolean
default: false
description: Also list ads imported from Ads Manager
- name: page
in: query
required: false
schema:
type: integer
default: 1
- name: per_page
in: query
required: false
schema:
type: integer
default: 25
maximum: 100
responses:
'200':
description: Ads
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: array
items:
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
meta:
type: object
properties:
page:
type: integer
per_page:
type: integer
total_count:
type: integer
total_pages:
type: integer
has_more:
type: boolean
by_state:
type: object
additionalProperties:
type: integer
description: Count per state for the whole filtered list
example:
success: true
data:
- id: 5012
name: Ava ad
meta_ad_id: '120214567890123456'
state: published
status: PAUSED
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'
- id: 5013
name: Mia ad
meta_ad_id: null
state: failed
status: PAUSED
published: false
failed: true
error_message: The video is too short for this placement
last_step: ensure_video
meta_ad_set_id: 78552828
meta_ad_set_name: Broad US
campaign_affiliate_id: 3490320
external: false
created_at: '2026-10-14T13:05:11Z'
meta:
page: 1
per_page: 25
total_count: 2
total_pages: 1
has_more: false
by_state:
published: 1
failed: 1
'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.
'404':
description: organization_id is not a child brand of the key's organization
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
error:
type: string
example:
success: false
error: Organization not found
'422':
description: Unknown state, or more than 200 ids
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
error:
type: string
example:
success: false
error: >-
state must be one of: queued, publishing, published, active,
failed
'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.