Ad Campaigns

Get ad details

Changed on

Shows one ad with its creative, targeting, status and performance metrics.

Google Search ads include current creative.headlines, creative.descriptions and creative.finalUrls, preserving pinnedField. Top-level cachedAt and stale report cache freshness. Google mutations invalidate this read. RSA enrichment requires a stored advertisingChannelType of SEARCH. Ads with an unknown or other channel return their stored details without a Google read. If RSA enrichment fails, the stored ad is returned with HTTP 200 and without cache metadata.

The {adId} path segment accepts any identifier dialect Zernio indexes for the ad:

  • the Zernio internal _id (24-char hex)

  • Meta's numeric platformAdId (the value shipped in comment.received webhooks as comment.ad.id)

  • the creative's effective_object_story_id ({pageId}_{postId} shape, Facebook side)

  • the creative's effective_instagram_media_id (Instagram side)

  • an Instagram media id an ad comment arrived on (comment.platformPostId of a comment.received carrying comment.ad.id), including the extra media Meta creates for placement variants

Any of these resolve to the same ad. Caller doesn't need a translation step. creative.creativeFeatures holds the stored requested settings, which do not confirm platform application.

Facebook ad dark posts. Meta gives an ad with per-placement assets one extra unpublished post per placement, and comments land on it. Meta exposes no link from that post to its ad. When exactly one ad on the Page, created before the dark post, carries the same copy as the post, the dark post id resolves to that ad. Otherwise, when the id is a dark post Zernio has seen comments on and its Page is connected, the response is ad: null plus darkPost, which carries the Meta Ads account and the ad accounts running ads for that Page. Read its comments with GET /v1/ads/{adId}/comments using the same id.

Status freshness. status, configuredStatus, platformStatus, platformAdSetStatus and platformCampaignStatus are the values Zernio last stored. Background sync refreshes them, typically within 15 to 60 minutes (Google up to about 3 hours), and ended or long-paused objects may be refreshed less often. Zernio's own status writes re-read the switches they change. A change made in the platform's own ads manager therefore shows up here only after the next sync. Controllers that act on a switch should pass live=true, which reads the switches from the platform now, stores them, and returns statusReadAt (null when the read failed and the stored values were returned). With live=true the ad's own switch (configuredStatus), its delivery status (status, platformStatus) and its ad set and campaign switches (platformAdSetStatus, platformCampaignStatus) are read live.

get/v1/ads/{adId}

Request

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

Path parameters

adIdstring required

Zernio _id (hex), Meta platformAdId (numeric), or one of the creative's effective story/media IDs. See description for details.

Query parameters

liveboolean

Read the on/off switches live from the platform instead of returning the synced values. The fresh values are stored (so later reads return them too) and the response carries statusReadAt, the time of the read. At most 20 platform objects are read per request. Where a read fails (credentials, platform error, no reader on that platform), the stored values come back with statusReadAt: null. See "Status freshness" in the operation description. On X the budget is read live in the same read: on GET /v1/ads/{adId} budget, adSetBudget, campaignBudget and budgetLevel are the line item and campaign budgets X holds now (stored like the switches); on the ad set and campaign listings budget is the one that line item or campaign holds now (returned, not stored); a row whose budget the other level holds keeps its synced budget.

Response

Ad details

cachedAtstring date-time nullable

Google RSA details cache timestamp.

staleboolean

Whether Google RSA details use the last successful cached response.

statusReadAtstring date-time nullable

Only with live=true. When the switches were read from the platform; null when the live read failed and the stored values were returned.

Example response

{
  "ad": {
    "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