Metrics

Campaign weekly cohort retention

Weekly cohort retention for attributed plays (listeners who reached the campaign soundlink), read from api_campaign_cohort_retention_weekly_by_country. Cohort weeks are UTC and anchored on the campaign start, not calendar Mondays. Each listener has one acquisition country.

days covers relative days 0 to 7. weeks covers relative weeks 0 to 26; week N spans days 7N to 7N+6 (week 0 streams includes day 0). Week 0 pct is the share of the cohort active on days 1 to 6 (day 0 excluded).

Only fully observed days and weeks are returned. Young cohorts have shorter, possibly empty arrays, and cells are never padded.

Omit groupBy for the global rollup (country_code is null; counts are summed over countries and pct is recomputed). groupBy=country returns one item per cohort week and country (XX when unknown).

startDate / endDate filter cohort_week (inclusive) and default to a recent window. A range that is too wide returns 400 invalid_query_parameter.

Plan requirement: Label, Enterprise, committed, and self-serve plans. Organizations on a lower plan receive 403 premium_plan_required.

Requires the metrics:read scope. A campaign outside the organization returns 404 campaign_not_found.

GET

campaigns

{campaignId}

metrics

retention-weekly

Campaign weekly cohort retention

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

import requests

url = "https://api.getsoundlink.com/v1/campaigns/{campaignId}/metrics/retention-weekly"

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/campaigns/{campaignId}/metrics/retention-weekly', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": {
    "schemaVersion": "1.0",
    "granularity": "week",
    "scope": "attributed",
    "groupBy": "country",
    "items": [
      {
        "soundlink_id": "<string>",
        "cohort_week": "2023-12-25",
        "cohort_week_timezone": "UTC",
        "country_code": "<string>",
        "cohort_size": 123,
        "days": [
          {
            "day": 3,
            "active_users": 123,
            "pct": 123,
            "streams": 123
          }
        ],
        "weeks": [
          {
            "week": 13,
            "active_users": 123,
            "pct": 123,
            "streams": 123
          }
        ]
      }
    ]
  },
  "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

campaignId

string

required

Campaign identifier (UUID)

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.

groupBy

enum<string>

Available options:

country

Response

Weekly cohort retention items, sorted by cohort_week (then country_code when grouped).

data

object

required

Show child attributes

meta

object

required

Show child attributes

Campaign weekly cohort retention

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

import requests

url = "https://api.getsoundlink.com/v1/campaigns/{campaignId}/metrics/retention-weekly"

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/campaigns/{campaignId}/metrics/retention-weekly', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": {
    "schemaVersion": "1.0",
    "granularity": "week",
    "scope": "attributed",
    "groupBy": "country",
    "items": [
      {
        "soundlink_id": "<string>",
        "cohort_week": "2023-12-25",
        "cohort_week_timezone": "UTC",
        "country_code": "<string>",
        "cohort_size": 123,
        "days": [
          {
            "day": 3,
            "active_users": 123,
            "pct": 123,
            "streams": 123
          }
        ],
        "weeks": [
          {
            "week": 13,
            "active_users": 123,
            "pct": 123,
            "streams": 123
          }
        ]
      }
    ]
  },
  "meta": {
    "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

System

Wallet

Campaigns

Soundlinks

Videos

Pixels

Campaign weekly cohort retention

Authorizations

Path Parameters

Query Parameters

Response