> ## 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

> Find existing campaigns, including future-start campaigns, and bring them into Apostra with your confirmation.

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 should explain the import option and ask for your confirmation.

## What importing does

`save_directed_campaign_subscription` imports campaigns created in a connected
ad platform, including campaigns created manually in Spotify Ads Manager. They
appear as read-only **tracked campaigns** in Apostra. The ad platform remains
the source of truth: subscribing does not create, edit, launch, pause or cancel
its campaigns.

Importing saves an ongoing subscription for the selected account and mapped
advertiser, then immediately attempts a campaign metadata sync. It is a write
in Apostra, so the agent must explain this scope and get your confirmation
before calling it. Worker sweeps reconcile subsequent changes every 15 minutes
by default. Subscription does not import delivery history.

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.

An ordinary subscription starts with a metadata-history boundary 30 days
before subscription setup. 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. Subscribing
does not enable Enhanced Reporting or grant a one-year reporting entitlement.
[Enhanced Reporting](/v2/buyer/storefronts/tasks/set-enhanced-reporting) has its
own account-scoped activation and billing rules.

## Resolve the account before importing

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`.
   Pass that row's internal `accounts[].id` as `providerAccountId`, and the
   connection's `id` as `connectionId`. Despite its name, `providerAccountId`
   takes Apostra's connection-account ID, not Spotify's UUID. The top-level
   `accountId` selects the Apostra account in which the call runs when
   `providerAccountId` is supplied.
3. Use an accessible advertiser mapped to that account for `advertiserId`.
   If the intended advertiser is ambiguous, ask the buyer. If the account is
   missing, disconnected or unmapped, explain what setup is needed instead of
   guessing IDs. Organisation/manager and publisher-identity accounts cannot
   be subscribed.
4. Explain the ongoing sync, selected account and advertiser. Wait for the
   buyer's confirmation before calling `save_directed_campaign_subscription`.

For example, **after confirmation**, using IDs returned by the reads above:

```json theme={null}
{
  "accountId": 1,
  "connectionId": "42",
  "providerAccountId": "81",
  "advertiserId": "12345"
}
```

These example IDs are not defaults. Use the IDs returned for the buyer's
account. See [connect and map an account](/v2/buyer/campaigns/directed-campaigns#connect-and-subscribe-an-account)
for setup and third-party source requirements.

## Read back before reporting success

After subscribing, inspect the returned sync errors, then 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.

The subscription'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 saved subscription with sync 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.
* **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.

To stop the sync, use the same subscription tool with `unsubscribe: true` after
explaining the change and receiving confirmation. This retires local mirrors;
it does not delete the campaigns from the provider.


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