Analytics API: Platforms, Availability, and Limits

The LabelGrid public API serves streaming analytics through GET /analytics/summary (a composite endpoint that returns the sections you select) and standalone series endpoints such as GET /analytics/streams. This page covers the platform set, how to discover what each platform reports, reporting cadence, and the request limits.

Supported platforms

filter[platform] accepts ten values covering nine stores:

SPOTIFY, APPLE_MUSIC (ITUNES is accepted as an alias for the same store), DEEZER, BOOMPLAY, AWA, AUDIOMACK, KUGOU, KUWO, QQMUSIC

Omit filter[platform] to receive the combined view across every platform your account has data for.

Discovering availability: GET /analytics/availability

Not every platform reports every metric. The availability discovery endpoint returns the whole picture in one call:

GET /analytics/availability

{
  "data": {
    "sections": ["streams", "listeners", "saves", ...],
    "platforms": ["SPOTIFY", "APPLE_MUSIC", "DEEZER", "BOOMPLAY", "AWA", "AUDIOMACK", "KUGOU", "KUWO", "QQMUSIC"],
    "availability": {
      "streams": { "SPOTIFY": "available", "KUGOU": "available" },
      "listeners": { "SPOTIFY": "available", "KUGOU": "not_available_for_platform" }
    },
    "platform_cadence": { "SPOTIFY": "daily", "KUGOU": "weekly" }
  }
}

• sections — every analytics section key, in canonical order. This list is authoritative: it’s the same set metrics[] accepts on /analytics/summary.
• platforms — every value filter[platform] accepts.
• availability — keyed by section, then platform. Each cell is available or not_available_for_platform.
• platform_cadence — daily or weekly per platform (see Reporting cadence).

The response is static configuration — it doesn’t depend on your account, a date range, or any filter — so fetch it once and cache it. It takes no parameters and uses the same authentication and rate limits as the other /analytics/* endpoints.

The availability field on filtered requests

When you filter an analytics request by a single platform (for example filter[platform]=DEEZER), the response also carries an availability field alongside data:

• available — the platform reports this metric; data is populated as normal.
• not_available_for_platform — the platform doesn’t report this metric; data is empty. This is expected behaviour, not an error.

Standalone endpoints carry a single top-level value; /analytics/summary carries a map with one entry per requested section. Requests with no platform filter carry no availability field. Always read availability before treating an empty data as “no activity.”

What the platforms report

The matrix at a glance (call the endpoint for the authoritative, current version):

Sections	Platforms reporting them
streams	All nine platforms
listeners	SPOTIFY, APPLE_MUSIC, AUDIOMACK
saves	SPOTIFY, AUDIOMACK
skips, shares, completion-rate, lyrics-view-rate, canvas-view-rate, device-split, source-split, saves-by-tier, shares-by-country	SPOTIFY
streams-by-country	SPOTIFY, APPLE_MUSIC, DEEZER, BOOMPLAY, AUDIOMACK
streams-by-gender, streams-by-age	SPOTIFY, APPLE_MUSIC
library-adds, playlist-adds, shazams, shazams-by-city, shazams-by-state, Apple dimension sections	APPLE_MUSIC
Listener audience-composition and per-stream sections (listener-plan-mix, avg-listen-time, hour-of-day, …)	SPOTIFY
Placements (GET /analytics/placements)	SPOTIFY, APPLE_MUSIC, DEEZER

A note on listener semantics: Spotify and Apple Music report a de-duplicated daily listener count per track. Audiomack’s daily listener figure is the sum of the listener counts it reports per country and subscription tier, so a listener active in more than one slice on the same day contributes more than once.

Reporting cadence: daily and weekly platforms

Every GET /analytics/summary response carries a meta.platform_cadence map naming how often each platform reports:

• daily — one report per day: SPOTIFY, APPLE_MUSIC, DEEZER, BOOMPLAY, AWA, AUDIOMACK
• weekly — one report per week: KUGOU, KUWO, QQMUSIC

A weekly platform produces one data point per track per week, dated on the day the report covers and carrying that week’s whole total. The total is never divided across the seven days. On a daily series you’ll see one populated date per week, with no rows on the dates between.

Handle this in a consumer by reading platform_cadence rather than inferring cadence from the spacing of dates:

• Don’t treat the gap between two weekly points as missing data.
• Don’t divide a weekly point into a daily average.
• Summing the points as they are still yields the correct total for any range.

Cadence is distinct from meta.section_granularity, which states how the points of a returned series are dated (day or week). A response can carry "day" granularity and "weekly" cadence at the same time — day-dated points, one per week.

Selecting sections: metrics[] on /analytics/summary

metrics[] is required on GET /analytics/summary: name the sections you want, from 1 up to 12 per request.

GET /analytics/summary?filter[start_date]=2026-06-01&filter[end_date]=2026-06-30&metrics[]=streams&metrics[]=listeners

Requesting more than 12 keys returns a 422 asking you to split the selection. Each projection is cached independently per scope and window, so splitting a larger selection into multiple requests is cheap on repeat calls. The valid section keys are the sections list from GET /analytics/availability; an invalid metrics[] request also enumerates them in its error message.

Date-range limits

GET /analytics/summary and the standalone series and demographic endpoints accept a date range of up to 400 days — enough for a full year plus a comparison period in one request. A range over the cap returns a 422 whose error message states the limit.

Endpoint family	Maximum range
/analytics/summary and standalone series/demographic endpoints	400 days
/analytics/leaderboards, /analytics/placements	180 days

The ranking endpoints keep their own 180-day cap — and note that combining several shorter top-N windows does not reconstruct the top-N over a longer period.

Two more behaviours ship with the 400-day window:

• Requests spanning more than 90 days are metered against a second, lower rate limit in addition to the standard analytics limit (30/minute per account vs. the standard 60; partner egress-IP budgets are halved the same way). Requests of 90 days or less are unaffected. Exceeding either limit returns 429 with the usual Retry-After and X-RateLimit-* headers.
• A range within the cap can still be too heavy to compute — a very large catalog at the full span with many metrics[], for example. That returns 422 with a “narrow the date range” message. Treat it as retryable: retry with a shorter range or fewer sections. An unrelated server error still returns 500, so a 422 here reliably means “this request was too big.”

Related

• API Overview — authentication, endpoints, and the full reference
• Analytics — the analytics dashboard and what each view shows
• Connect Your AI Assistant to LabelGrid (MCP) — query your analytics in plain language