Ad Campaigns

List ads

Changed on

Lists your ads with their performance over a date range, including ads created directly in each platform's ads manager.

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.

History: when an ad account connects, Zernio imports its last 90 days of metrics, so the metrics hold no data for days before that. When accountId or adAccountId resolves to a Meta ad account, a range reaching further back answers 202 with backfillPending: true and the covered part while the older days (up to 730 days back) are imported in the background; repeat the request until it returns 200. A request scoped to no Meta account never returns 202.

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

Request

  • Base URL: https://zernio.com/api
  • URL: https://zernio.com/api/v1/ads
  • Auth: HTTP bearer

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' | 'reddit'
accountIdstring

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)

adSetIdstring

Platform ad set ID (filter ads within an ad set, the /{adset_id}/ads read of an adset-centric dashboard).

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

Meta only. 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": {
        "assetGroup": {
          "finalUrl": "https://zernio.com",
          "headlines": [
            "Schedule posts",
            "One social API",
            "Build with Zernio"
          ],
          "longHeadline": "Schedule social content from your app with Zernio",
          "descriptions": [
            "Connect your social accounts.",
            "Publish and manage social content through one API."
          ],
          "businessName": "Zernio",
          "images": {
            "landscape": [
              "https://example.com/landscape.png"
            ],
            "square": [
              "https://example.com/square.png"
            ],
            "logo": [
              "https://example.com/logo.png"
            ]
          }
        },
        "assetGroupResourceName": "customers/9122445560/assetGroups/123456789",
        "creativeFeatures": {
          "auto_promotion_tag": "OPT_IN"
        },
        "carouselCards": [
          {
            "callToAction": "SHOP_NOW"
          }
        ],
        "servingHoldReasons": [
          "UNDER_REVIEW"
        ],
        "whatsappPhoneNumber": "+12025550123"
      }
    }
  ]
}

Changes

  • eeca67883e58Revision changes
    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /////// to the response with the status

  • c4ef454f4599Revision changes
    • info

      added the optional property /// to the response with the status

    • info

      added the optional property /////// to the response with the status