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

# Syncing campaigns

> List and detail endpoints for keeping your campaign catalog in sync.

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:

| Param      | Default | Max |
| ---------- | ------- | --- |
| `page`     | 1       | —   |
| `pageSize` | 10      | 100 |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS 'https://api.getsoundlink.com/v1/campaigns?page=1&pageSize=100' \
  -H 'Authorization: Bearer sk_YOUR_PREFIX_YOUR_SECRET'
```

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](/docs/managing-campaigns) (budget changes, tier updates, stop).

Use the `campaignId` from the list response in all `/metrics/*` paths.

## Typical sync flow

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
  A[List campaigns] --> B[Store campaign IDs]
  B --> C[Metrics overview / export per campaign]
  C --> D[Join on campaign_id in warehouse]
```

1. **Daily:** `GET /v1/campaigns` — upsert catalog
2. **Daily:** export or paginated metrics per active campaign
3. **Warehouse:** join metrics on `campaign_id` + `account_id` (your organization UUID from each row)

## Organization scope

Your organization is determined only from the API key. You never pass `organization_id` in query params — rows already include `account_id` for your org.

<Note>
  Node.js users can paginate campaigns with `soundlink.campaigns.listAll()` — see [TypeScript SDK](/docs/typescript-sdk).
</Note>

## Next

[Understanding metrics](/docs/understanding-metrics) → [JSONL exports](/docs/jsonl-exports)