Suno APIsuno.com ↗
Access Suno's explore feeds, trending songs, and playlist contents via API. Retrieve song metadata including audio URLs, play counts, tags, and artist info.
What is the Suno API?
The Suno API provides 3 endpoints for browsing AI-generated music on Suno, returning song metadata across curated explore feeds, trending charts, and named playlists. The get_trending_songs endpoint returns songs ranked by trending score, while explore_songs supports cursor-based pagination through staff-picked and curated feeds. Each song object includes fields like audio_url, play_count, duration, tags, artist, and title.
curl -X GET 'https://api.parse.bot/scraper/1e1a9405-ba82-4a65-99e1-e5088bf87a04/explore_songs?limit=5' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace suno-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Suno Music API — discover AI-generated songs, browse trending, and explore playlists."""
from parse_apis.suno_music_api import Suno, PlaylistNotFound
client = Suno()
# Browse the explore feed — curated songs from Staff Picks, Best Of, etc.
for song in client.songs.explore(limit=3):
print(f"🎵 {song.title} by {song.artist} — {song.play_count:,} plays")
# Trending songs — what's popular right now
top = client.songs.trending(limit=1).first()
if top:
print(f"\n🔥 Top trending: {top.title} by {top.artist}")
print(f" Tags: {top.tags}")
print(f" Upvotes: {top.upvote_count}, Plays: {top.play_count:,}")
# Fetch a playlist and browse its songs
playlist = client.playlists.get(id="990fd5fe-70d2-449b-8a4d-3cb0a7d3e805")
print(f"\n📚 Playlist: {playlist.name} ({playlist.total_available} songs)")
for song in playlist.songs.list(limit=3):
print(f" • {song.title} [{song.duration:.0f}s] — {song.created_at}")
# Typed error handling for a non-existent playlist
try:
client.playlists.get(id="00000000-0000-0000-0000-000000000000")
except PlaylistNotFound as exc:
print(f"\n❌ Playlist not found: {exc}")
print("\nExercised: songs.explore / songs.trending / playlists.get / playlist.songs.list")
Browse songs from Suno's explore page. Returns curated songs from various feeds (Staff Picks, Best Of, etc.) with cursor-based pagination. Each page returns a next_cursor for fetching subsequent pages.
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum number of songs to return. |
| cursor | string | Pagination cursor from previous response's next_cursor field. Omit for first page. |
{
"type": "object",
"fields": {
"songs": "array of song objects with id, title, artist, audio_url, play_count, duration, tags, and other metadata",
"next_cursor": "string pagination cursor for next page, or null if no more results",
"total_returned": "integer count of songs returned in this response"
},
"sample": {
"data": {
"songs": [
{
"id": "156a8275-3583-4b1e-8866-db12b5bfda63",
"url": "https://suno.com/song/156a8275-3583-4b1e-8866-db12b5bfda63",
"tags": "Experimental Hip-Hop, vocal chops, vocoders",
"title": "All speak for your life",
"artist": "Darren mac",
"duration": 150.52,
"audio_url": "https://cdn1.suno.ai/156a8275-3583-4b1e-8866-db12b5bfda63.mp3",
"image_url": "https://cdn2.suno.ai/8952215e-7dae-4bc7-a4a0-18a229b99b2e.jpeg",
"created_at": "2026-04-30T01:34:14.079Z",
"play_count": 349476,
"upvote_count": 4689,
"artist_handle": "dmacd",
"comment_count": 917,
"model_version": ""
}
],
"next_cursor": "3",
"total_returned": 5
},
"status": "success"
}
}About the Suno API
What the API Returns
All three endpoints return arrays of song objects sharing a consistent shape: id, title, artist, audio_url, play_count, duration, and tags. The audio_url field gives a direct link to the generated audio track, and play_count reflects how many times a song has been played on the platform. Tags describe the style, genre, or mood applied during generation.
Endpoints in Detail
explore_songs pulls from Suno's curated feeds — including Staff Picks and Best Of collections — and uses cursor-based pagination via the next_cursor response field. Pass the cursor value back as the cursor input param to advance through pages; omit it to start from the beginning. get_trending_songs takes an optional limit param and returns songs sorted by trending score, along with a total_available count. get_playlist_songs requires a playlist_id UUID and uses 1-indexed page-based pagination. Playlist IDs appear in explore_songs responses or can be read from Suno playlist URLs.
Pagination Patterns
explore_songs uses cursor-based pagination — store the next_cursor from each response and pass it to the next call. get_playlist_songs uses integer page numbers (page=1, page=2, etc.) alongside limit, and returns current_page, total_returned, and total_available so you can calculate how many pages remain. get_trending_songs does not paginate; it returns up to the requested limit from the available trending set.
The Suno API is a managed, monitored endpoint for suno.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when suno.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official suno.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a trending AI music dashboard using
play_countand trending score data fromget_trending_songs - Aggregate tagged songs by genre or mood using the
tagsfield across explore feed pages - Embed audio players in an app by retrieving
audio_urlvalues from playlist or explore results - Track how
play_countchanges over time for specific song IDs to monitor engagement trends - Mirror a curated Suno playlist into an external music library using
get_playlist_songswith pagination - Discover new AI-generated artists by collecting unique
artistvalues from explore feeds - Populate a music recommendation engine using metadata like
duration,tags, andplay_count
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Suno have an official developer API?+
What does the `explore_songs` endpoint return, and how does pagination work?+
explore_songs returns an array of song objects from Suno's curated feeds (such as Staff Picks and Best Of), along with a next_cursor string. Pass that cursor value as the cursor input parameter on the next call to retrieve the following page. When next_cursor is null, there are no more results.Can I retrieve a specific song's full detail page, lyrics, or generation prompts?+
id, title, artist, audio_url, play_count, duration, and tags — but does not expose lyrics, generation prompts, or individual song detail pages as a dedicated endpoint. You can fork this API on Parse and revise it to add a song-detail endpoint covering those fields.How do I find a playlist ID to use with `get_playlist_songs`?+
explore_songs, or you can read them directly from Suno playlist URLs in your browser (e.g., suno.com/playlist/<uuid>). Pass that UUID as the required playlist_id parameter.