Skip to main content
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:
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 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:
These example IDs are not defaults. Use the IDs returned for the buyer’s account. See connect and map 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.