recoupable 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) |