Sign in

v2

latestOpenAPI 3.1.02026-08-075421692.0 MB
Ad Campaigns

List campaigns

Returns campaigns as virtual aggregations over ad documents grouped by platform campaign ID. Metrics (spend, impressions, clicks, etc.) are summed across all ads in each campaign. Campaign status is derived from child ad statuses (active > pending_review > paused > error > completed > cancelled > rejected).

get/v1/ads/campaigns

Query parameters

includeEmptyboolean

Meta only. Campaign reads aggregate over ad documents, so a campaign with ZERO ads is normally invisible here — the state the two-step create (campaign, then ads via existingCampaignId) leaves behind whenever Meta rejects the ad step. Set true to list those too, with adCount: 0 and zeroed metrics. Requires accountId and adAccountId, since an empty campaign has no ad row to resolve a token or ad account from.

pageinteger

Page number (1-based)

limitinteger
source'zernio' | 'all'

all (default) returns both Zernio-created ads and those discovered from the platform's ad manager — matches the web UI's default view. Pass zernio to restrict to isExternal=false only. Status is NOT filtered by default — use the status param for that.

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

Filter by derived campaign status (post-aggregation)

adAccountIdstring

Platform ad account ID (e.g. act_123 for Meta)

pageIdstring

Meta only: Facebook Page ID. Campaigns have no Page of their own, so this keeps campaigns having at least one ad backed by this Page, with adCount and metrics computed over those ads only. Mirrors the same filter on /v1/ads and /v1/ads/tree.

accountIdstring

Social account ID

profileIdstring

Profile ID

fromDatestring date

Start of metrics date range (YYYY-MM-DD, inclusive). Defaults to 90 days ago when both date params are omitted.

toDatestring date

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

Response

Paginated campaigns

Example response

{
  "campaigns": [
    {
      "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
        }
      }
    }
  ]
}