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

# Playlist position

> Read daily track positions on playlist campaigns from the engagement export.

Engagement export rows include `playlist_position`. On playlist campaigns, use it to see which slot each engaged track held on the campaign playlist for that day.

<Note>
  The field is available now and treated as **beta** until historical backfill for older campaign days finishes. Recent active days already have high coverage.
</Note>

## Get the data

Same endpoint as other engagement rows — no new route:

`GET /v1/campaigns/{campaignId}/metrics/engagement/export?engagementContext=playlist`

Requires the `metrics:read` scope. See [JSONL exports](/docs/jsonl-exports) for streaming and date windows.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS \
  'https://api.getsoundlink.com/v1/campaigns/{campaignId}/metrics/engagement/export?engagementContext=playlist&startDate=2026-04-01&endDate=2026-04-30' \
  -H 'Authorization: Bearer sk_YOUR_PREFIX_YOUR_SECRET' \
  -H 'Accept: application/x-ndjson'
```

Each line is a JSON object. Read `playlist_position` when `engagement_context` is `playlist`. Catalog rows always have `null`.

## What the value means

| Value       | Meaning                                           |
| ----------- | ------------------------------------------------- |
| `1`, `2`, … | 1-based slot that day (`1` = top of the playlist) |
| `null`      | Unavailable for that row — see below              |

Position comes from that day's playlist crawl for `report_date`. After the crawl lands, historical days should show a position when the track was listed.

## When `null` is expected

* **Catalog rows** (`engagement_context = catalog`) — position only applies to `playlist` rows
* **Current UTC day** — often `null` until the morning crawl finishes; it fills on the next data refresh
* **Track not on the playlist** that day, or the track could not be matched to that day's crawl
* **Historical backfill still pending** for older campaign days

Treat `null` as unavailable — not an error. If a day looks wrong after crawl coverage should be complete, contact [hello@getsoundlink.com](mailto:hello@getsoundlink.com).

## Next

[Understanding metrics](/docs/understanding-metrics) · [JSONL exports](/docs/jsonl-exports) · [API Reference](/docs/api-reference)