` | Yes | Trigger.dev run ID |
+## research
+
+Music industry research — streaming metrics, audience demographics, playlist placements, competitive analysis, and web intelligence. All data is accessed through your `RECOUP_API_KEY`.
+
+Artist-scoped commands (like `metrics`, `audience`, `similar`) accept an **artist name** or a **Recoup artist ID** (UUID). The API resolves the artist automatically. If the name is ambiguous (multiple matches), the API returns the top results for disambiguation.
+
+### Search for an artist
+
+```bash
+recoup research "Drake"
+recoup research "Phoebe Bridgers" --json
+```
+
+See [`GET /api/research`](/api-reference/research/search).
+
+### Lookup by platform URL
+
+Find an artist from a Spotify URL, Apple Music link, or any platform ID.
+
+```bash
+recoup research lookup "https://open.spotify.com/artist/3TVXtAsR1Inumwj472S9r4"
+recoup research lookup "3TVXtAsR1Inumwj472S9r4"
+```
+
+See [`GET /api/research/lookup`](/api-reference/research/lookup).
+
+### Artist profile and career
+
+```bash
+recoup research profile "Drake"
+recoup research career "Drake"
+recoup research insights "Drake"
+```
+
+| Subcommand | Description | API endpoint |
+|------------|-------------|-------------|
+| `profile` | Full artist profile — bio, genres, social URLs, label | [`GET /api/research/profile`](/api-reference/research/profile) |
+| `career` | Career timeline and key milestones | [`GET /api/research/career`](/api-reference/research/career) |
+| `insights` | AI-generated observations and trends | [`GET /api/research/insights`](/api-reference/research/insights) |
+
+### Streaming and social metrics
+
+Get platform-specific metrics over time. Supports 14 platforms.
+
+```bash
+recoup research metrics "Drake" --source spotify
+recoup research metrics "Drake" --source instagram
+recoup research metrics "Drake" --source tiktok
+recoup research metrics "Drake" --source youtube_channel
+```
+
+Valid `--source` values: `spotify`, `instagram`, `tiktok`, `twitter`, `facebook`, `youtube_channel`, `youtube_artist`, `soundcloud`, `deezer`, `twitch`, `line`, `melon`, `wikipedia`, `bandsintown`.
+
+See [`GET /api/research/metrics`](/api-reference/research/metrics).
+
+### Audience and geography
+
+```bash
+recoup research audience "Drake"
+recoup research audience "Drake" --platform tiktok
+recoup research audience "Drake" --platform youtube
+recoup research cities "Drake"
+```
+
+| Subcommand | Description | API endpoint |
+|------------|-------------|-------------|
+| `audience` | Age, gender, country breakdown. `--platform`: `instagram` (default), `tiktok`, `youtube` | [`GET /api/research/audience`](/api-reference/research/audience) |
+| `cities` | Top cities by listener concentration | [`GET /api/research/cities`](/api-reference/research/cities) |
+
+### Social URLs
+
+Get all social and streaming links for an artist.
+
+```bash
+recoup research urls "Drake"
+```
+
+See [`GET /api/research/urls`](/api-reference/research/urls).
+
+### Instagram posts
+
+Get an artist's top Instagram posts and reels by engagement.
+
+```bash
+recoup research instagram-posts "Drake"
+```
+
+See [`GET /api/research/instagram-posts`](/api-reference/research/instagram-posts).
+
+### Competitive landscape
+
+```bash
+recoup research similar "Drake"
+recoup research similar "Drake" --audience high --genre high --limit 20
+```
+
+Configuration options: `--audience`, `--genre`, `--mood`, `--musicality` (values: `high`, `medium`, `low`).
+
+See [`GET /api/research/similar`](/api-reference/research/similar).
+
+### Playlists
+
+```bash
+recoup research playlists "Drake"
+recoup research playlists "Drake" --platform applemusic
+recoup research playlists "Drake" --editorial
+recoup research playlists "Drake" --status past --since 2025-01-01
+recoup research playlists "Drake" --sort followers --limit 50
+```
+
+| Flag | Description |
+|------|-------------|
+| `--platform ` | `spotify` (default), `applemusic`, `deezer`, `amazon`, `youtube` |
+| `--editorial` | Only editorial playlists |
+| `--status ` | `current` (default) or `past` |
+| `--since ` | Filter by date (YYYY-MM-DD) |
+| `--sort ` | Sort results (e.g., `followers`) |
+| `--limit ` | Max results |
+
+See [`GET /api/research/playlists`](/api-reference/research/playlists).
+
+### Discography
+
+```bash
+recoup research albums "Drake"
+recoup research tracks "Drake"
+```
+
+See [`GET /api/research/albums`](/api-reference/research/albums) and [`GET /api/research/tracks`](/api-reference/research/tracks).
+
+### Track details
+
+Get metadata for a specific track — look up by name or Spotify URL.
+
+```bash
+recoup research track "God's Plan"
+recoup research track "https://open.spotify.com/track/2grjqo0Frpf2..."
+```
+
+See [`GET /api/research/track`](/api-reference/research/track).
+
+### Playlist and curator details
+
+Get metadata for a specific playlist or its curator.
+
+```bash
+recoup research playlist spotify 37i9dQZF1DXcBWIGoYBM5M
+recoup research curator spotify 1
+```
+
+See [`GET /api/research/playlist`](/api-reference/research/playlist) and [`GET /api/research/curator`](/api-reference/research/curator).
+
+### Discover artists
+
+Find artists by criteria — country, genre, listener ranges, growth rate.
+
+```bash
+recoup research discover --country US --spotify-listeners 100000 500000
+recoup research discover --genre 86 --sort weekly_diff.sp_monthly_listeners
+```
+
+| Flag | Description |
+|------|-------------|
+| `--country ` | ISO country code (US, BR, GB, etc.) |
+| `--genre ` | Genre ID (use `recoup research genres` to list) |
+| `--spotify-listeners ` | Monthly listener range |
+| `--sort ` | Sort field (e.g., `weekly_diff.sp_monthly_listeners`) |
+| `--limit ` | Max results |
+
+See [`GET /api/research/discover`](/api-reference/research/discover).
+
+### Milestones
+
+Get an artist's activity feed — playlist adds, chart entries, and notable events.
+
+```bash
+recoup research milestones "Drake"
+recoup research milestones "Drake" --json
+```
+
+See [`GET /api/research/milestones`](/api-reference/research/milestones).
+
+### Venues
+
+Get venues an artist has performed at, including capacity and location.
+
+```bash
+recoup research venues "Drake"
+recoup research venues "Drake" --json
+```
+
+See [`GET /api/research/venues`](/api-reference/research/venues).
+
+### Rank
+
+Get an artist's global Chartmetric ranking.
+
+```bash
+recoup research rank "Drake"
+recoup research rank "Drake" --json
+```
+
+See [`GET /api/research/rank`](/api-reference/research/rank).
+
+### Charts
+
+Get global chart positions for a platform. NOT artist-scoped — returns the full chart.
+
+```bash
+recoup research charts --platform spotify
+recoup research charts --platform spotify --country US
+recoup research charts --platform applemusic --country GB --interval weekly --json
+```
+
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--platform ` | Yes | Chart platform (spotify, applemusic, tiktok, youtube, itunes, shazam) |
+| `--country ` | No | ISO country code (US, GB, DE, etc.) |
+| `--interval ` | No | Time interval (e.g. daily, weekly) |
+| `--type ` | No | Chart type (varies by platform) |
+| `--latest` | No | Return only the most recent chart |
+
+See [`GET /api/research/charts`](/api-reference/research/charts).
+
+### Radio stations
+
+List radio stations tracked by Chartmetric.
+
+```bash
+recoup research radio
+recoup research radio --json
+```
+
+See [`GET /api/research/radio`](/api-reference/research/radio).
+
+### Reference data
+
+```bash
+recoup research genres
+recoup research festivals
+```
+
+See [`GET /api/research/genres`](/api-reference/research/genres) and [`GET /api/research/festivals`](/api-reference/research/festivals).
+
+### Web research
+
+Search the web for narrative context, press coverage, and cultural information that structured data doesn't cover.
+
+```bash
+recoup research web "Drake brand partnerships sync licensing"
+recoup research web "Phoebe Bridgers fan community psychographics"
+```
+
+See [`POST /api/research/web`](/api-reference/research/web).
+
+### Deep research report
+
+Comprehensive multi-source research that synthesizes information from across the web into a cited report.
+
+```bash
+recoup research report "Drake"
+recoup research report "Tell me everything about Phoebe Bridgers — bio, streaming metrics, fan base, competitive landscape, and revenue opportunities"
+```
+
+See [`POST /api/research/deep`](/api-reference/research/deep).
+
+### People search
+
+Search for people in the music industry — artists, managers, A&R reps, producers. Returns profiles with LinkedIn data.
+
+```bash
+recoup research people "A&R reps at Atlantic Records"
+recoup research people "music managers in Los Angeles R&B"
+```
+
+See [`POST /api/research/people`](/api-reference/research/people).
+
+### Extract URL
+
+Extract clean markdown content from any public URL. Handles JavaScript-heavy pages and PDFs.
+
+```bash
+recoup research extract "https://en.wikipedia.org/wiki/Drake_(musician)" --objective "biography and discography"
+recoup research extract "https://open.spotify.com/artist/..." --full-content
+```
+
+Accepts up to 10 URLs per call.
+
+See [`POST /api/research/extract`](/api-reference/research/extract).
+
+### Enrich
+
+Get structured data about any entity from web research. Provide a description and a JSON schema — get typed data back with citations.
+
+```bash
+recoup research enrich "Drake rapper" --schema '{"properties": {"real_name": {"type": "string"}, "label": {"type": "string"}, "hometown": {"type": "string"}}}'
+```
+
+Processors: `base` (fast, default), `core` (balanced), `ultra` (comprehensive).
+
+See [`POST /api/research/enrich`](/api-reference/research/enrich).
+
+### Using Recoup artist IDs
+
+Artist IDs are supported on artist-scoped commands (see the note above). Example:
+
+```bash
+recoup research metrics de05ba8c-7e29-4f1a-93a7-3635653599f6 --source spotify
+```
+
+### Workflow example: full artist research
+
+```bash
+# Pull structured data (all by name, run in parallel)
+recoup research metrics "Phoebe Bridgers" --source spotify --json
+recoup research audience "Phoebe Bridgers" --json
+recoup research cities "Phoebe Bridgers" --json
+recoup research similar "Phoebe Bridgers" --audience high --genre high --json
+recoup research playlists "Phoebe Bridgers" --editorial --json
+
+# Add web context
+recoup research web "Phoebe Bridgers biography career milestones" --json
+recoup research web "Phoebe Bridgers fan community brand partnerships" --json
+```
+
+---
+
## content
Content-creation pipeline commands. Generate AI-powered social videos for artists.
diff --git a/docs.json b/docs.json
index 9639f6b..11c47fb 100644
--- a/docs.json
+++ b/docs.json
@@ -147,6 +147,41 @@
"api-reference/workspaces/create"
]
},
+ {
+ "group": "Research",
+ "pages": [
+ "api-reference/research/search",
+ "api-reference/research/lookup",
+ "api-reference/research/profile",
+ "api-reference/research/metrics",
+ "api-reference/research/audience",
+ "api-reference/research/cities",
+ "api-reference/research/similar",
+ "api-reference/research/urls",
+ "api-reference/research/instagram-posts",
+ "api-reference/research/playlists",
+ "api-reference/research/albums",
+ "api-reference/research/tracks",
+ "api-reference/research/track",
+ "api-reference/research/career",
+ "api-reference/research/insights",
+ "api-reference/research/playlist",
+ "api-reference/research/curator",
+ "api-reference/research/discover",
+ "api-reference/research/genres",
+ "api-reference/research/festivals",
+ "api-reference/research/web",
+ "api-reference/research/deep",
+ "api-reference/research/people",
+ "api-reference/research/extract",
+ "api-reference/research/enrich",
+ "api-reference/research/milestones",
+ "api-reference/research/venues",
+ "api-reference/research/rank",
+ "api-reference/research/charts",
+ "api-reference/research/radio"
+ ]
+ },
{
"group": "Spotify",
"pages": [