API de Analytics: filtros de escopo e dados por faixa

Toda requisição de analytics cobre alguma parte do seu catálogo, e toda requisição devolve um único resultado agregado sobre essa parte. Juntas, essas duas coisas pegam muita gente de surpresa: filtre uma chamada pelo UPC de um álbum e você recebe os números do álbum, não uma linha por faixa dele. Este guia cobre os filtros que definem o escopo, o que a agregação faz com o resultado e os dois endpoints que abrem um escopo faixa a faixa.

Os filtros de escopo

Quatro filtros restringem uma requisição de analytics a parte do seu catálogo. Eles funcionam em GET /analytics/summary, nos endpoints independentes de séries e de demografia e em GET /analytics/leaderboards e /analytics/placements.

Filtro	Tipo	As faixas que ele resolve
filter[release_id]	inteiro	todas as faixas daquele lançamento
filter[isrc]	string	a única gravação que carrega aquele ISRC
filter[upc]	string	todas as faixas do lançamento com aquele código de barras
filter[artist_names][]	array de strings	todas as faixas do seu catálogo creditadas àqueles artistas

GET /analytics/streams?filter[start_date]=2026-06-01&filter[end_date]=2026-06-30&filter[upc]=0123456789012

Não envie nenhum deles e a requisição cobre todo o catálogo a que você tem acesso: é o escopo padrão de qualquer chamada de analytics.

Só um filtro vale

Os quatro são resolvidos em uma ordem fixa: release_id, depois isrc, depois upc, depois artist_names[]. O primeiro que estiver presente vence. Enviar filter[release_id] e filter[upc] juntos não cruza os dois; o UPC é simplesmente ignorado. Envie só o filtro que você realmente quer.

O que acontece quando o identificador não é seu

Os três filtros de nível de lançamento respondem de formas diferentes quando o identificador não resolve dentro do seu catálogo:

• filter[release_id] gera erro: 404 quando não existe lançamento algum com aquele id, 403 quando ele existe mas não é seu.
• filter[isrc] e filter[upc] resolvem para um escopo vazio, e a requisição é bem-sucedida com data vazio.

Por isso, quando a sua chamada parte de um identificador digitado por um usuário, teste se data veio vazio em vez de ficar esperando por um 404.

Restringindo a uma das suas gravadoras

GET /analytics/summary e GET /analytics/leaderboards também aceitam filter[label_id], que restringe a requisição a uma única gravadora sua. Uma gravadora desconhecida retorna 404 e uma gravadora que não é sua retorna 403. Ele só consegue estreitar o seu escopo: não existe valor que o amplie.

Para restringir por loja, use filter[platform]. Veja API de Analytics: plataformas, disponibilidade e limites para os valores aceitos e a matriz de seções por plataforma.

Um escopo entra, uma série sai

As seções de séries e de resumo agregam sobre o escopo resolvido. Uma série diária agrupa por data e plataforma e soma a medida de todas as faixas do escopo, então o número de linhas que volta depende de quantas datas e plataformas reportaram, nunca de quantas faixas o filtro pegou.

GET /analytics/streams?filter[start_date]=2026-06-01&filter[end_date]=2026-06-02&filter[upc]=0123456789012

{
  "data": [
    { "date": "2026-06-01", "platform": "SPOTIFY", "total": 1804 },
    { "date": "2026-06-01", "platform": "DEEZER", "total": 96 },
    { "date": "2026-06-02", "platform": "SPOTIFY", "total": 1731 }
  ]
}

Um álbum de doze faixas e um single devolvem exatamente esse formato. O total de cada linha é o número do escopo inteiro para aquela data e plataforma, e é o mesmo valor tanto para um álbum de duas faixas quanto para um de vinte.

Os endpoints de demografia se comportam do mesmo jeito, uma dimensão adiante: /analytics/streams-by-country agrupa por país e soma o escopo todo, então uma chamada filtrada por UPC dá a divisão por país do álbum, não a de cada faixa. Toda seção de /analytics/summary segue a mesma regra, com duas exceções específicas, tratadas mais abaixo.

Nota

Isso é proposital, não uma limitação para contornar. Nada na requisição muda esse comportamento: não existe um parâmetro de “agrupar por faixa” nos endpoints de séries. Os números por faixa vêm dos dois endpoints abaixo.

Como obter números por faixa

O que você quer	Onde conseguir
Tudo sobre uma única faixa	filter[isrc] em qualquer endpoint de analytics
Totais por faixa em um período, ranqueados	GET /analytics/leaderboards?type=tracks
Série diária por faixa	GET /analytics/summary com metrics[]=track-streams-daily

Totais por faixa: o endpoint de leaderboards

GET /analytics/leaderboards classifica seu catálogo pela soma de streams na janela. É o equivalente na API ao card Top performers do dashboard de Analytics.

type é obrigatório e aceita artists, tracks, albums ou all (as três listas em uma requisição só). Os filtros de escopo o restringem exatamente como restringem uma série, então type=tracks com filter[upc] devolve as faixas daquele álbum e nada mais.

GET /analytics/leaderboards?type=tracks&filter[start_date]=2026-06-01&filter[end_date]=2026-06-30&filter[upc]=0123456789012&limit=50

As linhas de faixa trazem name, artistName, streams, release_id, identifier (o identificador da plataforma, ou null quando a linha abrange mais de uma) e isrc (a gravação a que pertencem os streams da linha). As linhas voltam ordenadas por streams, do maior para o menor.

isrc vem preenchido sempre que a linha corresponde, sem dúvida, a uma única gravação, inclusive quando várias plataformas reportam essa mesma gravação cada uma com seu próprio identifier, o caso comum de uma faixa disponível em mais de um serviço. Fica null quando não dá para provar que a linha cobre uma gravação só: chamadas sem filtro, que ordenam por nome em todo o seu catálogo; linhas delimitadas apenas por filter[artist_names][]; e linhas em que um mesmo título com o mesmo artista abrange duas gravações diferentes. Um null quer dizer que aquela linha não tem uma única gravação a que corresponder, não que a gravação esteja sem ISRC. Trate isrc e identifier como independentes: um pode vir null enquanto o outro traz um valor. E quando toda linha precisar de um ISRC, use as seções diárias por faixa mais abaixo.

Dois limites que vale planejar desde já:

• limit vale 10 por padrão e não passa de 50. Um álbum com mais de 50 faixas não cabe inteiro neste endpoint: use as seções diárias por faixa e some as linhas por conta própria.
• A janela não passa de 180 dias, menos que os 400 dias que os endpoints de séries permitem. Emendar várias janelas mais curtas não reconstrói um ranking mais longo, porque o top dez de cada mês não é o top dez do trimestre.

Séries diárias por faixa: duas seções do resumo

GET /analytics/summary traz duas seções que reportam cada faixa separadamente em vez do total do lançamento inteiro:

Seção	Formato da linha	Reportada por
track-streams-daily	{ date, platform, isrc, streams }	todas as plataformas
track-listeners-daily	{ date, platform, isrc, listeners }	Spotify, Apple Music e Amazon Music

As duas só entram sob demanda: são calculadas apenas quando você as nomeia em metrics[], e ambas exigem filter[release_id], filter[isrc] ou filter[upc]. Pedir uma delas sem um filtro de lançamento ou de faixa retorna 422, com o erro anexado a metrics. Um filtro por nome de artista não satisfaz essa exigência.

As linhas vêm ordenadas por data, depois plataforma, depois ISRC, e um dia sem atividade não gera linha alguma em vez de gerar um zero. Os números de listeners são contagens diárias e não podem ser somados entre datas: a mesma pessoa escutando em dois dias é um listener em cada um deles.

Cuidado

Uma requisição cujo produto de faixas × dias × plataformas fica grande demais retorna 422 pedindo para você encurtar o intervalo de datas, definir filter[platform] ou restringir a uma única faixa com filter[isrc]. O intervalo é recusado em vez de truncado, para que uma série parcial nunca chegue aos seus gráficos parecendo completa.

Exemplo prático: streams por faixa de um álbum

Você tem um álbum com UPC 0123456789012 e quer os números de junho abertos por faixa.

Para uma lista ranqueada de totais por faixa, peça ao endpoint de leaderboards as faixas do álbum:

GET /analytics/leaderboards?type=tracks&filter[start_date]=2026-06-01&filter[end_date]=2026-06-30&filter[upc]=0123456789012&limit=50

{
  "data": [
    { "name": "Nine Roses", "artistName": "Wiguez", "streams": 41208, "release_id": 88213, "identifier": "3n2f9xk2p1", "isrc": "USABC2600001" },
    { "name": "Harbour Lights", "artistName": "Wiguez", "streams": 18740, "release_id": 88213, "identifier": "7b1q4mz8v2", "isrc": "USABC2600002" }
  ],
  "meta": { "type": "tracks", "start_date": "2026-06-01", "end_date": "2026-06-30", "limit": 50 }
}

Para a série dia a dia de cada faixa, peça ao endpoint de resumo a seção por faixa:

GET /analytics/summary?filter[start_date]=2026-06-01&filter[end_date]=2026-06-30&filter[upc]=0123456789012&metrics[]=track-streams-daily

{
  "data": {
    "track-streams-daily": [
      { "date": "2026-06-01", "platform": "SPOTIFY", "isrc": "USABC2600001", "streams": 1412 },
      { "date": "2026-06-01", "platform": "DEEZER", "isrc": "USABC2600001", "streams": 78 },
      { "date": "2026-06-01", "platform": "SPOTIFY", "isrc": "USABC2600002", "streams": 392 }
    ]
  }
}

Acrescente metrics[]=track-listeners-daily à mesma chamada para ter os listeners junto com os streams. E, se só uma faixa do álbum interessa, tire o UPC e envie o filter[isrc] dela: todos os endpoints de analytics passam a reportar apenas aquela gravação.

Relacionado

• API de Analytics: plataformas, disponibilidade e limites — quais plataformas reportam quais métricas, a cadência de reporte e os limites de intervalo de datas
• Visão geral da API e guia rápido — autenticação, sandbox e a referência completa de endpoints
• Analytics — os mesmos dados no dashboard
• Conecte seu assistente de IA ao LabelGrid (MCP) — consulte seus analytics em linguagem natural