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

FieldTypeRequiredDescription
customer_integrationstringYesThe uuid of the customer's connection. It defines the ad account. Always goes in the query.
idstringYesIn /pixels/{id}/events: the pixel id, from GET /ads/facebook_ads/pixels.
refreshbooleanNoBypasses the 600 s cache and fetches again from the platform.
event_namestringNoIn the response: the name of the event the pixel recorded.
countintegerNoIn the response: how many times the event occurred in the last 90 days.
last_fired_atstringNoIn the pixels list: when the pixel last fired.
is_unavailablebooleanNoIn 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.

Related

See everything you can do with Ads

See Connect applied to your product.

Try it for 15 days with no card, or walk our team through your use case.