Meta Ads - Bug: IG identity auto-resolve binds the Page-Backed shadow account on tree creates, contradicting the `instagramAccountId` docs

POST /v1/ads/create · Meta · API v1 (spec v1.0.4) · observed 2026-08-13

Note: entity ids, domains, and brand strings in this report are anonymized placeholders. Concrete ids for every referenced entity are available on request through our account's support channel.

Summary

Your instagramAccountId field docs say:

"When omitted we auto-resolve the IG account linked to the connected Facebook Page (the existing default)."

The connected Page <PAGE_ID> has exactly one linked Instagram professional account, <REAL_IG_BUSINESS_ACCOUNT_ID> — it is both the Page's instagram_business_account and its connected_instagram_account.

Observed behavior when instagramAccountId is omitted, on the same account, same page, same day:

So the tree-building shapes resolve a Page-Backed Instagram Account (Meta's auto-generated shadow identity that renders as the FB Page) instead of the linked IG professional account — the opposite of what the docs promise, and inconsistent with your own attach shape, which resolves correctly. The ads run on IG placements as the faceless Page identity instead of the brand account, silently.

Environment

• Zernio account (SocialAccount): <ZERNIO_ADS_ACCOUNT_ID> (metaads) / profile <ZERNIO_PROFILE_ID>

• Ad account: act_<AD_ACCOUNT_ID> · Page: <PAGE_ID>

• Linked IG professional account: <REAL_IG_BUSINESS_ACCOUNT_ID> (the linked IG professional account)

• Page-Backed IG being wrongly selected: <PAGE_BACKED_IG_ID> (no username — PBIA)

Repro

1. Composite create (WRONG identity)

Production launch, POST /v1/ads/create with existingCampaignId (full multilingual creative surface; addressing shown):

{
  "accountId": "<ZERNIO_ADS_ACCOUNT_ID>",
  "adAccountId": "act_<AD_ACCOUNT_ID>",
  "name": "CRV-0038-1-(en,es,it,pt)",
  "adSetName": "<AD_SET_NAME>",
  "existingCampaignId": "<EXISTING_CAMPAIGN_ID>",
  "status": "ACTIVE",
  "goal": "conversions",
  "optimizationGoal": "OFFSITE_CONVERSIONS",
  "billingEvent": "IMPRESSIONS",
  "budgetAmount": 50,
  "budgetType": "daily",
  "promotedObject": { "pixelId": "<PIXEL_ID>", "customEventType": "PURCHASE" },
  "tracking": { "pixelId": "<PIXEL_ID>" },
  "headline": "Can't Meditate? Good.", "body": "…", "description": "…",
  "callToAction": "DOWNLOAD", "linkUrl": "…", "video": { "url": "…" },
  "defaultLocale": "en", "translations": [ "… es/it/pt entries …" ]
}

→ ad <AD_ID_COMPOSITE_1>, creative <CREATIVE_ID_COMPOSITE_1>. Meta Graph:

{ "id": "<CREATIVE_ID_COMPOSITE_1>", "instagram_user_id": "<PAGE_BACKED_IG_ID>", "object_story_spec": { "page_id": "<PAGE_ID>" } }

<PAGE_BACKED_IG_ID> is the Page-Backed shadow account. Same result on the plain standalone shape (creative <CREATIVE_ID_STANDALONE>, ad <AD_ID_STANDALONE_PROBE>).

2. Attach create, same day, same account (CORRECT identity)

{
  "accountId": "<ZERNIO_ADS_ACCOUNT_ID>",
  "adAccountId": "act_<AD_ACCOUNT_ID>",
  "name": "CRV-0045-1-(en,es,it,pt)",
  "adSetId": "<TARGET_ADSET_ID>",
  "status": "ACTIVE",
  "tracking": { "pixelId": "<PIXEL_ID>" },
  "headline": "Replace the Scroll", "body": "…", "description": "…",
  "callToAction": "DOWNLOAD", "linkUrl": "…", "video": { "url": "…" },
  "defaultLocale": "en", "translations": [ "… es/it/pt entries …" ]
}

→ ad <AD_ID_ATTACH_PROD>, creative <CREATIVE_ID_ATTACH_PROD>. Meta Graph:

{ "id": "<CREATIVE_ID_ATTACH_PROD>", "instagram_user_id": "<REAL_IG_BUSINESS_ACCOUNT_ID>", "instagram_permalink_url": "<INSTAGRAM_PERMALINK>" }

Correct: the linked professional account, with a real IG dark post.

3. Explicit pin works everywhere (confirms the fix path)

Standalone create with "instagramAccountId": "<REAL_IG_BUSINESS_ACCOUNT_ID>" added, everything else identical → creative <CREATIVE_ID_PINNED> with instagram_user_id<REAL_IG_BUSINESS_ACCOUNT_ID> and the language feed. So the field works; only the omitted-case default is wrong on the tree shapes.

Expected

All three shapes resolve the same identity when instagramAccountId is omitted: the IG professional account linked to the connected Page (here <REAL_IG_BUSINESS_ACCOUNT_ID>), falling back to a PBIA only when the Page has no linked IG account. Attach already behaves this way — standalone and composite should match it (and the docs).

Related feature request: make the linked IG discoverable via the API

To pin instagramAccountId deterministically we need to know the linked IG account id, and today there is no way to read it through your API outside a connect flow:

• the ads SocialAccount documents (GET /v1/accounts…) don't carry it;

• GET /v1/connect/instagram/select-account returns instagram_business_account{id, username} per page, but requires a mid-OAuth tempToken;

• the only observational path is creative.instagramUserId on GET /v1/ads/{adId}, which is resolved lazily and only populates for ads that have gone active — useless before the first launch.

Please expose the connected Page's linked instagram_business_account (id + username) on the ads SocialAccount document or a small dedicated endpoint. That, or fixing the auto-resolve above, unblocks us; both would be ideal.