Sign in
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.

hasDeliveryboolean

Return only campaigns that delivered between fromDate and toDate — spend above zero, or impressions served at zero spend. Unlike status, which reads a campaign's CURRENT state, this filters on what happened inside the window. Filters the campaign set itself, so pagination.total counts only matching campaigns. Mirrors the same filter on /v1/ads/tree.

minSpendnumber

Return only campaigns whose spend between fromDate and toDate reaches this amount, in each campaign's OWN currency (the currency field on the campaign). Implies hasDelivery; minSpend=0 applies no filter. Mirrors the same filter on /v1/ads/tree.

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
        },
        "costPerAction": {
          "link_click": 0.1052,
          "offsite_conversion.fb_pixel_purchase": 4.0114
        }
      }
    }
  ]
}

Changes

Changed in 4 of the 29 revisions of this API.29

  • b5344d376e5e1See the full diff
    • ▲

      response property campaigns/items/optimizationGoal list-of-types was widened by adding types array to media type application/json of response 200

      response-property-list-of-types-widened

  • ac5fffe58a631See the full diff
    • ▲

      the campaigns/items/optimizationGoal response's property type/format changed from string null/ to string array/ for status 200

      response-property-type-changed

  • e0cd920708582See the full diff
    • ○

      added the new optional query request parameter hasDelivery

      new-optional-request-parameter

    • ○

      added the new optional query request parameter minSpend

      new-optional-request-parameter

  • 5bcceb4c15ba7See the full diff
    • ○

      added the optional property campaigns/items/metrics/costPerAction to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property campaigns/items/metrics/inlineLinkClickCtr to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property campaigns/items/metrics/inlineLinkClicks to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property campaigns/items/metrics/outboundClicks to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property campaigns/items/metrics/outboundClicksCtr to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property campaigns/items/metrics/uniqueClicks to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property campaigns/items/metrics/uniqueCtr to the response with the 200 status

      response-optional-property-added