Ads
List Meta Ads pixels and conversion events via API
Two routes show the pixels in the customer's ad account and the events each pixel recorded, with the period's count. The pixel id goes in the ad set optimized for conversion, and you read it all through the customer's connection, without implementing the Meta API.
The request
GET /api/ads/facebook_ads/pixels/900000000000001/events?customer_integration=<connection uuid> Authorization: Bearer <merchant token> x-customer-token: <customer token>
What you can do
- List the account's pixels with GET /ads/facebook_ads/pixels, with id, name, last_fired_at, created_at and is_unavailable.
- See the events a pixel recorded with GET /ads/facebook_ads/pixels/{id}/events, with event_name and count.
- Use the pixel id in adset.facebook_ads.promoted_object.pixel_id on a conversion-optimized ad set.
- Force a fresh read from the platform with refresh=true.
Rules and limits
- The event count covers the last 90 days, the window the integration uses so rare events do not disappear.
- It is not paginated: at most 200 items come back per read.
- Cached for 600 s per connection. meta.cached and meta.cached_at show whether it came from the cache, and refresh=true bypasses it.
- A pixel id that is not in the connection's account answers 404 ads_object_not_found.
- The connection always goes in ?customer_integration= and the call needs Authorization and x-customer-token.
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. |
| id | string | Yes | In /pixels/{id}/events: the pixel id, from GET /ads/facebook_ads/pixels. |
| refresh | boolean | No | Bypasses the 600 s cache and fetches again from the platform. |
| event_name | string | No | In the response: the name of the event the pixel recorded. |
| count | integer | No | In the response: how many times the event occurred in the last 90 days. |
| last_fired_at | string | No | In the pixels list: when the pixel last fired. |
| is_unavailable | boolean | No | In the pixels list: tells whether the pixel is unavailable. |
Who it is for
Check the pixel before launching
Your SaaS checks that the customer's pixel recorded Purchase in the last 90 days before allowing purchase optimization.
Tracking diagnosis at an agency
An agency lists pixels and their last fire date to find the ones that stopped working.
AI agent that picks the event
An agent reads the pixel's events, picks the highest-volume one and configures the ad set with it.
Works with
Meta Ads
Frequently asked questions
What period does the event count cover?
The last 90 days, the window the integration uses so rare events do not disappear.
Where do I use the pixel id?
In adset.facebook_ads.promoted_object.pixel_id, on a conversion-optimized ad set.
How do I know if the pixel is working?
GET /ads/facebook_ads/pixels returns last_fired_at and is_unavailable, and the events route shows which events arrived and how many times.
See Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
