chartmetric
Chartmetric API
Music industry analytics via Python scripts. Get streaming metrics, playlist placements, audience data, and competitive insights.
Setup
With Python (recommended)
cd .recoup/skills/chartmetric
python3 -m venv .venv && source .venv/bin/activate
pip install requests
export CHARTMETRIC_REFRESH_TOKEN="your_token"
Without Python (curl fallback)
If Python is unavailable, see references/curl-fallback.md for curl-only patterns. Only requires curl (universal).
Quick Start
# 1. Search for an artist
python scripts/search_artist.py "Drake"
# Returns: Chartmetric ID 3380
# 2. Get profile and stats
python scripts/get_artist.py 3380
python scripts/get_artist_metrics.py 3380 --source spotify
# 3. Get where fans listen
python scripts/get_artist_cities.py 3380
Critical Gotchas
These are the API traps that cause 401/400 errors. Memorize them:
| Gotcha | Wrong | Correct |
|---|---|---|
| YouTube metrics | --source youtube |
--source youtube_channel or youtube_artist |
| Artist playlists | /artist/:id/playlists |
/artist/:id/:platform/current/playlists |
| Similar artists | /artist/:id/similar |
/artist/:id/relatedartists or similar-artists/by-configurations |
| TikTok charts | With country_code |
No country_code parameter |
| Amazon charts | With country_code |
No country_code - use genre + type |
| Curator search | By name | By numeric Chartmetric ID only |
Scripts Reference
Artist Discovery
# Find US artists with 100K-500K Spotify monthly listeners
python scripts/discover_artists.py --country US --spotify-listeners 100000 500000
# TikTok-famous but weak on Spotify
python scripts/discover_artists.py --tiktok-followers 1000000 10000000 --spotify-listeners 0 100000
# Emerging artists in a genre, sorted by weekly growth
python scripts/discover_artists.py --genre 86 --spotify-listeners 50000 200000 --sort weekly_diff.sp_monthly_listeners
# Solo female artists in Brazil
python scripts/discover_artists.py --country BR --band false --pronoun she/her
# Festival performers with low Spotify (undervalued)
python scripts/discover_artists.py --festival-id 123 --spotify-followers 0 50000
Available filters: --country, --genre, --band, --pronoun, --spotify-listeners, --spotify-followers, --tiktok-followers, --instagram-followers, --youtube-subscribers, --cpp, --festival-id
Sort columns: latest.sp_monthly_listeners, weekly_diff.sp_monthly_listeners, monthly_diff.tt_followers, etc.
Search & Lookup
python scripts/search_artist.py "Taylor Swift" # Search artists by name
python scripts/get_artist.py 2762 # Get profile by CM ID
python scripts/get_artist_by_spotify.py 3TVXtAsR... # Lookup by Spotify ID/URL
python scripts/get_track.py 128613854 # Get track metadata
python scripts/get_track_by_spotify.py 0VjIjW4G... # Lookup track by Spotify
Artist Data
python scripts/get_artist_albums.py 3380 # All albums
python scripts/get_artist_tracks.py 3380 # All tracks
python scripts/get_artist_cities.py 3380 # Top cities by listeners
python scripts/get_artist_urls.py 3380 # Social/streaming URLs
python scripts/get_artist_insights.py 3380 # AI-generated insights
python scripts/get_artist_career.py 3380 # Career timeline
Platform Metrics
python scripts/get_artist_metrics.py 3380 --source spotify
python scripts/get_artist_metrics.py 3380 --source instagram
python scripts/get_artist_metrics.py 3380 --source youtube_channel
Valid sources (14 total): spotify, instagram, tiktok, twitter, facebook, youtube_channel, youtube_artist, soundcloud, deezer, twitch, line, melon, wikipedia, bandsintown
Audience Demographics
python scripts/get_artist_audience.py 3380 # Instagram (default)
python scripts/get_artist_audience.py 3380 --platform tiktok # TikTok
python scripts/get_artist_audience.py 3380 --platform youtube # YouTube
python scripts/get_artist_instagram_posts.py 3380 # Top IG posts/reels
Playlist Placements
# Basic - current Spotify playlists
python scripts/get_artist_playlists.py 3380
# Other platforms
python scripts/get_artist_playlists.py 3380 --platform applemusic
python scripts/get_artist_playlists.py 3380 --platform deezer
# Past placements
python scripts/get_artist_playlists.py 3380 --status past
# With filters
python scripts/get_artist_playlists.py 3380 --editorial --newMusicFriday
python scripts/get_artist_playlists.py 3380 --indie --majorCurator
# With date range and sorting
python scripts/get_artist_playlists.py 3380 --since 2025-01-01 --sort followers --limit 100
Platforms: spotify, applemusic, deezer, amazon, youtube
Spotify filters: --editorial, --personalized, --chart, --thisIs, --newMusicFriday, --radio, --indie, --majorCurator, --popularIndie, --brand
Similar/Related Artists
# Basic related artists
python scripts/get_similar_artists.py 3380 --limit 10
# Advanced with configuration filters
python scripts/get_similar_artists.py 3380 --by-config --audience high --genre high
python scripts/get_similar_artists.py 3380 --by-config --mood medium --musicality high
Config options: --audience, --mood, --genre, --musicality (values: high, medium, low)
Playlists & Curators
python scripts/get_playlist.py spotify 37i9dQZF1DXcBWIGoYBM5M # Playlist metadata
python scripts/get_curator.py 1 # Curator info (numeric ID)
Discovery
python scripts/list_genres.py # All Chartmetric genres
python scripts/list_festivals.py # Music festivals
Workflow Chains
Research an Artist for Playlist Pitching
# 1. Find the artist
python scripts/search_artist.py "Phoebe Bridgers"
# ID: 241089
# 2. Get their current playlist placements
python scripts/get_artist_playlists.py 241089 --editorial --limit 50
# 3. Find similar artists who might share playlists
python scripts/get_similar_artists.py 241089 --by-config --genre high --audience high
# 4. Check where their fans are
python scripts/get_artist_cities.py 241089
python scripts/get_artist_audience.py 241089 --platform instagram
Competitive Analysis
# 1. Get base artist
python scripts/get_artist.py 3380
# 2. Get similar artists with metrics
python scripts/get_similar_artists.py 3380 --by-config --audience high --limit 25
# 3. Compare streaming growth
python scripts/get_artist_metrics.py 3380 --source spotify
python scripts/get_artist_metrics.py <competitor_id> --source spotify
# 4. Compare playlist reach
python scripts/get_artist_playlists.py 3380 --sort followers
python scripts/get_artist_playlists.py <competitor_id> --sort followers
From Spotify URL to Full Profile
# 1. Convert Spotify URL to Chartmetric ID
python scripts/get_artist_by_spotify.py "https://open.spotify.com/artist/3TVXtAsR1Inumwj472S9r4"
# Returns: cm_artist: 1320
# 2. Get everything
python scripts/get_artist.py 1320
python scripts/get_artist_metrics.py 1320 --source spotify
python scripts/get_artist_cities.py 1320
python scripts/get_artist_playlists.py 1320
python scripts/get_artist_audience.py 1320
More Advanced Workflows
See references/advanced-workflows.md for 10 strategic workflow chains including:
- Playlist pitching intelligence
- TikTok-to-Spotify pipeline analysis
- A&R discovery workflow
- Collaboration finder
- Viral song autopsy
References
| File | When to Use |
|---|---|
references/parameter-guide.md |
Detailed endpoint parameters and gotchas |
references/endpoints.md |
All 120 endpoints with status |
references/curl-fallback.md |
When Python unavailable - curl patterns for all endpoints |
references/advanced-workflows.md |
Strategic insights - 10 multi-step workflow chains |
Rate Limits
Chartmetric has rate limits. If you get 429 errors, wait 60 seconds before retrying.
Troubleshooting
| Error | Cause | Fix |
|---|---|---|
| 401 Unauthorized | Token expired or internal endpoint | Refresh token; check if endpoint is public |
| 402 Payment Required | Subscription expired | Check Chartmetric account |
| 404 Not Found | Invalid ID | Verify Chartmetric ID (not Spotify ID) |
| 400 Bad Request | Wrong parameters | Check parameter-guide.md for correct params |
| "Domain does not exist" | Invalid stat source | Use exact source names (e.g., youtube_channel not youtube) |
More from recoupable/skills
recoup-api
Call the Recoupable API from the sandbox to fetch artist data, socials, organizations, research, documents and any other platform resource — and to invoke external connector actions (Google Docs / Drive / Sheets edits, Gmail, TikTok, Instagram, etc.) via Recoupable's shared connections. Use whenever you're asked for Recoup data, a Recoupable platform resource, or to read/write something outside Recoup like a Google Doc URL or a spreadsheet. Triggers on phrases like "look up artist", "fetch from recoup", "artist data", "artist socials", "organizations", "artist report", "research", "create new artist", "create artist", "onboard artist", "add artist", "edit this Google Doc", "read this doc", "update the spreadsheet", "send an email", "post on TikTok", "save to Drive", or whenever the user pastes a docs.google.com / drive.google.com / sheets.google.com URL. Always load this before writing curl calls against recoup-api.vercel.app.
79artist-workspace
How to work in artist directories — including creating, enumerating, and editing them. Use when creating or onboarding a new artist ("create artist", "onboard X", "add this artist", "set up a new artist") — this skill scaffolds the artist's `RECOUP.md` checklist file and drives the multi-step setup from it. Use when adding or updating artist context (identity, brand, voice, audience), adding songs, organizing files inside an artist directory, or figuring out where something belongs. Also use when the account asks inventory questions like "what artists do I have", "list my artists", "which orgs am I in", "what's in this sandbox" — the filesystem tree is the authoritative answer. And use when the account mentions an artist by name and the task involves their files, context, or content — even if they don't say "artist directory." This includes tasks like researching an artist, creating content for an artist, updating an artist's brand, or adding a face guide.
77trend-to-song
Create songs and content campaigns from trending cultural moments. Use when someone identifies a trending topic, viral moment, reality TV drama, meme, or cultural event and wants to turn it into a song and distribution strategy. Also triggers on "make a song about this trend," "capitalize on this moment," "reverse engineer from the market," "cultural moment to song," "trend-jack," or "burner page strategy." This flips the traditional music workflow — instead of song-first then marketing, you go market-first then song.
2songwriting
Guide for writing and evaluating song lyrics and concepts. Use when brainstorming song ideas, writing lyrics, evaluating song drafts, refining hooks, or improving existing songs. Applies the 7 C's framework to ensure songs are memorable, clear, and authentic.
2getting-started
Set up Recoupable from scratch — install the CLI, get an API key, and make your first call. Use this skill when the user says "set up Recoupable", "install Recoup", "get an API key", "connect to Recoup", "use Recoupable", "onboard to Recoup", "how do I start", or when an agent needs to configure itself to use the Recoupable platform.
2streaming-growth
Strategy for growing a new or early-stage music artist to key streaming milestones on Spotify and other DSPs. Use when someone asks about getting more streams, unlocking Spotify Showcase or Marquee, increasing Spotify Popularity score, playlist pitching, DSP advertising, or growing an artist from near-zero. Triggers on "how do we get more streams," "unlock Spotify ads," "playlist push," "get to a thousand listeners," "artist growth strategy," or "Spotify Popularity score.
2