API de Analytics: filtros de alcance y datos por track

Toda solicitud de analytics cubre una parte de su catálogo, y toda solicitud devuelve un único resultado agregado sobre esa parte. Esas dos reglas juntas confunden a mucha gente: si filtra una llamada por el UPC de un álbum, obtiene las cifras del álbum, no una fila por cada track que contiene. Esta guía explica los filtros que fijan el alcance, qué hace la agregación con el resultado y los dos endpoints que desglosan un alcance track a track.

Los filtros de alcance

Cuatro filtros acotan una solicitud de analytics a una parte de su catálogo. Funcionan en GET /analiticas/summary, en los endpoints independientes de series y demografía, y en GET /analiticas/leaderboards y /analiticas/placements.

Filtro	Tipo	Los tracks a los que se resuelve
filter[release_id]	entero	todos los tracks de ese lanzamiento
filter[isrc]	cadena	la única grabación que lleva ese ISRC
filter[upc]	cadena	todos los tracks del lanzamiento con ese código de barras
filter[artist_names][]	array de cadenas	todos los tracks de su catálogo acreditados a esos artistas

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

Si no envía ninguno, la solicitud cubre todo el catálogo al que tiene acceso: es el alcance por defecto de cualquier llamada de analytics.

Solo se aplica un filtro

Los cuatro se resuelven en un orden fijo: release_id, luego isrc, luego upc y luego artist_names[]. Gana el primero que esté presente. Enviar filter[release_id] y filter[upc] a la vez no los cruza: el UPC se ignora. Envíe únicamente el filtro que quiere aplicar.

Qué pasa cuando el identificador no es suyo

Los tres filtros a nivel de lanzamiento responden de forma distinta cuando el identificador no se resuelve dentro de su catálogo:

• filter[release_id] genera un error: 404 si no existe tal lanzamiento y 403 si existe pero no es suyo.
• filter[isrc] y filter[upc] se resuelven en un alcance vacío, y la solicitud tiene éxito con un data vacío.

Así que cuando llame a la API con un identificador que ha escrito un usuario, compruebe si data viene vacío en lugar de esperar un 404.

Acotar a uno de sus sellos

GET /analiticas/summary y GET /analiticas/leaderboards aceptan además filter[label_id], que limita la solicitud a uno solo de sus sellos. Un sello desconocido devuelve 404 y un sello que no es suyo devuelve 403. Solo puede reducir su alcance: no hay ningún valor que lo amplíe.

Para acotar por tienda, use filter[platform]. En API de Analytics: plataformas, disponibilidad y límites encontrará los valores aceptados y la matriz de secciones por plataforma.

Un alcance de entrada, una serie de salida

Las secciones de series y de resumen agregan sobre el alcance ya resuelto. Una serie diaria agrupa por fecha y plataforma y suma la medida de todos los tracks del alcance, así que el número de filas que recibe depende de cuántas fechas y plataformas informaron, nunca de cuántos tracks coincidieron con el filtro.

GET /analiticas/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 }
  ]
}

Un álbum de doce tracks y un single devuelven exactamente la misma forma. El total de cada fila es la cifra de todo el alcance para esa fecha y esa plataforma, y vale lo mismo tanto si el álbum tiene dos tracks como si tiene veinte.

Los endpoints de demografía se comportan igual, solo que una dimensión más allá: /analiticas/streams-by-country agrupa por país y suma sobre el alcance, así que una llamada filtrada por UPC da el desglose por país del álbum, no el de cada track. Todas las secciones de /analiticas/summary siguen la misma regla, con dos excepciones concretas que se explican más abajo.

Nota

Esto es deliberado, no una limitación que haya que sortear. Nada en la solicitud lo cambia: los endpoints de series no tienen ningún parámetro de tipo «agrupar por track». Las cifras por track salen de los dos endpoints que se describen a continuación.

Cómo obtener cifras por track

Lo que quiere	Dónde conseguirlo
Todo sobre un solo track	filter[isrc] en cualquier endpoint de analytics
Totales por track de un período, en forma de ranking	GET /analiticas/leaderboards?type=tracks
Serie diaria por track	GET /analiticas/summary con metrics[]=track-streams-daily

Totales por track: el endpoint de rankings

GET /analiticas/leaderboards clasifica su catálogo por la suma de streams de la ventana. Es el equivalente en la API de la tarjeta Top performers del dashboard de Analytics.

type es obligatorio y acepta artists, tracks, albums o all (las tres listas en una sola solicitud). Los filtros de alcance lo acotan igual que acotan una serie, así que type=tracks con filter[upc] le da los tracks de ese álbum y nada más.

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

Las filas de track llevan name, artistName, streams, release_id, identifier (el identificador de la plataforma, o null cuando la fila abarca más de uno) e isrc (la grabación a la que pertenecen los streams de la fila). Las filas vuelven ordenadas por streams, de mayor a menor.

isrc se devuelve siempre que la fila corresponde sin lugar a dudas a una sola grabación, incluso cuando varias plataformas informan esa misma grabación cada una con su propio identifier, que es lo habitual en un track disponible en más de un servicio. Es null cuando no se puede demostrar que la fila cubra una sola grabación: las llamadas sin filtro, que ordenan por nombre en todo su catálogo; las filas acotadas solo con filter[artist_names][]; y las filas en las que un mismo título y un mismo artista abarcan dos grabaciones distintas. Un null significa que esa fila no tiene una grabación única con la que emparejarla, no que la grabación carezca de ISRC. Trate isrc e identifier como independientes: cualquiera de los dos puede venir null mientras el otro trae un valor. Y cuando necesite que todas las filas lleven un ISRC, use las secciones diarias por track de más abajo.

Dos límites que conviene tener previstos:

• limit vale 10 por defecto y no puede pasar de 50. Un álbum con más de 50 tracks no se puede listar entero por este endpoint: use en su lugar las secciones diarias por track y sume usted las filas.
• La ventana no puede pasar de 180 días, menos que los 400 días que permiten los endpoints de series. Encadenar varias ventanas más cortas no reconstruye un ranking más largo, porque el top diez de cada mes no es el top diez del trimestre.

Series diarias por track: dos secciones de resumen

GET /analiticas/summary incluye dos secciones que informan cada track por separado en lugar del total de todo el lanzamiento:

Sección	Forma de la fila	Informada por
track-streams-daily	{ date, platform, isrc, streams }	todas las plataformas
track-listeners-daily	{ date, platform, isrc, listeners }	Spotify, Apple Music y Amazon Music

Las dos hay que pedirlas expresamente: solo se calculan cuando las nombra en metrics[], y las dos exigen filter[release_id], filter[isrc] o filter[upc]. Nombrar una de ellas sin un filtro de lanzamiento o de track devuelve 422, con el error asociado a metrics. Un filtro por nombre de artista no cumple ese requisito.

Las filas van ordenadas por fecha, luego por plataforma y luego por ISRC, y un día sin actividad no genera ninguna fila en lugar de una fila con un cero. Las cifras de listeners son recuentos diarios y no se pueden sumar entre fechas: la misma persona escuchando dos días es un listener en cada uno de ellos.

Precaución

Una solicitud cuyo producto de tracks × días × plataformas resulta demasiado grande devuelve 422 y le pide reducir el rango de fechas, fijar filter[platform] o acotar a un solo track con filter[isrc]. El rango se rechaza en lugar de recortarse, así que una serie parcial nunca llega a sus gráficos aparentando estar completa.

Ejemplo práctico: streams por track de un álbum

Tiene un álbum con el UPC 0123456789012 y quiere las cifras de junio desglosadas por track.

Para una lista ordenada de totales por track, pida al endpoint de rankings los tracks del álbum:

GET /analiticas/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 la serie día a día de cada track, pida al endpoint de resumen la sección por track:

GET /analiticas/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 }
    ]
  }
}

Añada metrics[]=track-listeners-daily a la misma llamada para tener listeners junto a los streams. Y si solo le interesa un track del álbum, quite el UPC y envíe en su lugar el filter[isrc] de ese track: a partir de ahí todos los endpoints de analytics informan únicamente sobre esa grabación.

Relacionado

• API de Analytics: plataformas, disponibilidad y límites — qué plataformas informan qué métricas, la cadencia de informes y los límites de rango de fechas
• Visión general de la API y guía rápida — autenticación, sandbox y la referencia completa de endpoints
• Analytics — los mismos datos en el dashboard
• Conecte su asistente de IA a LabelGrid (MCP) — consulte sus analytics en lenguaje natural