Metrics

Soundlink cohort retention

Cohort retention for a soundlink: one row per cohort date that has first plays (dates with no first plays have no row), where the cohort date is the UTC date listeners first played via the soundlink. A listener’s cohort date is their earliest first play across all countries. Conforms to the soundlink_cohort_retention_daily v1.0 schema. All rows are returned in data.items (one per cohort date), so there is no pagination.

Retention definitions:

returned_on_day_N: listeners from the cohort who played again on exactly day N after their first play.
retention_by_day_N: share of the cohort (cohort_size) who played again on any day from 1 to N (end-day, cumulative). Each listener is counted once, so the by-day rate never decreases within a row.
A day-N value is null until day N has passed for that cohort date.

Known limitation: end-day rates are cumulative per listener, so whether day-3 returners also returned on day 2 is not recoverable from the end-day columns. Use the exact-day returned_on_day_N columns for day-by-day behaviour.

soundlink_target_isrc is currently always null.

Date range: startDate / endDate filter the cohort date (both inclusive). If you omit both, a recent window ending today is used. A range that is too wide returns 400 invalid_query_parameter.

Requires the soundlinks:read scope. Accepts API key or OAuth Bearer.

GET

soundlinks

{soundlinkId}

metrics

retention

Soundlink cohort retention

curl --request GET \
  --url https://api.getsoundlink.com/v1/soundlinks/{soundlinkId}/metrics/retention \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.getsoundlink.com/v1/soundlinks/{soundlinkId}/metrics/retention"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.getsoundlink.com/v1/soundlinks/{soundlinkId}/metrics/retention', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": {
    "schemaVersion": "1.0",
    "items": [
      {
        "provider": "soundlink",
        "account_id": "<string>",
        "schema_version": "1.0",
        "cohort_date": "2023-12-25",
        "cohort_date_timezone": "UTC",
        "exported_at": "2023-11-07T05:31:56Z",
        "soundlink_id": "V1StGXR8_Z5jdHi6B-myT",
        "soundlink_name": "<string>",
        "soundlink_target_type": "track",
        "cohort_size": 1,
        "returned_on_day_1": 1,
        "retention_by_day_1": 0.5,
        "returned_on_day_2": 1,
        "retention_by_day_2": 0.5,
        "returned_on_day_3": 1,
        "retention_by_day_3": 0.5,
        "returned_on_day_4": 1,
        "retention_by_day_4": 0.5,
        "returned_on_day_5": 1,
        "retention_by_day_5": 0.5,
        "returned_on_day_6": 1,
        "retention_by_day_6": 0.5,
        "returned_on_day_7": 1,
        "retention_by_day_7": 0.5,
        "soundlink_target_isrc": "<string>",
        "soundlink_target_spotify_track_id": "<string>",
        "soundlink_target_playlist_id": "<string>"
      }
    ]
  },
  "meta": {
    "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

Authorizations

Authorization

string

header

required

Pass your Soundlink sk_* API key as a Bearer token: Authorization: Bearer sk_<prefix>_<token> (not an OAuth token; see oauthBearer for that). Accepted on all Public API operations. Send only one Authorization header per request.

Path Parameters

soundlinkId

string

required

Soundlink identifier (URL-safe string, same ID used in the public sndl.ink URL)

Query Parameters

startDate

string<date>

Inclusive start date (YYYY-MM-DD). When omitted, the default depends on the endpoint: campaign overview and paginated breakdown use the campaign start date; engagement and JSONL export endpoints use the last 90 days ending today (see each operation).

endDate

string<date>

Inclusive end date (YYYY-MM-DD). Defaults to today.

Response

Cohort retention rows (soundlink_cohort_retention_daily schema), sorted by cohort_date ascending.

data

object

required

Show child attributes

meta

object

required

Show child attributes

Soundlink cohort retention

curl --request GET \
  --url https://api.getsoundlink.com/v1/soundlinks/{soundlinkId}/metrics/retention \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.getsoundlink.com/v1/soundlinks/{soundlinkId}/metrics/retention"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.getsoundlink.com/v1/soundlinks/{soundlinkId}/metrics/retention', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": {
    "schemaVersion": "1.0",
    "items": [
      {
        "provider": "soundlink",
        "account_id": "<string>",
        "schema_version": "1.0",
        "cohort_date": "2023-12-25",
        "cohort_date_timezone": "UTC",
        "exported_at": "2023-11-07T05:31:56Z",
        "soundlink_id": "V1StGXR8_Z5jdHi6B-myT",
        "soundlink_name": "<string>",
        "soundlink_target_type": "track",
        "cohort_size": 1,
        "returned_on_day_1": 1,
        "retention_by_day_1": 0.5,
        "returned_on_day_2": 1,
        "retention_by_day_2": 0.5,
        "returned_on_day_3": 1,
        "retention_by_day_3": 0.5,
        "returned_on_day_4": 1,
        "retention_by_day_4": 0.5,
        "returned_on_day_5": 1,
        "retention_by_day_5": 0.5,
        "returned_on_day_6": 1,
        "retention_by_day_6": 0.5,
        "returned_on_day_7": 1,
        "retention_by_day_7": 0.5,
        "soundlink_target_isrc": "<string>",
        "soundlink_target_spotify_track_id": "<string>",
        "soundlink_target_playlist_id": "<string>"
      }
    ]
  },
  "meta": {
    "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

System

Wallet

Campaigns

Soundlinks

Videos

Soundlink cohort retention

Authorizations

Path Parameters

Query Parameters

Response