راهنما

API تعداد پخش Spotify: تعداد کل استریم هر آهنگ، با شناسه یا ISRC

Q: آیا Spotify Web API تعداد پخش برمیگرداند؟

خیر. شیء آهنگ در مرجع Web API فیلد تعداد پخش ندارد. نزدیکترین فیلد، popularity، امتیازی از ۰ تا ۱۰۰ است که Spotify عمدتاً از کل پخشها و تازگی آنها حساب میکند؛ مرجع آن را منسوخ علامت میزند، و تغییرات فوریه ۲۰۲۶ در Spotify آن را برای برنامههای حالت توسعه که از ۱۱ فوریه ۲۰۲۶ ساخته شدهاند حذف کرد.

Q: چرا آهنگی ۰ پخش نشان میدهد؟

چون کمتر از ۱٬۰۰۰ پخش دارد. اسپک میگوید Spotify برای آهنگهای کمتر از ۱٬۰۰۰ پخش، ۰ گزارش میکند؛ پس ۰ یعنی زیر ۱٬۰۰۰، نه هرگز پخش نشده.

Q: میتوانم آهنگ را با ISRC پیدا کنم؟

بله. ⁨GET /partner/track/count⁩ بهجای شناسه Spotify مقدار ⁨isrc⁩ را میگیرد، پس کاتالوگی که با ISRC کلید خورده نیازی به جستجوی شناسه از پیش ندارد.

Q: این عدد چقدر بهروز است؟

تعداد پخشها یک ساعت کش میشوند، پس تعداد معمولاً حداکثر به همان اندازه قدیمی است. مقدار ⁨X-Cache⁩ که با ⁨STALE⁩ یا ⁨FALLBACK⁩ شروع شود یعنی چون دریافت زنده کند بود یا شکست خورد، نسخه قدیمیتر ارائه شده است؛ ⁨X-Cache-Stale-Age⁩ عمر آن را به ثانیه میدهد. برای دریافت نسخه تازه ⁨cache=false⁩ را اضافه کنید. دکمههای «اجرا» در این سایت از کش خود دمو هم میگذرند، پس عددی که آنجا میبینید ممکن است قدیمیتر باشد.

Q: کدام پلن را لازم دارم؟

هر پلنی. هر دو endpoint تعداد پخش روی همه پلنها هستند، هم RapidAPI و هم پورتال مستقیم، و پلنها در حجم ماهانه فرق دارند. هر پلن RapidAPI ⁨۵⁩ درخواست در ثانیه مجاز میکند و هر کلید مستقیم ⁨۱۰⁩ را شامل میشود. پلن رایگان RapidAPI ماهانه ⁨۱٬۰۰۰⁩ درخواست مجاز میکند.

Web API در Spotify هیچ‌وقت نمی‌گوید یک آهنگ چند بار پخش شده است. نزدیک‌ترین چیز popularity است، امتیازی از ۰ تا ۱۰۰ که مرجع خودش آن را عمدتاً مبتنی بر کل پخش‌ها می‌داند و منسوخ (deprecated) علامت زده است. این endpoint‌ها خود تعداد را برمی‌گردانند: یک آهنگ با شناسه Spotify یا ISRC، یا تا ⁨۵۰⁩ آهنگ در یک فراخوانی.

از ⁨Eduardo Airaudo⁩، نگهدارنده API · به‌روزرسانی ⁨۳۰ مهر ۱۴۰۵⁩

آنچه شیء رسمی آهنگ ندارد

⁨GET /v1/tracks/{id}⁩ در Spotify Web API آلبوم، هنرمندان، ⁨duration_ms⁩، ⁨explicit⁩، ⁨external_ids⁩، نام، ⁨popularity⁩ و چند مورد دیگر را برمی‌گرداند. هیچ‌کدام پخش‌ها را نمی‌شمارد. popularity از همه نزدیک‌تر است: مرجع Spotify آن را مقداری از ۰ تا ۱۰۰ می‌داند که عمدتاً از تعداد پخش‌های آهنگ و تازگی آن‌ها محاسبه می‌شود، و آن را منسوخ علامت می‌زند. تغییرات فوریه ۲۰۲۶ در Spotify آن را برای برنامه‌های حالت توسعه که از ۱۱ فوریه ۲۰۲۶ ساخته شده‌اند حذف کرد.

امتیاز نمی‌تواند کار تعداد را بکند. نسبی است، پس روی یک آلبوم یا کاتالوگ جمع نمی‌شود، و به پخش‌های تازه امتیاز بیشتری می‌دهد — همان مرجع می‌گوید آهنگ‌هایی که اکنون زیاد پخش می‌شوند امتیاز بالاتری از آهنگ‌هایی دارند که در گذشته زیاد پخش شده‌اند — پس نمی‌تواند بگوید یک آهنگ تا امروز چند بار پخش شده است.

به تعبیر اسپک، گروه Partner این API «⁨Spotify's internal (pathfinder) data, including play counts⁩» است. ⁨/partner/track/count⁩ تعداد کل پخش یک آهنگ را برمی‌گرداند، ⁨/partner/tracks/count⁩ تعداد حداکثر ⁨۵۰⁩ آهنگ را یک‌جا، و ⁨/partner/track⁩ آن را درون رکورد کامل آهنگ می‌آورد.

چه چیزی برمی‌گردد

فیلد به فیلد، همان‌طور که طرح‌واره‌های پاسخ اسپک تعریف می‌کنند. فراخوانی تک‌آهنگ، تعداد را ⁨streams⁩ می‌نامد؛ فراخوانی دسته‌ای آن را ⁨playcount⁩ می‌نامد.

یک آهنگ

GET /partner/track/count

streams: تعداد کل پخش، به‌صورت عدد صحیح (int64). در اسپک nullable است، و برای آهنگ زیر ۱٬۰۰۰ پخش برابر ۰ است.
spotify_track_id: شناسه Spotify آهنگ.
isrc: ISRC آهنگ. در اسپک nullable است.
result: ⁨success⁩ یا ⁨error⁩، با یک ⁨message⁩ کوتاه کنارش.

یک دسته

GET /partner/tracks/count

tracks[]: یک ورودی به‌ازای هر شناسه درخواستی، به ترتیب درخواست.
tracks[].playcount: کل پخش‌ها (int64، nullable)؛ برای آهنگ زیر ۱٬۰۰۰ برابر ۰.
tracks[].status: ⁨ok⁩، ⁨not_found⁩ یا ⁨error⁩، و وقتی ⁨error⁩ است متن ⁨error⁩ هم دارد.
tracks[].name: نام آهنگ؛ اگر پیدا نشد ⁨null⁩.
tracks[].artists[]: ⁨id⁩ و ⁨name⁩ هر هنرمند.
tracks[].releaseDate: تاریخ انتشار آلبوم آهنگ: YYYY-MM-DD، یا با دقتی کمتر.
missing[]: شناسه‌های درخواستی که status آن‌ها ⁨ok⁩ نیست.

۰ یعنی زیر ۱٬۰۰۰، نه هرگز پخش نشده. اسپک می‌گوید Spotify برای آهنگ‌های کمتر از ۱٬۰۰۰ پخش، ۰ گزارش می‌کند؛ پس ۰ را «زیر ۱٬۰۰۰» ذخیره کنید، نه به‌عنوان یک تعداد.

نمونه ضبط‌شده · دریافت‌شده در ⁨2026-10-22⁩

GET /partner/track/count

{

"result": "success",

"message": "Data Retrieved.",

"spotify_track_id": "7qiZfU4dY1lWllzX7mPBI3",

"streams": 5152826895

}

⁨۶⁩ خط — کل بدنه ضبط‌شده.

نمونه ضبط‌شده · دریافت‌شده در ⁨2026-10-22⁩

GET /partner/tracks/count

{

"tracks": [

{

"id": "7qiZfU4dY1lWllzX7mPBI3",

"name": "Shape of You",

"artists": [

{

"id": "6eUKZXaKkcviH0Ku9w2n3V",

"name": "Ed Sheeran"

}

"playcount": 5152826895,

"releaseDate": "2017-03-03",

"status": "ok"

}

"missing": []

}

⁨۱۸⁩ خط — کل بدنه ضبط‌شده.

یک آهنگ، یا ⁨۵۰⁩ آهنگ در هر فراخوانی

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.
پارامترهاspotify_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.
پارامترهاids, 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).
پارامترهاid, slim, cache

⁨/partner/tracks/count⁩ تا ⁨۵۰⁩ شناسه جداشده با ویرگول می‌گیرد و به همان ترتیبی که فرستاده‌اید پاسخ می‌دهد، پس ⁨۵۰⁩ آهنگ به‌جای ⁨۵۰⁩ درخواست، یک درخواست هزینه دارد.

دریافت تعداد پخش

یک آهنگ، با شناسه Spotify

curl -X GET \

"https://spotify-proxy.checkleaked.cc/spotify-data/partner/track/count?id=0VjIjW4GlUZAMYd2vXMi3b" \

-H "x-rapidapi-key: $SPOTIFY_API_KEY"

شناسه همان رشته ۲۲ نویسه‌ای بعد از ⁨/track/⁩ در هر URL اسپاتیفای است. برای جستجوی آهنگ با ISRC آن، به‌جای ⁨id=⁩ مقدار ⁨isrc=⁩ را بفرستید.

تا ⁨۵۰⁩ آهنگ در یک فراخوانی

curl -X GET \

"https://spotify-proxy.checkleaked.cc/spotify-data/partner/tracks/count?ids=0VjIjW4GlUZAMYd2vXMi3b%2C7qiZfU4dY1lWllzX7mPBI3" \

-H "x-rapidapi-key: $SPOTIFY_API_KEY"

پیش از تعداد، ⁨status⁩ هر ورودی را بخوانید. ورودی‌ها به ترتیب شناسه‌ها برمی‌گردند؛ ورودی بدون تعداد پخش، به‌جای آن ⁨not_found⁩ یا ⁨error⁩ دارد و دوباره در ⁨missing⁩ فهرست می‌شود.

تعداد پخش بدون کد

اگر تعدادها برای یک صفحه‌گسترده‌اند نه برای کد خودتان، دو Actor در Apify از همان نگهدارنده آن‌ها را به‌صورت دیتاست برمی‌گردانند. برای اجرا حساب Apify لازم است و کلید API لازم نیست: پیوندها را می‌چسبانید و JSON یا CSV دانلود می‌کنید.

Spotify Play Count Scraper (در زبانه جدید باز می‌شود)eduair94/spotify-play-count-scraper
پیوند، URI یا شناسه آهنگ، آلبوم، هنرمند یا پلی‌لیست را بچسبانید؛ برای هر آهنگ یک ردیف همراه با تعداد پخشش برمی‌گرداند — آهنگ‌های برتر یا کل آثار یک هنرمند، هر آهنگ یک آلبوم یا پلی‌لیست — و در صورت درخواست، یک ردیف با شنوندگان ماهانه هنرمند.
Spotify Scraper (در زبانه جدید باز می‌شود)eduair94/spotify-scraper
Actor عمومی: ⁨۶۱⁩ دسته، که ⁨۵⁩ تای آن‌ها تعداد پخش‌اند (⁨track_play_count, album_play_counts, artist_play_counts, artist_discography_play_counts, playlist_play_counts⁩)، و ⁨isrc⁩ که آهنگ را با ISRC پیدا می‌کند و تعداد پخشش را می‌دهد.

هر دو به‌ازای هر نتیجه صورتحساب می‌دهند، با قیمت‌های فهرست‌شده در ⁨۳۰ مهر ۱۴۰۵⁩: ⁨$0.001⁩ برای هر ردیف در پلن رایگان Apify، تا ⁨$0.0006⁩ از Gold به بالا. اینکه کی اجرا از کلید بهتر است و کی نه، در ⁨راهنمای اسکرپر⁩ آمده است.

تاریخچه‌ای که از قبل نگهداری می‌شود: 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.

از یک دستیار هوش مصنوعی (MCP) استفاده کنید: از Claude، Cursor یا VS Code استریم‌های یک آهنگ را بپرسید، و ابزار ⁨get_track_play_count⁩ در سرور MCP Spotify تعداد کل پخش را از این API برمی‌گرداند. ⁨راه‌اندازی سرور MCP⁩.

پرسش‌ها

آیا Spotify Web API تعداد پخش برمی‌گرداند؟

خیر. شیء آهنگ در مرجع Web API فیلد تعداد پخش ندارد. نزدیک‌ترین فیلد، popularity، امتیازی از ۰ تا ۱۰۰ است که Spotify عمدتاً از کل پخش‌ها و تازگی آن‌ها حساب می‌کند؛ مرجع آن را منسوخ علامت می‌زند، و تغییرات فوریه ۲۰۲۶ در Spotify آن را برای برنامه‌های حالت توسعه که از ۱۱ فوریه ۲۰۲۶ ساخته شده‌اند حذف کرد.

چرا آهنگی ۰ پخش نشان می‌دهد؟

چون کمتر از ۱٬۰۰۰ پخش دارد. اسپک می‌گوید Spotify برای آهنگ‌های کمتر از ۱٬۰۰۰ پخش، ۰ گزارش می‌کند؛ پس ۰ یعنی زیر ۱٬۰۰۰، نه هرگز پخش نشده.

می‌توانم تعداد پخش چند آهنگ را یک‌جا بگیرم؟

بله. ⁨GET /partner/tracks/count⁩ تا ⁨۵۰⁩ شناسه آهنگ جداشده با ویرگول می‌گیرد و به ترتیب درخواست پاسخ می‌دهد؛ هر ورودی status برابر ⁨ok⁩، ⁨not_found⁩ یا ⁨error⁩ دارد؛ شناسه‌های بدون تعداد پخش در ⁨missing⁩ هم فهرست می‌شوند. ⁨۵۰⁩ آهنگ به‌جای ⁨۵۰⁩ درخواست، یک درخواست هزینه دارد.

می‌توانم آهنگ را با ISRC پیدا کنم؟

بله. ⁨GET /partner/track/count⁩ به‌جای شناسه Spotify مقدار ⁨isrc⁩ را می‌گیرد، پس کاتالوگی که با ISRC کلید خورده نیازی به جستجوی شناسه از پیش ندارد.

این عدد چقدر به‌روز است؟

تعداد پخش‌ها یک ساعت کش می‌شوند، پس تعداد معمولاً حداکثر به همان اندازه قدیمی است. مقدار ⁨X-Cache⁩ که با ⁨STALE⁩ یا ⁨FALLBACK⁩ شروع شود یعنی چون دریافت زنده کند بود یا شکست خورد، نسخه قدیمی‌تر ارائه شده است؛ ⁨X-Cache-Stale-Age⁩ عمر آن را به ثانیه می‌دهد. برای دریافت نسخه تازه ⁨cache=false⁩ را اضافه کنید. دکمه‌های «اجرا» در این سایت از کش خود دمو هم می‌گذرند، پس عددی که آنجا می‌بینید ممکن است قدیمی‌تر باشد.

می‌توانم بدون نوشتن کد تعداد پخش بگیرم؟

بله، در Apify: برای اجرا حساب Apify لازم است و کلید API لازم نیست. ⁨Spotify Play Count Scraper⁩ (⁨eduair94/spotify-play-count-scraper⁩) پیوند آهنگ، آلبوم، هنرمند یا پلی‌لیست می‌گیرد و برای هر آهنگ یک ردیف با تعداد پخشش برمی‌گرداند؛ ⁨Spotify Scraper⁩ (⁨eduair94/spotify-scraper⁩) از ⁨۶۱⁩ دسته‌اش ⁨۵⁩ دسته تعداد پخش دارد. هر دو به‌ازای هر نتیجه صورتحساب می‌دهند.

کدام پلن را لازم دارم؟

هر پلنی. هر دو endpoint تعداد پخش روی همه پلن‌ها هستند، هم RapidAPI و هم پورتال مستقیم، و پلن‌ها در حجم ماهانه فرق دارند. هر پلن RapidAPI ⁨۵⁩ درخواست در ثانیه مجاز می‌کند و هر کلید مستقیم ⁨۱۰⁩ را شامل می‌شود. پلن رایگان RapidAPI ماهانه ⁨۱٬۰۰۰⁩ درخواست مجاز می‌کند.

منابع

Get Track — مرجع Spotify Web API — شیء رسمی آهنگ: بدون تعداد پخش، و popularity منسوخ علامت خورده است.
تغییرات فوریه ۲۰۲۶ — مرجع Spotify for Developers — popularity آهنگ در میان فیلدهای حذف‌شده.
راهنمای مهاجرت فوریه ۲۰۲۶ — Spotify for Developers — حذف‌ها شامل چه کسانی می‌شود: برنامه‌های حالت توسعه، تازه‌ها از ۱۱ فوریه ۲۰۲۶؛ برنامه‌های extended-quota تحت تأثیر نیستند.
⁨GET /partner/track/count⁩ در این سایت — پارامترها، وضعیت‌های خطا و یک دکمه اجرا.
⁨GET /partner/tracks/count⁩ در این سایت — فراخوانی دسته‌ای، با همان موارد.
⁨Spotify Play Count Scraper⁩ در Apify — راه بدون کد: ورودی و قیمت هر ردیف، همان‌طور که اکنون منتشر شده است.

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

یک کلید بگیرید و اولین تعداد پخش را بکشید

هر دو endpoint تعداد پخش روی همه پلن‌ها هستند، هم RapidAPI و هم پورتال مستقیم؛ در Apify، دو Actor بالا همین تعدادها را به‌صورت ردیف‌های دیتاست برمی‌گردانند، با صورتحساب به‌ازای هر نتیجه. پلن رایگان RapidAPI ماهانه ⁨۱٬۰۰۰⁩ درخواست است: با حداکثر ⁨۵۰⁩ آهنگ در هر فراخوانی، تا ⁨۵۰٬۰۰۰⁩ تعداد پخش.

RapidAPI Apify پورتال مستقیم

آماده خرید نیستید؟ ⁨دریافت کلید آزمایشی رایگان⁩: ⁨۵۰۰⁩ درخواست در ⁨۷⁩ روز، بدون کارت.