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.

GET /meta_ads

cURL

curl -X GET "https://api.growi.io/api/public/v1/meta_ads?ids=5012,5013" \
     -H "Authorization: Bearer YOUR_API_KEY"

200

{
  "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
  }
}

Lists your Meta ads with their publish status, newest first. Pass ids to poll the ads you created with Create ads in bulk. Only ads built in Growi are listed unless include_external=true.

Step 4 of the Meta ads automation flow.

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 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.

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

cURL

curl -X GET "https://api.growi.io/api/public/v1/meta_ads?ids=5012,5013" \
     -H "Authorization: Bearer YOUR_API_KEY"

200

{
  "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
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

organization_id · integer

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.

ids · string

Comma separated Growi ad ids (up to 200)

state · enum<string>

Available options: queued, publishing, published, active, failed

status · string

Meta delivery status, such as ACTIVE or PAUSED (case insensitive)

meta_ad_set_id · integer

include_external · boolean · default: false

Also list ads imported from Ads Manager

page · integer · default: 1

per_page · integer · default: 25

Required range: x <= 100

Response

200

application/json

Ads

success · boolean

data · object[]

Show child attributes

meta · object

Show child attributes

by_state · object

Count per state for the whole filtered list

Show child attributes