Sign in

v2

latestOpenAPI 3.1.02026-08-075421692.0 MB
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 only on 202 responses: part of the requested date range is still being backfilled from the platform in the background. Retry the same request shortly; it returns 200 once the range is fully ingested.

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
        }
      },
      "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"
        ]
      }
    }
  ]
}