Sign in
Ad Campaigns

List ads

Returns a paginated list of ads with metrics computed over an optional date range. Use source=all to include externally-synced ads from platform ad managers. If no date range is provided, defaults to the last 90 days. Date range is capped at 730 days max.

To find the Zernio ad behind a comment you see in Meta Business Manager, filter by platformAdId (the Meta ad ID), effectiveObjectStoryId (Facebook), or effectiveInstagramMediaId (Instagram) — those are the post/media the ad's engagement lives on, and are also returned on each ad's creative object. Then call GET /v1/ads/{adId}/comments with the returned ad id.

get/v1/ads

Query parameters

pageinteger

Page number (1-based)

limitinteger
source'zernio' | 'all'

all (default) = Zernio-created + platform-discovered ads. zernio = restrict to Zernio-created only.

status'active' | 'paused' | 'pending_review' | 'rejected' | 'completed' | 'cancelled' | 'error'
platform'facebook' | 'instagram' | 'tiktok' | 'linkedin' | 'pinterest' | 'google' | 'twitter' | 'openai'
accountIdstring

Social account ID

adAccountIdstring

Platform ad account ID (e.g. act_123 for Meta). Mirrors the same filter on /v1/ads/campaigns and /v1/ads/tree.

pageIdstring

Meta only: Facebook Page ID. Returns only ads whose creative is backed by this Page (a Meta ad account serves ads for every Page in the Business Manager). Matches each ad's creative.pageId; ads with no page signal (rare IG-only creatives) never match. Mirrors the same filter on /v1/ads/campaigns and /v1/ads/tree.

profileIdstring

Profile ID

campaignIdstring

Platform campaign ID (filter ads within a campaign)

platformAdIdstring

Meta ad ID. Returns the ad with this platform-side ad ID.

effectiveObjectStoryIdstring

Facebook {pageId}_{postId} of the post the ad's engagement lives on (Meta effective_object_story_id). Use to map a Business-Manager-visible post back to the Zernio ad.

effectiveInstagramMediaIdstring

Instagram media ID of the boosted post (Meta effective_instagram_media_id). Use to map a Business-Manager-visible IG post back to the Zernio ad.

fromDatestring date

Start of metrics date range (YYYY-MM-DD). Defaults to 90 days ago.

toDatestring date

End of metrics date range (YYYY-MM-DD). Defaults to today. Max 730-day range.

Response

Paginated ads

backfillPendingboolean

Present and true while historical data is being backfilled.

Example response

{
  "ads": [
    {
      "configuredStatus": "ACTIVE",
      "creativeType": "video",
      "metrics": {
        "actions": {
          "link_click": 160,
          "post_engagement": 300,
          "offsite_conversion.fb_pixel_purchase": 42
        },
        "actionValues": {
          "offsite_conversion.fb_pixel_purchase": 2456.78,
          "offsite_conversion.fb_pixel_add_to_cart": 980.5
        },
        "costPerAction": {
          "link_click": 0.1052,
          "offsite_conversion.fb_pixel_purchase": 4.0114
        }
      },
      "platformObjective": "OUTCOME_SALES",
      "optimizationGoal": "OFFSITE_CONVERSIONS",
      "costType": "CPC",
      "servingStatuses": [
        "ACCOUNT_TOTAL_BUDGET_HOLD"
      ],
      "platformAdAccountName": "Zernio - previously Late",
      "bidAmount": 5,
      "roasAverageFloor": 2,
      "promotedObject": {
        "custom_event_type": "PURCHASE"
      },
      "creative": {
        "servingHoldReasons": [
          "UNDER_REVIEW"
        ]
      }
    }
  ]
}

Changes

Changed in 4 of the 26 revisions of this API.1210

  • 44b6b1ca2a8b2See the full diff
    • ●

      added the new page_likes enum value to the ads/items/goal response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new page_likes enum value to the allOf[AdsListResponse]/ads/items/goal response property for the response status 202

      response-property-enum-value-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 15e893e69e8c1See the full diff
    • ▲

      the backfillPending response property const value true was removed for the status 202

      response-property-const-removed

  • a23bb6e634382See the full diff
    • ○

      added the optional property ads/items/creative/creativeId to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property allOf[AdsListResponse]/ads/items/creative/creativeId to the response with the 202 status

      response-optional-property-added

  • 5bcceb4c15ba8See the full diff
    • ○

      added the media type application/json for the response with the status 202

      response-media-type-added

    • ○

      added the optional property ads/items/metrics/anyOf[AdMetrics]/costPerAction to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property ads/items/metrics/anyOf[AdMetrics]/inlineLinkClickCtr to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property ads/items/metrics/anyOf[AdMetrics]/inlineLinkClicks to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property ads/items/metrics/anyOf[AdMetrics]/outboundClicks to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property ads/items/metrics/anyOf[AdMetrics]/outboundClicksCtr to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property ads/items/metrics/anyOf[AdMetrics]/uniqueClicks to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property ads/items/metrics/anyOf[AdMetrics]/uniqueCtr to the response with the 200 status

      response-optional-property-added