> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Find campaigns created in your ad platform

> Campaigns in an ad account mapped to an advertiser appear in Apostra automatically, including future-start campaigns.

When you ask to list campaigns on a connected ad account, the agent first checks
campaigns already saved in Apostra. That search does not query the ad platform's
native campaign inventory. An empty result does not mean your Spotify Ads Manager
account has no campaigns, and a non-empty result does not prove every native
campaign has been imported.

You can ask in ordinary language:

```text theme={null}
Can you please list existing campaigns on my Spotify ad account
<your-spotify-ad-account-id>, even those that have not started yet?
```

You do not need to know an import tool's name or say where each campaign was
created. If the saved results do not account for the campaigns you expect, the
agent checks the account's mapping and sync state, as described below.

## How campaigns get here

Mapping an ad account to an advertiser starts campaign sync for that account.
There is no separate subscribe step, and every account mapped on a connection
syncs under its own advertiser, whichever account the connection has selected.
An account that is not mapped to an advertiser is never synced. A login that
reaches many client accounts, such as an agency's, syncs only the accounts that
are mapped.

The first sync runs within one 15-minute sweep of the mapping. Later sweeps
pick up changes. The synced campaigns appear as **tracked campaigns**
(`handling: "tracking"`), including campaigns created manually in the ad
platform. The ad platform remains the source of truth: syncing does not create,
edit, launch, pause or cancel its campaigns. Sync does not import delivery
history. In the buyer beta, you can change a tracked Meta campaign through
Apostra, and the first change takes it over; see
[Change a campaign synced from Meta](https://docs.apostra.com/v3/import-existing-campaigns.md#change-a-campaign-synced-from-meta).

A campaign Apostra itself placed through the same account is not synced as a
second copy. The sync recognises it, from the record of where Apostra placed it
(the connection, the ad account and the platform's campaign id), and keeps that
one campaign under its existing media buy. It is a managed campaign, not a
tracked one. This holds after the media buy has ended in Apostra, even while
the platform still shows the campaign paused: the campaign stays under the
ended media buy and is not synced again as a tracked campaign. If an earlier
sync made such a copy, the next sync retires it, unless someone changed the
copy through Apostra. Apostra then reviews that campaign.

Removing the mapping stops the sync and retires Apostra's copies of that
account's campaigns. It never changes or deletes anything in the ad platform.
Mapping the account again starts the sync again. When a campaign is synced
again under a new mapping, the earlier, retired copy stops carrying the
platform's campaign id, so only the current copy answers to it.

## When two advertisers map the same ad account

An ad account syncs once, under one advertiser. When two advertisers of the
same organization map it, the advertiser with the oldest live mapping owns the
account, until an administrator hands it to another advertiser. Every campaign
synced from it belongs to that advertiser, once, and stays with it on every
later sync, including after you change a campaign in the ad platform. The other
advertiser's mapping is kept, but that advertiser sees none of the account's
campaigns.

* **A later mapping changes nothing.** Mapping an account that another
  advertiser already owns, or mapping it again after removing the mapping, does
  not take the campaigns and does not copy them.
* **Removing the other advertiser's mapping changes nothing** for the owner.
* **Removing the owner's mapping hands the account on.** The sync stops and
  Apostra retires its copies of the campaigns. The next sync of the advertiser
  whose mapping is oldest among those left takes the same campaigns, with the
  same campaign ids, under that advertiser. Until that sync runs, neither
  advertiser shows them. A finished campaign older than the new sync's history
  boundary is not taken over; it stays retired with the advertiser that had it.
* **Moving a single campaign between advertisers is not available.** The owner
  is an advertiser's, never a campaign's. An administrator can hand the whole
  account to another advertiser, as [described below](https://docs.apostra.com/v3/import-existing-campaigns.md#hand-the-accounts-campaigns-to-another-advertiser).

### See which advertiser owns the account's campaigns

Read the connection, `get({kind: "connection", id: connectionId})`. Its
`accounts[]` come back on that plain read, with no `include`. Each entry of
`accounts[].mappedAdvertisers[]` is one advertiser's mapping of the account, and
carries `campaignSync`. The same field is on the mappings the read returns
as `accountMappings[]`.

| Field | What it says |
| - | - |
| `owner` | `true` when this mapping's advertiser owns the account's campaigns, `false` when another advertiser does. |
| `ownerAdvertiserId` | The advertiser that owns them. The mapping's own advertiser when `owner` is `true`. |
| `ownerAdvertiserName` | That advertiser's name. |

An advertiser whose mapping says `owner: false` and shows no campaigns for the
account therefore knows why, and which advertiser has them. Your agent reads
the same field. It names the owner and nothing else about it: the owner's
campaigns, budgets and mappings stay with the owner.

`campaignSync` is `null` when no campaign sync exists for the account. That is
the case for a mapping added a moment ago, before the first sync has started,
and for a mapping on a third-party agent, whose campaigns Apostra does not sync
this way. It says who owns the campaigns today. If the owner's mapping is
removed, the account passes to the next advertiser as described above, and the
field follows.

The sync requests all supported campaign statuses, including pending-start
campaigns. A future start date does not exclude a campaign. Campaigns still
need to be readable and representable by the connected provider.

A tracked campaign reads the platform's own state, and each sync copies it
across. When the platform finishes a campaign, it reads `completed`; when the
platform moves a flight's end date forward again, it reads `active` again on
the next sync. Spotify has no completed status on a campaign, so a Spotify
campaign reads `completed` once every ad set it still has is completed or
archived, or has an end date that has passed, even while Spotify shows the
campaign itself as active or paused. A campaign archived in Spotify reads
`completed` too. A campaign with an ad set that has no end date, or an end date
still ahead, keeps its status.

A sync starts with a metadata-history boundary 30 days before it was set up.
When the existing account-scoped Enhanced Reporting activation applies at
setup, that boundary starts 365 days back instead. The subscription's stored
`backfillStart` governs newly discovered terminal campaigns: their provider
update timestamp, or creation timestamp when no update timestamp is available,
must fall on or after that boundary. Already mirrored campaigns retain later
terminal transitions even when they predate the boundary.

This metadata boundary is separate from delivery/reporting history. Syncing
does not enable Enhanced Reporting or grant a one-year reporting entitlement.
[Enhanced Reporting](https://docs.apostra.com/v2/buyer/storefronts/tasks/set-enhanced-reporting.md) has its
own account-scoped activation and billing rules.

Organisation/manager accounts and publisher-identity accounts are not synced.
Sync covers adapter-provider connections; for third-party source connections
see [connect and map an account](https://docs.apostra.com/v2/buyer/campaigns/directed-campaigns.md#connect-and-subscribe-an-account).

### Hand the account's campaigns to another advertiser

An administrator of your account (the role `ADMIN` or `SUPER_ADMIN`) can make
another advertiser the owner, so the campaigns appear under it instead. The
advertiser must already map the ad account, and the call never creates a
mapping. Call `save_connection` with the connection, the ad account and the
advertiser that should own the campaigns:

```json theme={null}
{
  "name": "save_connection",
  "arguments": {
    "connectionId": "26",
    "advertiserMapping": {
      "advertiserId": "8848",
      "accountId": "88",
      "state": "mapped",
      "campaignSync": { "owner": true }
    }
  }
}
```

The campaigns and the sync move together, in one step. They keep their campaign
ids, nothing is copied, and neither advertiser is ever without them. Nothing
changes in the ad platform. The previous owner's mapping stays and now reads
`campaignSync.owner: false`, naming the new owner.

The result has `action: "campaign_sync_owner_updated"`, the advertiser that
owned the campaigns before as `previousOwner`, and the connection read back, so
every mapping shows its new `campaignSync`. The call states an end state, so
sending it again changes nothing and answers `campaign_sync_owner_unchanged`.

* **Everyone in the account is told.** The people in your account see a notice
  in the app and receive an email, and so does the account's notification
  address. It names the ad account, the advertiser the campaigns left, the
  advertiser that has them now and how many moved. The notice
  (`storefront_adapter_sync.owner_changed`) asks for nothing and cannot be
  muted. No approval is needed, because no spend moves.
* **It lasts as long as an owner's mapping does.** The new owner keeps the
  campaigns until its mapping is removed. Then the sync stops and the advertiser
  with the oldest remaining mapping takes over, as described above. The campaigns
  do not go back to the earlier owner on their own.
* **Nothing is half moved.** If any campaign cannot move, the call is refused,
  names the problem and moves none.

The call is refused, with a message that says what to do, when:

| Refused when | What to do |
| - | - |
| The caller is not an `ADMIN` or `SUPER_ADMIN` of the account. | Ask an administrator. |
| The advertiser has no live mapping to the ad account, or its mapping is unreachable. | Map the ad account to the advertiser first, then hand the campaigns over in a separate call. |
| The ad account has no campaign sync yet (`campaignSync` reads `null`). | Wait for the sync to start, a few minutes after the first mapping, and try again. |
| The account is syncing, or a change to one of its campaigns has not settled with the ad platform. | Try again in a few minutes. |
| A campaign carries creatives, audiences, tracking, UTM or data delivery settings, or creative collections that belong to its current advertiser. | Remove them from the campaign, then hand the campaigns over. The message names the campaign. |
| `owner` is `false`, or the call sends `ownerAdvertiserId` or `ownerAdvertiserName`. | An account that syncs always has an owner. Make another advertiser the owner instead. The server sets the owner's id and name. |
| The call comes from a media company, organization or developer account. | Use a buyer account. |

## How quickly a change in the ad platform appears

Apostra reads each subscribed ad account on a schedule, about every 15 minutes.
Its target is that a campaign, ad set or ad you create or edit in the ad
platform appears in Apostra within **30 minutes**. Most changes appear sooner.
This is a target Apostra measures, not a guarantee: it holds when Apostra's
latest read of the account succeeded and Apostra's scheduled reads are keeping
up.

`lastSyncedAt` on the subscription is when Apostra last attempted a read of the
account, and `lastSyncStatus` says whether it succeeded. Use them to see how
old Apostra's view is.

For Meta, Apostra also asks Meta to notify it when a campaign, ad set or ad is
created or changed, and reads the account as soon as a notification arrives. A
notification can bring a change in within minutes. It is not what the 30 minutes
rests on: Meta does not guarantee delivery or timing, so the scheduled read is
the bound.

What the target does not cover:

* **A read that failed.** If Apostra could not read the account,
  `lastSyncStatus` is `ERROR` and `lastSyncedAt` is the time of that failed
  attempt, not of a good read. Apostra retries on the next scheduled read. Until
  one succeeds, what you see is as old as the last successful read.
* **Reads running behind.** If Apostra has more accounts to read than a
  scheduled pass can finish, some accounts wait longer than 30 minutes.
* **Campaigns Apostra can't represent.** A campaign the provider returns in a
  form Apostra cannot read is not shown, whatever the schedule.
* **Delivery and spend.** The target is about campaign metadata. Delivery
  reporting has its own timing.

## See how much of the account Apostra shows

Apostra records what each read of an ad account saw. Read it with
`get({kind: "connection", id: connectionId})`, which returns `accounts[]` with no
`include`. Each entry of `accounts[]` carries `campaignCoverage` once the account
has synced. Buyers and Apostra support staff read the same field. It is absent
for an account with no campaign subscription, and until the account's first sync
after Apostra began recording coverage.

| Field | What it says |
| - | - |
| `platformCount` | Campaigns the ad platform returned at the last sync, in any status. `null` when the read failed. |
| `platformActiveCount` | The part of `platformCount` that has not ended. |
| `mirroredCount` | Campaigns Apostra shows as tracked campaigns. |
| `leftOut.byReason` | Campaigns Apostra does not show, counted by reason. Complete: it counts every campaign left out. A reason with none is absent. |
| `leftOut.byField` | Campaigns left out because of a failure, counted by the adapter `field` that left them out, for example `buys.optimization_projection.objective_unsupported`. It counts campaigns beyond the listed entries, and `byReason` stays the complete total: if an account has more than 100 distinct combinations of reason and field, the smallest are counted in `byReason` only. Absent when none failed. |
| `leftOut.entries` | Up to 50 of the campaigns or failures behind the counts: `reason`, plus `campaignId` and `field` when they apply. Use `byReason` and `byField` for totals, never the length of this list. |
| `state` | `full`, `partial` or `error`, defined below. |
| `cause` | Present unless `state` is `full`. Who must act and what they do: `class`, `owner` and `action`, defined in [Who acts](https://docs.apostra.com/v3/import-existing-campaigns.md#who-acts-when-an-account-is-not-full). |
| `syncedAt` | When the sync the numbers describe finished. |

So "Meta has 12, we show 9, 3 left out" reads as `platformCount: 12`,
`mirroredCount: 9` and the three reasons in `leftOut.byReason`.

`state` is `full` when nothing is missing beyond the history window, `partial`
when at least one campaign is left out for another reason, and `error` when
Apostra could not read the platform at all. Do not report an account as fully
imported unless `state` is `full`.

### Why a campaign is left out

| Reason | What it means | What to do |
| - | - | - |
| `outside_history_window` | An ended campaign older than the account's history boundary (30 days before the subscription, or 365 days with Enhanced Reporting). This is expected and does not make the account `partial`. | Nothing. The boundary is described above. |
| `deferred_by_discovery_cap` | The platform has more new campaigns than one read takes. This one waits for a later read. | Nothing. It appears on a later sync. |
| `provider_read_failed` | The platform did not answer for the whole account, so `platformCount` is `null`. `lastSyncStatus` is `ERROR`. | Read `cause`: it says whether the customer reconnects, fixes the advertiser mapping, or whether Apostra or the platform acts. |
| `campaign_unreadable` | The platform answered, but this campaign has a setting Apostra cannot represent, such as targeting by language or excluded geography on Meta. `campaignId` names it and `field` is the setting. With `field` `unexpected_read_error`, Apostra hit an error it did not expect while reading this one campaign on any platform; the other campaigns in the account were read and shown. | Manage that campaign in the ad platform. For `unexpected_read_error` there is nothing for the buyer to change: Apostra investigates. Tell the buyer which campaign and why; do not blame the others. |
| `mirror_write_failed` | Apostra read the campaign but could not save it. | The next sync retries it. If it persists, contact support with the `campaignId`. |
| `retirement_failed` | A campaign that ended or was removed on the platform is still shown, because Apostra could not retire it. | The next sync retries it. If it persists, contact support with the `campaignId`. |
| `unlisted` | Only on a record written before every failure was counted by reason: more than 50 campaigns failed at once and their reasons were not kept. The next sync replaces the record, so it does not appear after that. | Wait for the next sync. |

### Who acts when an account is not full

Every account that is not `full` carries a `cause`. It names who has to act and
what they do, so an agent can tell the customer their step instead of guessing.
`owner` is `customer` (the person who connected the account), `platform` (the ad
platform) or `scope3`. When the cause is `account_access_denied`, Apostra also
notifies the customer once, in the app and by email, and notifies again if the
account is denied again after it has read as `full`. A lost authorisation is
announced by the existing credential notification instead.

| `cause.class` | `owner` | `action` | What it means and what to do |
| - | - | - | - |
| `credential_unusable` | `customer` | `reconnect` | The connection's authorisation is expired, revoked, or lacks a permission the read needs. Ask the customer to reconnect the platform and grant every permission it asks for. Apostra cannot refresh a revoked authorisation. |
| `account_access_denied` | `customer` | `fix_advertiser_mapping` | The connection works, but the platform will not show it this ad account. Either the person who connected lacks access to that account, or the account is mapped to the wrong advertiser. Ask the customer to reconnect as a user with access to the ad account, or to map the ad account they meant. |
| `platform_rate_limited` | `platform` | `wait_for_platform` | The ad platform asked Apostra to slow down. Nothing to do: Apostra reads the account again on its own. For Meta it waits out a short request within the same read, and after a longer one it leaves the account alone until Meta says access is back (an hour at most). |
| `campaign_not_readable` | `scope3` | `scope3_investigates` | The platform answered, but Apostra cannot read or represent a campaign. `leftOut.entries` names it. Do not ask the customer to change anything. |
| `sync_incomplete` | `scope3` | `scope3_investigates` | Apostra read the campaigns but could not save or retire some, or left some for a later read. The next scheduled read retries. |
| `unclassified` | `scope3` | `scope3_investigates` | Apostra has no mapping for what went wrong, so Apostra owns it. An ad platform reporting itself unavailable lands here, because Apostra cannot yet tell the platform's outage from its own failure to read the answer. |

A cause that Apostra does not recognise is always `scope3`. Apostra never leaves
an account without a named owner.

### Where the customer sees their step

When the owner is `customer`, the connection says so without anyone opening the
coverage. On `get({kind: "connection", id})`, the advertiser's entry in
`controlPlane.activation.advertisers` carries `requiredAction` (`reconnect` for
`credential_unusable`, `map_account` for `account_access_denied`) and a
`syncCause` with the `class`, the `action` and the `accountId` (Apostra's id for
the ad account that could not be read; the connection's account list can leave
it out, for example on another page). The connection's own `requiredAction`
reports it too, and
the text read prints a "Needs your action" line naming the ad account, the
problem and the fix. Apostra reports a cause here only when the customer is the
one who fixes it, and a step it already owes the advertiser, such as completing
setup, stays ahead of it. The account's activation `state` does not change,
because the seller account is still active; only reading the ad account is
blocked.

## The creatives of your Meta ads

When Apostra syncs a Meta ad account, it also brings the creatives of the
account's ads into the Library. You do nothing and change no setting: a creative
made in Meta Ads Manager, for an ad in a campaign Apostra syncs, becomes a
creative in the Library of the advertiser that owns the account's campaigns (see
[When two advertisers map the same ad account](https://docs.apostra.com/v3/import-existing-campaigns.md#when-two-advertisers-map-the-same-ad-account)).
It is never added to another advertiser's Library, or to another customer's.

What is imported, and what is not:

| Meta creative | Library creative |
| - | - |
| A single image ad | An `image` creative with the image, the primary text, headline, description and call to action, and the link. |
| A single video ad | A `video_hosted` creative with the video, the primary text, headline and call to action, and the link. AdCP's video has no description, so Meta's is not carried. |
| A dynamic creative (a pool of images, videos and words, or several headlines and texts on one image or video) that Apostra can read as an AdCP `responsive_creative`, and that sends clicks to one URL | A `responsive_creative` creative with each image, video and text, saved as a draft because a responsive creative needs a logo and a Meta dynamic creative has none. |
| A carousel, a catalog ad, an ad that promotes an existing post, or a dynamic creative Apostra cannot read as a responsive creative, such as one whose click opens a Meta Shop or places a phone call, or whose pool sends clicks to several landing pages | Nothing. The ad stays in Meta and is not imported. An AdCP `responsive_creative` has no shop or call destination and a Library creative has one click-through URL, so importing these would change where a click goes or drop a link. |

Other creatives stay out too: a single image whose creative names only a
picture link rather than an image Meta holds, an ad whose landing page link
carries a token that neither Apostra nor Meta fills, a file larger than 30 MB, a
creative whose files total more than 60 MB or number more than 10, and a
creative Meta no longer has. They are not an error. They stay as they are in
Meta, and Apostra tries again later where the cause can pass.

An ad whose landing page link carries Meta's own dynamic URL parameters, such as
`{{campaign.name}}` or `{{ad.id}}`, is imported with the link exactly as you
wrote it in Meta. Meta fills those parameters when it serves the ad, so the
creative records that they are Meta's. Because only Meta fills them, that
creative can be sent to Meta only. When you send it to another seller, Apostra
leaves that creative out, delivers the others in the same send, and reports
which creative it left out and why, naming the parameters. You can still edit the
creative, keeping the parameters, or edit the link to remove them. See
[Landing page macros](https://docs.apostra.com/v3/landing-page-macros.md#metas-own-dynamic-url-parameters).

* **Which ads.** The ads of the campaigns Apostra syncs: live campaigns, and
  campaigns that ended within the history window of the sync, 30 days, or 365
  days when the account has Enhanced Reporting (see [above](https://docs.apostra.com/v3/import-existing-campaigns.md#how-campaigns-get-here)).
* **Each unique creative once.** Meta often holds several creatives that run the
  same image and the same words, for example when an ad is duplicated. Apostra
  stores them as one Library creative, and every one of those Meta creatives
  belongs to it. The creative is named as it is in Meta.
* **The media is copied.** Meta's links to its images and videos expire, so
  Apostra copies each file when it imports the creative.
* **It comes in over several syncs.** Each sync imports up to 20 creatives and
  stops after about two minutes, or as soon as Meta says the ad account is close
  to its limit, so an account with many creatives fills over several syncs, about
  15 minutes apart. Importing starts after the sync has recorded what it read, so
  it never holds back your campaigns appearing.
* **Ads report your creative.** An imported creative is linked to its Meta
  creative, so [per-ad delivery](https://docs.apostra.com/v3/per-ad-delivery.md) names it from the next
  read, with `creative_in_library: true`.

An imported creative is an ordinary Library creative with `source: "connected"`.
It is not attached to any campaign: the ad already runs in Meta, and attaching it
would make Apostra send a second copy. Archive it as you would any creative;
the ad keeps running in Meta.

## Change a campaign synced from Meta

A campaign synced from a Meta ad account is changed with the same calls and
permissions as a campaign Apostra built: `save_campaign` with its `campaignId`,
or `save_media_buy` with its `mediaBuyId`. A synced campaign has one media buy,
and the two calls change the same campaign. There is no separate take-over step.

This is available to accounts in the buyer beta. For any other account a
tracked campaign stays read-only: `save_campaign` refuses a change with
`TRACKING_CAMPAIGN_WRITE_REJECTED`, and `save_media_buy` refuses it as a change
to a campaign synced from an ad account.

The first change Meta accepts **takes the campaign over**:

* Apostra reads the campaign from Meta at that moment and records it as the
  media buy's first revision, the baseline. Every later change, made through
  Apostra or in Meta, is compared with it.
* The campaign and its media buy read `handling: "managing"` from then on.
  They keep their ids, and nothing is copied or created again in Meta.
* The change is then sent to Meta through the ad account's connection.
* The response says so in its text and carries `takenOver: true`. Later
  changes do not carry it.

A change Meta refuses takes nothing over: the campaign stays tracked, as it was.
If Meta cannot be read when the change arrives, nothing is taken over or changed,
and the call returns `SERVICE_UNAVAILABLE`; retry shortly. If the outcome of a
change is unknown, for example because Meta timed out, the campaign stays taken
over, because Meta may hold the change. The error says so and carries
`takenOver: true`.

What a change can carry:

| Field | `save_campaign` | `save_media_buy` | Sent to Meta as |
| - | - | - | - |
| Name | `name` | `name` | The campaign's name. |
| Pause or resume | `isPaused` | `isPaused` | The campaign's status. |
| Flight | `flight` | `flight` | The ad sets' start and end times. |
| Budget | `budget.total`, `budget.currency` | `budget.total`, `budget.currency` | See below. |

Any other field is refused with `VALIDATION_ERROR` naming it, and nothing is
taken over or changed. That includes the budget's `dailyCap` and `pacing`,
creatives, targeting, goals, bidding, `products` on the media buy, archiving
and cancelling.

A budget in Apostra is a lifetime total. Apostra reads the campaign from Meta
and sends the budget where Meta holds one:

| Where Meta holds the budget | What happens |
| - | - |
| On the campaign, as a lifetime budget | The budget becomes the campaign's lifetime budget. |
| On the campaign's one ad set, as a lifetime budget | The budget becomes that ad set's lifetime budget. |
| As a daily budget, on the campaign or its ad set | Refused with `VALIDATION_ERROR` on `budget`: the campaign uses a daily budget on Meta. Change it in Meta. |
| On several ad sets | Refused with `VALIDATION_ERROR` on `budget`, naming the split. Change each ad set's budget in Meta. |

A refused budget changes nothing in Meta and takes nothing over. The budget's
`currency` must be the ad account's currency, which the campaign reads as its
own.

After take-over:

* **Status** still follows the ad account's sync, as before.
* **A change someone makes in Meta** shows as drift against the baseline, and is
  never copied over Apostra's record.
* **Settings Apostra cannot represent** stay exactly as Meta holds them, and
  stay named in `unrepresented`. Advantage+ audience stays as the buyer set it
  in Meta, including when a paused campaign is resumed through Apostra.
* **Reading back the change:** if Meta accepted a change but could not be read
  back straight away, the campaign shows the change as requested, and the next
  sync replaces it with what Meta holds. The response says so.

Only Meta campaigns can be taken over today. A change to a campaign synced from
another platform is refused with `CAPABILITY_NOT_SUPPORTED`.

## When campaigns are missing

1. Use `search({kind: "connection"})` to find the connected platform, then
   `get({kind: "connection", id: connectionId})` to read its discovered accounts
   and advertiser mappings. Follow account and mapping pagination when needed.
2. Match the buyer's ad-platform account ID against `accounts[].externalAccountId`.
   If the account has no advertiser mapping, explain that mapping it to an
   advertiser starts the sync. Do not guess IDs.
3. If the account is mapped, wait for the next sweep (up to 15 minutes) and
   read back as below. Report sync errors the read returns instead of
   inferring that the account is empty.

`save_directed_campaign_subscription` still accepts an explicit subscription
for a mapped account, with the account's `connectionId` and
`providerAccountId` (Apostra's connection-account ID, not the ad platform's
own ID) and an `advertiserId` mapped to it. It is no longer needed to start
sync, and it will be retired. Its `unsubscribe: true` option stops the sync,
but the next sweep starts it again while the account is still mapped. To stop
syncing an account, remove its mapping.

## Read back before reporting success

After the sync has run, repeat
`search({kind: "campaign", filter: {advertiserId, campaignMode: "tracked"}})`
and follow its pagination. Inspect the returned campaigns with
`get({kind: "campaign", id})` to verify their identity and flight dates.
Use explicit campaign status filters when terminal or archived campaigns are
also requested; the default saved search returns non-terminal campaigns.

A sync's `mirrored` count records sync work, not a verified list of
newly imported campaigns. Report names, counts and future dates only from
actual read-back. If more than one provider account maps to the advertiser,
do not attribute every returned campaign to the requested account without
matching its provider identity.

Distinguish these outcomes:

* **No saved match:** the requested campaign is not in the saved search results.
  Its presence in the native ad account has not been established by that search.
* **No native match:** a successful, complete provider sync and subsequent
  read-back found no matching eligible campaign. State the account, requested
  filters and history boundary; do not claim inventory outside that scope.
* **Unavailable or unsupported:** provider enumeration failed, was incomplete,
  or is unsupported. A sync with errors or zero mirrors does
  not prove the account is empty. Existing valid mirrors survive failed or
  incomplete snapshots, and the worker retries the subscription.
* **Some campaigns left out:** a Meta campaign that Apostra cannot read at all,
  for example one with a budget set at both the campaign and the ad set, is not
  mirrored, but the rest of the ad account is. The sync still reports success
  and the saved search shows fewer campaigns than the native ad account. Do not
  report the account as fully imported, and do not blame the other campaigns for
  the missing one.
* **Audience expansion:** Meta lets an ad set deliver beyond the audience it
  states. `get({kind: "media_buy", id})` reports it on each package of a synced
  Meta campaign as `targeting_overlay.audience_expansion`, whether it is on or
  off. It follows the shape of the AdCP audience expansion proposal
  ([adcontextprotocol/adcp#9094](https://github.com/adcontextprotocol/adcp/issues/9094)),
  which AdCP has not adopted yet, so it is Apostra's extension for now: AdCP
  callers read the same object under `ext.apostra.audience_expansion` on the
  package. `enabled: true` means Meta may deliver outside the stated audience,
  and delivery to people outside it is expected, not a targeting mismatch. An ad
  set that turns on Advantage+ audience reads `enabled: true`, with `beyond`
  naming what Meta may go beyond (`demographics`, `audience_include`,
  `signal_targeting_groups` and `seller_criteria`, for the ones the ad set states).
  Its age range is Meta's suggestion, not a limit: it is under
  `suggestions.demographics.age`, and the age limit stays Meta's real minimum and
  maximum age (the maximum is fixed at 65), so do not state the suggestion as the
  audience's age. An ad set with Advantage detailed targeting set to
  `expansion_all` reads `enabled: true`, with `beyond` including
  `seller_criteria`: Meta may go beyond the interests and behaviours listed. An ad
  set with neither reads `enabled: false`. Meta has no narrow, balanced or broad
  setting, so `level` is not set. Apostra only reads this on a synced Meta
  campaign; it does not set expansion when it creates one. LinkedIn (audience
  expansion) and Pinterest (auto-targeting) report the same field with `enabled`
  alone, on or off, on every package. A buy Apostra creates on LinkedIn or
  Pinterest has expansion off, unless the product is Pinterest Performance+, which
  expands by design, and it fails to create if the platform reads the setting back
  on. A campaign that already existed keeps whatever the platform holds.
* **Some settings left out:** a Meta campaign that the buyer built in Meta, and
  whose ad sets target by a setting Apostra cannot represent (language, excluded
  geography, behaviours, cities targeted with a radius, Advantage+ automation
  beyond Advantage+ audience, placement controls, or a targeting key Apostra
  does not recognise), or whose ad sets bid with a cost cap or a minimum return on ad
  spend, is mirrored with its name, status, budget, dates, goal and the
  targeting Apostra can represent. The settings it cannot represent are left out of
  Apostra's copy. `get({kind: "media_buy", id})` names each one in
  `unrepresented` as a `{ path, reason }`, on the media buy and on the package
  that holds it (for example `packages[<ad set id>].targeting.locales` with
  `unsupported_dimension`); the field is absent when there are none. Every such
  setting on an ad set is named, not only the first. Two Meta audience
  settings are not left out: they are read as audience expansion (the
  next item). A range that disagrees with the age limits when Advantage+
  audience is off is still named as
  `packages[<ad set id>].targeting.age_range` with `unsupported_dimension`, and so
  is an Advantage detailed targeting value other than `expansion_all` and `none`
  (as `packages[<ad set id>].targeting.targeting_optimization` with
  `unknown_dimension`). A bidding
  setting is named as `packages[<ad set id>].bidding` with
  `unsupported_dimension`, and the package carries no `bid_price`, so do not
  state its bid or cost target. Meta placements are not left out. A package's
  `targeting_overlay.placement_selection` states the placements Meta holds, in
  AdCP's own shape: `{ mode: "selected", placement_refs }` for a set the buyer
  chose in Meta, naming each Facebook, Instagram, Messenger or Threads placement
  (including Marketplace, the right-hand column, Notifications and Explore), and
  `{ mode: "default" }` when the ad set uses automatic placements (Advantage+
  placements), which is not an unrecognised setting. Audience Network is third-party
  app inventory, not a publisher placement, so it is not in
  `placement_selection`. It is carried in the named extension
  `targeting_overlay.ext.scope3.meta_audience_network` as
  `{ included: true, positions }`, where `positions` is `classic` and
  `rewarded_video` as Meta lists them and is absent when Meta chooses them.
  Meta has retired two Facebook positions, Instant Articles and Video Feeds, and
  an ad set made before they ended can still list them. Nothing delivers there,
  so `placement_selection` lists the placements the ad set names without them, and
  each retired position is named in `unrepresented` as
  `packages[<ad set id>].targeting.facebook_positions.instant_article` or
  `facebook_positions.video_feeds`, so you can tell the buyer the ad set still
  lists it. An ad set whose only Facebook positions are retired has no
  `placement_selection`, and is named as below.
  When Apostra cannot state an ad set's placements exactly, the package has no
  `placement_selection` and the settings are named as before: a platform Meta
  gives no positions for (Meta chooses its positions), or a position Meta has not
  retired that has no placement. They are named as
  `packages[<ad set id>].targeting.facebook_positions.value`,
  `instagram_positions.value`, `publisher_platforms.value` or the matching `effective_` list
  Meta reads back, and the ad set's
  known placements are kept. A setting of a `flexible_spec` group other than its
  custom audiences, such as interests, is named as
  `packages[<ad set id>].targeting.flexible_spec.<n>.<setting>`. Meta's gender
  value `0` means every gender, so it names nothing and leaves `genders` empty. When Apostra cannot state the placements, a Messenger or Threads position in the placements Meta reads back is
  named as `packages[<ad set id>].targeting.effective_owned_publisher_positions`
  and left out whole.
  A package that names any is a partial copy: its
  `targeting_overlay` leaves those settings out, so do not describe the
  campaign's targeting as complete. A campaign that Apostra created is read the
  same way once someone changes an ad set's targeting or placement controls in
  Meta so that they no longer match what Apostra sent: Meta is the source of
  truth, so the buy's status, budget, dates and creatives keep updating, and
  the targeting Apostra cannot represent is named in `unrepresented`. Its
  targeting is then read as Meta holds it, and if none of it can be projected
  the package carries no `targeting_overlay` and names
  `packages[<ad set id>].targeting` with `targeting_not_projectable`. Other
  changes made in Meta to a campaign Apostra created are read the same way:

  * **Objective, goal or bidding.** The ad set is read as Meta now holds it,
    and what Apostra cannot state is named in `unrepresented`, as for a
    campaign built in Meta (see "Goals and bidding Apostra cannot fully read"
    below).
  * **An ad set added or removed.** An ad set added in Meta is read as a
    package built in Meta: it carries no `product_id`, and Apostra reports it
    as an object it did not create. An ad set removed in Meta is no longer a
    package of the buy.
  * **An ad changed.** An ad whose creative was swapped, a second ad for the
    same creative, or an ad for a creative Apostra never finished sending is
    read as Meta holds it.

  The difference from what Apostra booked shows on the media buy's drift
  `indicators` until Meta is back in line with the booking, and the buy's
  status follows Meta. A budget or flight-date change you make through
  `save_media_buy` is part of the booking, so it never shows as drift. One
  campaign that cannot be
  read never stops the others in the account from being read. A change in Meta
  to how the budget is placed, on AdCP 3.2, still leaves that campaign out as
  `campaign_unreadable`.
* **Changing a campaign with settings left out:** a change through
  `save_media_buy` never removes or alters a Meta targeting setting named in
  `unrepresented`; Apostra sends it back to Meta exactly as Meta holds it. A
  budget, flight-date or pause change goes ahead. A `products[].targetingOverlay` change
  that would replace one of those settings is refused with `VALIDATION_ERROR`
  before anything is sent to Meta, and the message names each setting by its
  `unrepresented` path: `language` covers `targeting.locales`; the excluded
  geography fields cover `targeting.excluded_geo_locations`; and any change to
  the included geography covers the regions and cities lists. Change that
  setting in Meta itself, or send the update without the targeting that covers
  it. If Meta's answer to a change no longer holds a setting exactly as it was,
  Apostra treats the change as failed and undoes it. This applies to campaigns
  Apostra created and to campaigns taken over from the ad account; see
  [Change a campaign synced from Meta](https://docs.apostra.com/v3/import-existing-campaigns.md#change-a-campaign-synced-from-meta).
* **Snap targeting left out:** a Snap campaign that the buyer built in Snap, and
  whose ad squad has targeting Apostra cannot represent, is mirrored with its
  name, status, budget, dates and creatives. Snap region ids map to an ISO
  region only through a request Apostra made, so a squad the buyer built in Snap
  is mirrored without its regions and `unrepresented` names
  `packages[<ad squad id>].targeting.geos.region_id` with
  `region_without_iso_mapping`; the rest of its targeting is kept. If the
  squad's targeting does not project at all, the package carries no
  `targeting_overlay` and `unrepresented` names `packages[<ad squad id>].targeting`
  with `targeting_not_projectable`. Do not describe such a squad's targeting as
  complete. A squad that Apostra created is read the same way once someone
  changes its targeting in Snap so that it no longer matches what Apostra sent:
  Snap is the source of truth, so the buy's status, budget, dates and creatives
  keep updating, and the targeting Apostra cannot represent is named in
  `unrepresented`. An ad squad someone adds in Snap to a campaign Apostra
  created is read the same way as a squad built in Snap: it carries no
  `product_id`, so it shows as one Apostra did not create, and the rest of the
  buy keeps updating. An ad squad removed in Snap is no longer a package of the
  buy.
* **Campaigns on Meta's original objectives:** Meta still serves campaigns built
  on the objectives that predate its outcome-based ones. Where Meta defines one
  outcome-based objective for an original objective, Apostra reads the campaign
  as that one: `LINK_CLICKS` as traffic; `BRAND_AWARENESS`, `REACH`,
  `VIDEO_VIEWS` and `STORE_VISITS` as awareness; `POST_ENGAGEMENT`,
  `PAGE_LIKES`, `EVENT_RESPONSES` and `MESSAGES` as engagement;
  `LEAD_GENERATION` as leads; `APP_INSTALLS` as app promotion. Where Meta
  defines none that the campaign alone determines (`CONVERSIONS`, whose
  replacement depends on the ad set's optimization goal, and
  `PRODUCT_CATALOG_SALES`, `LOCAL_AWARENESS` and `OFFER_CLAIMS`), the campaign
  is mirrored with its name, status, budget, dates and targeting, its packages
  carry no `optimization_goals`, and `unrepresented` names `objective` with
  `unknown_dimension` once on the media buy. Do not state such a campaign's
  goal. If the ad set's goal then does not fit the replacement objective, the
  campaign is left out as `campaign_unreadable` with the field that says why.
* **Goals and bidding Apostra cannot fully read:** a Meta campaign the buyer
  built in Meta, whose ad set optimizes for something Apostra cannot state, is
  still mirrored. `unrepresented` names what was left out, on the media buy and
  on the package, and the package carries only what Apostra read:
  * `packages[<ad set id>].optimization_goals`: the goal cannot be stated, so
    the package carries no `optimization_goals`. The reason is
    `unsupported_dimension` when Meta returned no event source for a conversion
    goal, and `unknown_dimension` when the conversion event or the optimization
    goal itself is one Apostra does not recognise. Do not state the campaign's
    goal.
  * `packages[<ad set id>].bidding`: a bid strategy Apostra does not recognise,
    or an amount Meta returned that Apostra cannot read. The goal is kept and
    the package carries no `bid_price`.
  * `packages[<ad set id>].billing_event`: the ad set's goal is read from the
    ad set itself, but its billing event is not the one Apostra pairs with that
    goal and the campaign's objective. The goal is kept.
  * `packages[<ad set id>].targeting` with `targeting_not_projectable`: Meta
    returned the ad set with no targeting at all, or with targeting that
    Apostra cannot project and cannot name setting by setting, so the package
    carries no `targeting_overlay`. The rest of the campaign is still read.
    Do not describe the ad set as untargeted.
* **Unauthorised:** the connection or advertiser is inaccessible, or provider
  authorisation failed. Explain the access or reconnect action; do not infer
  that the campaigns are absent or retry as a different account.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.