curl --request GET \
--url https://api.recoupable.dev/api/catalogs/{catalogId}/playcount-history \
--header 'x-api-key: <api-key>'import requests
url = "https://api.recoupable.dev/api/catalogs/{catalogId}/playcount-history"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.recoupable.dev/api/catalogs/{catalogId}/playcount-history', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.recoupable.dev/api/catalogs/{catalogId}/playcount-history",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.recoupable.dev/api/catalogs/{catalogId}/playcount-history"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.recoupable.dev/api/catalogs/{catalogId}/playcount-history")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.recoupable.dev/api/catalogs/{catalogId}/playcount-history")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"status": "success",
"catalog_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"platform": "spotify",
"metric": "platform_displayed_play_count",
"data_source": "apify_spotify_playcount",
"semantics": "<string>",
"source_timestamp_available": false,
"provider_identity_available": false,
"comparison_quality": "legacy_recording_series_identity_unverified",
"missing_observation_reason_available": false,
"collection_enabled": false,
"periods": {
"previous": {
"start": "2023-12-25",
"end": "2023-12-25"
},
"current": {
"start": "2023-12-25",
"end": "2023-12-25"
},
"days": 123,
"timezone": "UTC",
"boundary_semantics": "<string>",
"alignment_tolerance_seconds": 3600
},
"pagination": {
"page": 123,
"limit": 123,
"total_count": 123,
"total_pages": 123,
"has_more": true
},
"summary_scope": "page",
"comparable_recordings": 123,
"recordings": [
{
"isrc": "<string>",
"name": "<string>",
"state": "comparable",
"observations": [
{
"date": "2023-12-25",
"captured_at": "2023-11-07T05:31:56Z",
"value": 123
}
],
"missing_days": [
"2023-12-25"
],
"invalid_days": [
"2023-12-25"
],
"correction_days": [
"2023-12-25"
],
"previous_change": 123,
"current_change": 123,
"absolute_growth": 123,
"percentage_growth": 123,
"zero_baseline": true
}
]
}Catalog Playcount History
Read-only, store-backed public Spotify observations for current catalog membership, including unmeasured recordings. No collection, provider calls, charges or cron activation. API keys and Privy bearer tokens supported; identity overrides, unknown and duplicate query parameters rejected. Compare two adjacent equal observation periods with complete daily coverage and at most one hour capture drift. Missing days, invalid counts, negative corrections and excessive drift suppress growth. Real zero values remain zero; zero prior movement produces null percentage growth. Summaries apply only to this page; increment page while pagination.has_more. Catalog edits can change paging. Legacy rows lack historical provider counter identity and upstream update time: comparisons are provisional, not verified same-counter history, exact daily streams, royalties or causal marketing uplift. This endpoint does not import private artist analytics. Standard MCP tool: get_catalog_playcount_history; unavailable for delegated OAuth pending organization-grant audit. Proposed endpoint requires the linked API feature release; documentation is not proof of production availability.
curl --request GET \
--url https://api.recoupable.dev/api/catalogs/{catalogId}/playcount-history \
--header 'x-api-key: <api-key>'import requests
url = "https://api.recoupable.dev/api/catalogs/{catalogId}/playcount-history"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.recoupable.dev/api/catalogs/{catalogId}/playcount-history', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.recoupable.dev/api/catalogs/{catalogId}/playcount-history",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.recoupable.dev/api/catalogs/{catalogId}/playcount-history"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.recoupable.dev/api/catalogs/{catalogId}/playcount-history")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.recoupable.dev/api/catalogs/{catalogId}/playcount-history")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"status": "success",
"catalog_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"platform": "spotify",
"metric": "platform_displayed_play_count",
"data_source": "apify_spotify_playcount",
"semantics": "<string>",
"source_timestamp_available": false,
"provider_identity_available": false,
"comparison_quality": "legacy_recording_series_identity_unverified",
"missing_observation_reason_available": false,
"collection_enabled": false,
"periods": {
"previous": {
"start": "2023-12-25",
"end": "2023-12-25"
},
"current": {
"start": "2023-12-25",
"end": "2023-12-25"
},
"days": 123,
"timezone": "UTC",
"boundary_semantics": "<string>",
"alignment_tolerance_seconds": 3600
},
"pagination": {
"page": 123,
"limit": 123,
"total_count": 123,
"total_pages": 123,
"has_more": true
},
"summary_scope": "page",
"comparable_recordings": 123,
"recordings": [
{
"isrc": "<string>",
"name": "<string>",
"state": "comparable",
"observations": [
{
"date": "2023-12-25",
"captured_at": "2023-11-07T05:31:56Z",
"value": 123
}
],
"missing_days": [
"2023-12-25"
],
"invalid_days": [
"2023-12-25"
],
"correction_days": [
"2023-12-25"
],
"previous_change": 123,
"current_change": 123,
"absolute_growth": 123,
"percentage_growth": 123,
"zero_baseline": true
}
]
}Authorizations
Your Recoup API key. Learn more.
Path Parameters
Catalog owned by the authenticated account or an organization it currently belongs to.
Query Parameters
Current UTC observation-period start. Previous period immediately precedes it. Boundaries use the latest observation on that date, not midnight stream totals.
Equal length of both periods. Every UTC observation day through the final boundary must be finished and captured.
1 <= x <= 311 <= x <= 10000001 <= x <= 25Response
Saved observations and page-scoped comparison coverage
success spotify platform_displayed_play_count apify_spotify_playcount false false legacy_recording_series_identity_unverified false false Show child attributes
Show child attributes
Show child attributes
Show child attributes
page Show child attributes
Show child attributes
Was this page helpful?
