Billboard API: Get chart
Gets the ranked entries and chart history for a Billboard chart. It returns the latest published week, or the week that contains a given date. A date between published weeks selects the next published week.
Unofficial. Not affiliated with or endorsed by Billboard.
Inputs
Values from the run on Oct 23, 2026, shown under Output.
- Date optional
date Day in the chart week, for example 2024-04-03. Omit for the latest published week.
Not set
- Chart, required
chart Chart name as people say it, for example Hot 100, Billboard 200, Global 200, Artist 100, or Hot Country Songs.
Hot 100
- Max Results optional
max_results Maximum number of ranked entries, for example 10. Default 0 returns the full chart.
0 (default)
Whole number 0 or more.
Input as JSON
{ "chart": "Hot 100"}Output
{ "entries": [ { "rank": 1, "title": "Patient Zero", "artist": "Taylor Swift", "status": null, "page_url": "https://www.billboard.com/charts/hot-100/2026-10-24/" , "peak_position": 1, "last_week_rank": 1, "weeks_on_chart": 3 }, { "rank": 2, "title": "Choosin' Texas", "artist": "Ella Langley", "status": null, "page_url": "https://www.billboard.com/charts/hot-100/2026-10-24/" , "peak_position": 1, "last_week_rank": 2, "weeks_on_chart": 52 }, { "rank": 3, "title": "Boston", "artist": "Stella Lefty", "status": null, "page_url": "https://www.billboard.com/charts/hot-100/2026-10-24/" , "peak_position": 2, "last_week_rank": 3, "weeks_on_chart": 28 } ], "chart_name": "Billboard Hot 100", "chart_week_date": "2026-10-24"}Code
curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"billboard.com/get_chart","input":{"chart":"Hot 100"}}' # Save as fous.py, then run: python3 fous.pyimport json, os, timefrom urllib.error import HTTPErrorfrom urllib.request import Request, urlopenAPI = "https://api.fous.com/v1/runs" KEY = os.environ["FOUS_API_KEY"]HEADERS = { "Authorization": f"Bearer {KEY}", "Content-Type": "application/json" ,}def call(url, body=None): data = json.dumps(body).encode() if body else None request = Request(url, data, HEADERS) try: with urlopen(request, timeout=120) as r: return r.status, json.load(r) except HTTPError as error: message = json.load(error)["error"]["message"] raise RuntimeError(message) from errorstatus, run = call(API, { "method": "billboard.com/get_chart" , "input": { "chart": "Hot 100" }})# 202: still going after 30 s. Ask again until it ends.while status == 202: time.sleep(2) status, run = call(f"{API}/{run['id']}")print(json.dumps(run["data"], indent=2))// Save as fous.mjs, then run: node fous.mjsconst api = "https://api.fous.com/v1/runs" ;const headers = { Authorization: `Bearer ${process.env.FOUS_API_KEY}`, "Content-Type": "application/json" ,};let response = await fetch(api, { method: "POST", headers, body: JSON.stringify({ "method": "billboard.com/get_chart" , "input": { "chart": "Hot 100" } }), signal: AbortSignal.timeout(120_000),});let run = await response.json();// 202: still going after 30 s. Ask again until it ends.while (response.status === 202) { await new Promise((done) => setTimeout(done, 2_000)); response = await fetch(`${api}/${run.id}`, { headers }); run = await response.json();}if (!response.ok) throw new Error(run.error.message);console.log(run.data);# Connect your agent to Fous once, over MCP (Streamable HTTP):# https://api.fous.com/mcp# Set FOUS_API_KEY first: create a key at https://app.fous.com/keys.# Claude Codeclaude mcp add \ --scope user \ --transport http fous https://api.fous.com/mcp \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Codexcodex mcp add fous \ --url https://api.fous.com/mcp \ --bearer-token-env-var FOUS_API_KEY# Cursor, VS Code, Windsurf, Cline and morenpx -y add-mcp https://api.fous.com/mcp -g -n fous \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Then ask your agent:# "Use Fous to run billboard.com/get_chart# with {"chart":"Hot 100"}"Over HTTP, the answer’s data holds the output. A run still going after 30 seconds answers 202 with its id: ask GET /v1/runs/{id} until it ends.
Schema
Input schema
{ "type": "object", "required": [ "chart" ], "properties": { "date": { "type": "string", "examples": [ "2024-04-03" ], "description": "Day in the chart week, for example 2024-04-03. Omit for the latest published week." }, "chart": { "type": "string", "examples": [ "Hot 100" ], "description": "Chart name as people say it, for example Hot 100, Billboard 200, Global 200, Artist 100, or Hot Country Songs." }, "max_results": { "type": "integer", "default": 0, "minimum": 0, "examples": [ 10 ], "description": "Maximum number of ranked entries, for example 10. Default 0 returns the full chart." } }}Output schema
{ "type": "object", "required": [ "chart_name", "chart_week_date", "entries" ], "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "artist": { "type": "string" }, "status": { "type": [ "string", "null" ] }, "page_url": { "type": "string" }, "peak_position": { "type": "integer" }, "last_week_rank": { "type": [ "integer", "null" ] }, "weeks_on_chart": { "type": "integer" } } } }, "chart_name": { "type": "string" }, "chart_week_date": { "type": "string" } }}- Price
- 1 credit per completed run (1¢ with pay as you go); failed runs are free.
- Method
billboard.com/get_chart- Returns
- chart name, chart week date, entries with rank, title, artist, last week rank, peak position, weeks on chart, status
Use it from your agent
Give your agent this line. It reads SKILL.md, gets a Fous API key and connects the Fous MCP server. Its run then takes the method billboard.com/get_chart with the inputs above.
Ask your agent
- What's at number one on the Hot 100 this week?
- Show me the top 10 songs on the Billboard 200 for the week of April 3, 2024, with their peak positions.
- Get the Global 200 chart entries and how many weeks each song has been on it.
- I need the Hot Country Songs ranking from the chart week that includes 2023-11-18, limited to 15 entries.
- Which artists are on the Artist 100 chart right now, and what were their last week ranks?
See more
All Billboard methodsReturns an artist's Billboard Hot 100 song history or Billboard 200 album history: chart totals (entries, No. 1 hits, top 10 hits) and each title's debut, peak and weeks on chart, most recent debut first.
billboard.com/get_artist_chart_historyLists the current top songs, albums, or music videos on Apple Music for a country, in chart order. Countries without an Apple Music chart return no results.
music.apple.com/list_top_chartsLists the latest weekly YouTube Music Top Songs chart for a country or globally, with ranks, weekly views and video links.
youtube.com/list_top_songsGets Kworb's latest YouTube music chart, worldwide or for one country, ordered by daily views. The worldwide chart covers the past 24 hours. Country charts report daily track streams.
kworb.net/get_youtube_music_chartLists current worldwide top tracks, albums or artists on Deezer in chart order, or tracks from Deezer's official Top <country> playlist.
deezer.com/list_top_chartsReturns ranked box office grosses for a weekend in a market. Defaults to the latest reported US and Canada weekend; international markets use their own weekend calendar.
boxofficemojo.com/get_weekend_box_officeLists titles in an IMDb movie or TV chart (Top 250 movies, Top 250 TV shows, most popular movies or TV shows) with ratings, votes, runtime, age rating and weekly rank movement for popularity charts. Popular charts contain up to 100 titles.
imdb.com/list_top_chartsReturns the latest published Spotify daily Top 200 chart from Kworb for a country or worldwide, with rankings and stream counts.
kworb.net/get_spotify_daily_chart