Guia

API de reproduções do Spotify: streams totais de qualquer música, por ID ou ISRC

A Web API do Spotify nunca diz quantas vezes uma música foi tocada. O mais perto disso é a popularidade, uma nota de 0 a 100 que a própria referência descreve como baseada principalmente no total de reproduções, e marca como descontinuada. Estes endpoints retornam a própria contagem: uma música por ID do Spotify ou ISRC, ou até 50 músicas em uma chamada.

Por Eduardo Airaudo, mantenedor da API · Atualizado em 22 de outubro de 2026

O que o objeto de música oficial deixa de fora

GET /v1/tracks/{id} na Web API do Spotify retorna o álbum, os artistas, duration_ms, explicit, external_ids, o nome, popularity e mais alguns campos. Nenhum deles conta reproduções. A popularidade é o mais próximo: a referência do Spotify a define como um valor de 0 a 100, calculado principalmente a partir de quantas reproduções uma música teve e de quão recentes elas são, e a marca como descontinuada. As mudanças de fevereiro de 2026 do Spotify a removeram para apps em modo de desenvolvimento criados a partir de 11 de fevereiro de 2026.

Uma nota não faz o que uma contagem faz. Ela é relativa, então não se soma entre um álbum ou um catálogo, e favorece reproduções recentes — a mesma referência diz que músicas muito tocadas agora recebem nota maior que músicas muito tocadas no passado — e por isso não diz quantas vezes uma música já foi tocada.

Nas palavras da especificação, o grupo Partner desta API é “Spotify's internal (pathfinder) data, including play counts”. /partner/track/count retorna a contagem total de uma música, /partner/tracks/count a de até 50 músicas de uma vez, e /partner/track a traz dentro do registro completo da música.

O que volta

Campo por campo, como os esquemas de resposta da especificação os definem. A chamada de uma música chama a contagem de streams; a de lote a chama de playcount.

Uma música

GET /partner/track/count

streams
O total de reproduções, como inteiro (int64). Pode ser nulo na especificação, e é 0 para uma música com menos de 1.000 reproduções.
spotify_track_id
O ID da música no Spotify.
isrc
O ISRC da música. Pode ser nulo na especificação.
result
success ou error, com uma message curta ao lado.

Um lote

GET /partner/tracks/count

tracks[]
Uma entrada por ID solicitado, na ordem da requisição.
tracks[].playcount
Reproduções totais (int64, pode ser nulo); 0 para uma música com menos de 1.000.
tracks[].status
ok, not_found ou error, com um texto de error quando for error.
tracks[].name
O nome da música; null quando ela não foi encontrada.
tracks[].artists[]
O id e o name de cada artista.
tracks[].releaseDate
A data de lançamento do álbum da música: YYYY-MM-DD ou uma precisão menor.
missing[]
Os IDs solicitados cujo status não é ok.

Um 0 significa menos de 1.000, não que a música nunca foi tocada. A especificação diz que o Spotify informa 0 para músicas com menos de 1.000 reproduções, então guarde um 0 como “abaixo de 1.000” em vez de como uma contagem.

Amostra gravada · capturada em 2026-10-22

GET /partner/track/count

6 linhas — o corpo gravado inteiro.

Amostra gravada · capturada em 2026-10-22

GET /partner/tracks/count

18 linhas — o corpo gravado inteiro.

Uma música ou 50 por chamada

  • GET /partner/track/countTrack play count

    Lifetime play count of one track, by Spotify id (spotify_track_id, or its alias id) or by isrc. Spotify reports 0 for tracks with fewer than 1,000 plays. Play counts are cached for 1 hour; for many tracks use /partner/tracks/count.

    Parâmetrosspotify_track_id, id, isrc, cache

  • GET /partner/tracks/countTrack play counts (batch)

    Lifetime play counts for up to 50 tracks in one call. Entries come back in request order with status ok, not_found or error; ids without a play count are also listed in missing. Each id is cached for 1 hour.

    Parâmetrosids, cache

  • GET /partner/trackPartner track data

    Track with its play count (data.trackUnion.playcount), album, artists and content ratings. Add slim=1 to keep only {id, uri, profile.name, visuals.avatarImage} of each artist (the full payload embeds the first artist's discography and is ~100 KB).

    Parâmetrosid, slim, cache

/partner/tracks/count recebe até 50 IDs separados por vírgula e responde na ordem em que você os enviou, então 50 músicas custam uma requisição em vez de 50.

Buscar reproduções

Uma música, por ID do Spotify

O ID é a sequência de 22 caracteres depois de /track/ em qualquer URL do Spotify. Para buscar uma música pelo ISRC, envie isrc= no lugar de id=.

Até 50 músicas em uma chamada

Leia o status de cada entrada antes da contagem. As entradas voltam na ordem dos IDs; uma sem contagem de reproduções vem marcada como not_found ou error no lugar dela e é listada de novo em missing.

Reproduções sem código

Se as contagens são para uma planilha e não para o seu próprio código, dois actors do Apify do mesmo mantenedor as retornam como dataset. Uma execução exige uma conta no Apify e nenhuma chave de API: você cola links e baixa JSON ou CSV.

Os dois cobram por resultado, pelos preços listados em : $0.001 por linha no plano gratuito do Apify, caindo até $0.0006 do Gold em diante. Quando uma execução vale mais que uma chave, e quando não vale, está em o guia do scraper.

Um histórico já guardado: spotify-most-streamed-songs (opens in a new tab) on GitHub has daily play counts and daily streams for 1,000 of the most-streamed songs, as CSV and JSON history.

Use em um assistente de IA (MCP): peça ao Claude, ao Cursor ou ao VS Code os streams de uma música, e a ferramenta get_track_play_count do servidor MCP do Spotify retorna as reproduções totais desta API. Configure o servidor MCP.

Perguntas

A Web API do Spotify retorna o número de reproduções?

Não. O objeto de música na referência da Web API não tem campo de reproduções. O campo mais próximo, popularity, é uma nota de 0 a 100 que o Spotify calcula principalmente a partir do total de reproduções e de quão recentes elas são; a referência o marca como descontinuado, e as mudanças de fevereiro de 2026 do Spotify o removeram para apps em modo de desenvolvimento criados a partir de 11 de fevereiro de 2026.

Por que uma música aparece com 0 reproduções?

Porque ela tem menos de 1.000. A especificação diz que o Spotify informa 0 para músicas com menos de 1.000 reproduções, então um 0 significa abaixo de 1.000, não que a música nunca foi tocada.

Posso obter as reproduções de várias músicas de uma vez?

Sim. GET /partner/tracks/count recebe até 50 IDs de músicas separados por vírgula e responde na ordem da requisição, cada entrada com status ok, not_found ou error; os IDs sem contagem de reproduções também são listados em missing. 50 músicas custam uma requisição em vez de 50.

Posso buscar uma música pelo ISRC?

Sim. GET /partner/track/count aceita isrc no lugar de um ID do Spotify, então um catálogo organizado por ISRC não precisa de uma busca de ID antes.

Quão atual é o número?

As contagens de reproduções ficam em cache por uma hora, então uma contagem tem, em geral, no máximo essa idade. Um valor de X-Cache que começa com STALE ou FALLBACK significa que uma cópia mais antiga foi servida porque a busca ao vivo estava lenta ou falhou; X-Cache-Stale-Age informa a idade dela em segundos. Adicione cache=false para buscar uma nova. Os botões Executar deste site também passam pelo cache próprio da demonstração, então o valor ali pode ser mais antigo.

Posso obter as reproduções sem escrever código?

Sim, no Apify: uma execução exige uma conta no Apify e nenhuma chave de API. O Spotify Play Count Scraper (eduair94/spotify-play-count-scraper) recebe links de músicas, álbuns, artistas ou playlists e retorna uma linha por música com a contagem de reproduções; o Spotify Scraper (eduair94/spotify-scraper) tem 5 categorias de reproduções entre as 61 que oferece. Os dois cobram por resultado.

De qual plano eu preciso?

De qualquer um. Os dois endpoints de reproduções estão em todos os planos, tanto da RapidAPI quanto do portal direto, e os planos diferem pelo volume mensal. Todo plano da RapidAPI permite 5 requisições por segundo e toda chave direta inclui 10. O plano gratuito da RapidAPI permite 1.000 requisições por mês.

Fontes

More guides

What changed in the API and on these pages, and when: What's new.

Obtenha uma chave e puxe sua primeira contagem de reproduções

Os dois endpoints de reproduções estão em todos os planos, tanto da RapidAPI quanto do portal direto; no Apify, os dois actors acima retornam as mesmas contagens como linhas de dataset, cobradas por resultado. O plano gratuito da RapidAPI tem 1.000 requisições por mês: com até 50 músicas por chamada, até 50.000 contagens de reproduções.

RapidAPI Apify Portal Direto

Ainda não quer comprar? Receber uma chave de teste grátis: 500 requisições em 7 dias, sem cartão.