Ads
List Meta Ads campaigns, ad sets and ads via API
Three GET routes list the campaigns, ad sets and ads of a customer's ad account, with status, effective status, issues and budget. You choose to read what Connect stores or the account live, with no OAuth to build and no Meta app review.
The request
GET /api/ads/campaigns?customer_integration=<connection uuid>&source=external&status=active&per_page=50 Authorization: Bearer <merchant token> x-customer-token: <customer token>
What you can do
- List campaigns, ad sets and ads with GET /ads/campaigns, /ads/adsets and /ads.
- Read the account live with source=external, including what was created outside Connect.
- Filter by status (active or paused) and, with source=connect, by effective_status, such as pending_review or disapproved.
- See in issues why the platform is holding an object, such as a rejection or a delivery problem.
- Filter ad sets and ads by campaign_id and ads by adset_id, and paginate with page and per_page.
Rules and limits
- The default is source=connect: what Connect created or already wrote in the account, without calling the platform. An account with older campaigns lists empty until the first write through Connect.
- To see the whole account, use source=external. The live read is cached for 120 s, and refresh=true bypasses the cache.
- Every response carries synced_at, the last time Connect checked the object. With source=connect, refresh=true re-reads the status and name of the page's items.
- per_page goes from 1 to 100 (default 15) and the response is {data, links, meta}. With source=external there is no meta.total, and with status the page may exceed per_page slightly.
- Items Connect stores come with a uuid. Ones that only exist in the account come with uuid null. The budget comes in the account's currency, never in cents.
Main fields
| Field | Type | Required | Description |
|---|---|---|---|
| customer_integration | string | Yes | The uuid of the customer's connection. It defines the ad account. Always goes in the query. |
| source | string | No | connect (default) reads what Connect created or already wrote in the account. external reads the account live, including what was created outside Connect. |
| status | string | No | Filters by active or paused. |
| effective_status | string | No | Only with source=connect. Filters by the status the platform actually applies, such as pending_review, disapproved or with_issues. |
| refresh | boolean | No | With source=external it bypasses the 120 s cache. With source=connect it re-reads the status and name of the page's items and updates Connect. |
| per_page | integer | No | Items per page, from 1 to 100. The default is 15. |
| campaign_id | string | No | Only on /ads/adsets and /ads: filters by the campaign id or the Connect uuid. |
| include_deleted | boolean | No | Only with source=connect. Includes deleted objects, with deleted_at. |
Who it is for
Campaign dashboard in your SaaS
Show the customer their active campaigns, budget and effective status without opening Ads Manager.
Rejected ad alerts
Poll with effective_status=disapproved and notify the team when an ad is rejected, with the reason in issues.
AI agent that audits accounts
An agent lists the account live, finds ad sets with delivery problems and suggests pausing or adjusting the budget.
Works with
Meta Ads
Frequently asked questions
Why is the list empty on an account that already had campaigns?
Because the default is source=connect, which only shows what Connect created or already wrote in the account. To see what was created outside Connect, use source=external.
Is the data real time?
With source=external yes, cached for 120 s and refresh=true bypasses it. With source=connect you see the last known state, shown in synced_at, and refresh=true updates it.
How do I filter only what has problems?
Use effective_status with values such as with_issues, disapproved or pending_review (only with source=connect). The reason comes in the issues field.
See Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
