Skip to main content
Use the Campaigns API to discover which campaigns belong to your organization and pull metadata for reporting joins.

​
List campaigns

GET /v1/campaigns Requires campaigns:read. Supports pagination:
Walk pages until pagination.page >= pagination.totalPages.

​
Campaign detail

GET /v1/campaigns/{campaignId} Returns full metadata for one campaign: name, status, target type (track or playlist), dates, and identifiers you need to join metrics rows. Both list and detail rows include generation — a resource version for the campaign (1 Stripe/legacy, 2 managed, 3 wallet). Only generation 3 can be managed via the API (budget changes, tier updates, stop). Both list and detail rows include campaignUrl — a logged-in insights URL (/orgs/{organizationId}/insights/{smartLinkId}). It uses the smart link id, not the campaign id. Both list and detail rows include artistId, artistName, trackId, playlistId, and trackName (nullable). artistId is the follow-attribution artist. trackId / playlistId identify the promoted Spotify target (one is set, the other is null). Use the campaignId from the list response in all /metrics/* paths.

​
Typical sync flow

  1. Daily: GET /v1/campaigns — upsert catalog
  2. Daily: export or paginated metrics per active campaign
  3. Warehouse: join metrics on campaign_id

​
Organization scope

Your organization is determined only from the API key (or OAuth token). You never pass an organization id in query params.
  • Campaign list and detail JSON uses organizationId.
  • Metrics JSONL / warehouse rows use account_id for the same organization UUID. Join catalog to metrics on campaign_id.
Node.js: soundlink.campaigns.listAll() — TypeScript SDK. DuckDB or BigQuery: warehouse connector.

​
Next

Warehouse connector · Campaign metrics → JSONL exports