# 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. - Page: https://fous.com/methods/billboard.com/get-chart - Method: `billboard.com/get_chart`, version 1 - Website: billboard.com - Returns: chart name, chart week date, entries with rank, title, artist, last week rank, peak position, weeks on chart, status - Effect: read (it gets data and changes nothing) - Sign-in: none needed - Cost: 1 credit per completed run (1ยข with pay as you go); failed runs are free - Verified: Nov 2, 2026 ## Inputs | Field | Type | Required | In the run below | Description | |---|---|---|---|---| | `date` | string | no | | Day in the chart week, for example 2024-04-03. Omit for the latest published week. | | `chart` | string | yes | `"Hot 100"` | Chart name as people say it, for example Hot 100, Billboard 200, Global 200, Artist 100, or Hot Country Songs. | | `max_results` | integer | no | | Maximum number of ranked entries, for example 10. Default 0 returns the full chart. Default 0. | ## Output From a run on Oct 23, 2026, shortened. Its input: ```json { "chart": "Hot 100" } ``` Its output: ```json { "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" } ``` ## Run it From code, with a Fous API key in `FOUS_API_KEY`; the answer's `data` holds the output: ```bash 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"}}' ``` From an AI agent connected to the Fous MCP server: its `run` with the same method and input. To connect one, give it `set up https://fous.com/SKILL.md`. ## 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? ## Input schema ```json { "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 ```json { "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" } } } ``` ## See more - [Billboard API: Get an artist's chart history](https://fous.com/methods/billboard.com/get-artist-chart-history.md): Returns 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. - [Apple API: List top charts](https://fous.com/methods/music.apple.com/list-top-charts.md): Lists 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. - [YouTube API: List top songs chart](https://fous.com/methods/youtube.com/list-top-songs.md): Lists the latest weekly YouTube Music Top Songs chart for a country or globally, with ranks, weekly views and video links. - [Kworb API: Get YouTube music chart](https://fous.com/methods/kworb.net/get-youtube-music-chart.md): Gets 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. - [Deezer API: List top charts](https://fous.com/methods/deezer.com/list-top-charts.md): Lists current worldwide top tracks, albums or artists on Deezer in chart order, or tracks from Deezer's official Top playlist. - [Box Office Mojo API: Get weekend box office chart](https://fous.com/methods/boxofficemojo.com/get-weekend-box-office.md): Returns 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. - [IMDb API: List top charts](https://fous.com/methods/imdb.com/list-top-charts.md): Lists 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. - [Kworb API: Get Spotify daily chart](https://fous.com/methods/kworb.net/get-spotify-daily-chart.md): Returns the latest published Spotify daily Top 200 chart from Kworb for a country or worldwide, with rankings and stream counts. - [All Billboard methods](https://fous.com/methods/billboard.com.md)