# Podscan.fm — Podcast Intelligence Platform > Markdown mirror of DialtoneApp's public top-site detail page for `podscan.fm`. URL: https://dialtoneapp.com/top-sites/podscan.fm/index.md Canonical HTML: https://dialtoneapp.com/top-sites/podscan.fm ## Summary - Domain: `podscan.fm` - Website: https://podscan.fm - Description: callable surface | score 36 | purchase read only - Label: callable_surface - Payment surface: Not available - Purchase boundary: read_only - Control boundary: unknown - Rank: 230287 ## robots ~~~text # As a condition of accessing this website, you agree to abide by the following # content signals: # (a) If a Content-Signal = yes, you may collect content for the corresponding # use. # (b) If a Content-Signal = no, you may not collect content for the # corresponding use. # (c) If the website operator does not include a Content-Signal for a # corresponding use, the website operator neither grants nor restricts # permission via Content-Signal with respect to the corresponding use. # The content signals and their meanings are: # search: building a search index and providing search results (e.g., returning # hyperlinks and short excerpts from your website's contents). Search does not # include providing AI-generated search summaries. # ai-input: inputting content into one or more AI models (e.g., retrieval # augmented generation, grounding, or other real-time taking of content for # generative AI search answers). # ai-train: training or fine-tuning AI models. # ANY RESTRICTIONS EXPRESSED VIA CONTENT SIGNALS ARE EXPRESS RESERVATIONS OF # RIGHTS UNDER ARTICLE 4 OF THE EUROPEAN UNION DIRECTIVE 2019/790 ON COPYRIGHT # AND RELATED RIGHTS IN THE DIGITAL SINGLE MARKET. # BEGIN Cloudflare Managed content User-agent: * Content-Signal: search=yes,ai-train=no Allow: / User-agent: Amazonbot Disallow: / User-agent: Applebot-Extended Disallow: / User-agent: Bytespider Disallow: / User-agent: CCBot Disallow: / User-agent: ClaudeBot Disallow: / User-agent: CloudflareBrowserRenderingCrawler Disallow: / User-agent: Google-Extended Disallow: / User-agent: GPTBot Disallow: / User-agent: meta-externalagent Disallow: / # END Cloudflare Managed Content Sitemap: https://podscan.fm/sitemap.xml User-agent: * Disallow: User-agent: * Allow: / User-agent: * Disallow: /dashboard User-agent: facebookexternalhit Crawl-delay: 5 User-agent: Applebot Crawl-delay: 2 ~~~ ## llms ~~~text # Podscan > Podscan is a podcast intelligence platform that indexes 4M+ podcasts and processes 35,000+ episodes daily with full transcription, entity recognition, topic extraction, and sentiment analysis. It provides real-time monitoring, search, and analytics through a REST API, MCP Server, and Firehose streaming API. ## API - [REST API Documentation](https://podscan.fm/docs/rest-api): Interactive API reference with all endpoints, parameters, and response schemas (OpenAPI/Swagger) - [REST API Overview](https://podscan.fm/rest-api): Getting started guide for the REST API with authentication and usage examples - [Firehose API](https://podscan.fm/realtime-firehose): Real-time streaming API delivering new episodes as they are processed ## MCP Server - [MCP Server](https://podscan.fm/mcp-server): Connect AI assistants like Claude to Podscan's 80 podcast intelligence tools via the Model Context Protocol - [MCP Server Documentation](https://podscan.fm/docs/mcp-server): Detailed MCP server setup and tool reference - [MCP Endpoint](https://podscan.fm/mcp): Streamable HTTP transport endpoint for MCP clients (OAuth 2.1 authentication) ## AI Integration - [Podscan for AI Agents](https://podscan.fm/for-ai-agents): Landing page with setup guides for Claude Desktop, Claude Code, Cursor, VS Code, and Windsurf - [Agent Discovery](https://podscan.fm/.well-known/agent.json): Machine-readable agent card (A2A-compatible) with capabilities and authentication details - [Full LLM Documentation](https://podscan.fm/llms-full.txt): Comprehensive integration guide for AI agents including all MCP tools, REST API patterns, and use cases ## Optional - [Webhook Documentation](https://podscan.fm/docs/alert-webhook): Configure webhooks for real-time alert notifications - [Data Exports](https://podscan.fm/docs/exports): Bulk data export documentation - [OpenAPI Spec](https://podscan.fm/docs/api.json): Machine-readable OpenAPI 3.x specification - [Pricing](https://podscan.fm/pricing): Plans and API access tiers ~~~ ## llms-full ~~~text # Podscan — AI Agent Integration Guide > Podscan is a podcast intelligence platform that indexes 4M+ podcasts and processes 35,000+ episodes daily. It provides full transcription, entity recognition (people, brands, organizations), topic extraction, sentiment analysis, and audience demographics. This document is designed for AI agents and developers integrating with Podscan. ## Table of Contents 1. Platform Overview 2. MCP Server (Model Context Protocol) 3. REST API 4. Key Concepts 5. Common Use Cases 6. Rate Limits & Quotas --- ## 1. Platform Overview Podscan continuously monitors the podcast ecosystem in near real-time (~10 minute processing time from episode publication). Key capabilities: - **Full-text transcription** of every episode with speaker diarization - **Entity recognition** — identifies people, brands, and organizations mentioned in episodes - **Topic extraction** — surfaces discussion themes and tracks their momentum over time - **Sentiment analysis** — evaluates the emotional context of mentions - **Audience demographics** — language, region, audience size estimates - **Chart tracking** — Apple Podcasts and Spotify chart rankings across countries and categories - **Alert monitoring** — keyword/phrase monitoring with Boolean expressions and AI-powered contextual filtering ### Scale - 4,000,000+ podcasts indexed - 35,000+ new episodes processed daily - Full transcripts for all episodes - 100+ countries covered in chart tracking --- ## 2. MCP Server (Model Context Protocol) ### Connection Details - **Endpoint**: `https://podscan.fm/mcp` - **Transport**: Streamable HTTP - **Authentication**: OAuth 2.1 (for web-based clients) or Bearer token (for CLI tools) ### Authentication **For CLI tools (Claude Code, Cursor, etc.):** 1. Sign up at https://podscan.fm/register 2. Generate an API token in your dashboard under Team Settings > API Tokens 3. Use the token as a Bearer token in the Authorization header **For web-based clients (Claude Desktop, etc.):** OAuth 2.1 flow is handled automatically by the MCP client. **Multi-team support**: All team-scoped tools accept an optional `team_id` parameter, defaulting to the authenticated user's current team. ### MCP Client Configuration **Claude Desktop** (`claude_desktop_config.json`): ```json { "mcpServers": { "podscan": { "url": "https://podscan.fm/mcp" } } } ``` **Claude Code:** ```bash claude mcp add --transport http podscan https://podscan.fm/mcp ``` **Cursor** (`.cursor/mcp.json`): ```json { "mcpServers": { "podscan": { "url": "https://podscan.fm/mcp" } } } ``` **VS Code** (`.vscode/mcp.json`): ```json { "servers": { "podscan": { "type": "http", "url": "https://podscan.fm/mcp" } } } ``` **Windsurf** (`~/.codeium/windsurf/mcp_config.json`): ```json { "mcpServers": { "podscan": { "serverUrl": "https://podscan.fm/mcp" } } } ``` ### Available MCP Tools (80 total) #### Search Tools **search-episodes-tool** Search podcast episodes by keyword across transcripts, titles, and descriptions. Returns matching episodes with metadata, summaries, and search highlights. Supports filters for language, location, audience size, categories, and guest/sponsor presence. Parameters: - `query` (required): Search keywords - `language`: Filter by language code (e.g., "en", "es") - `location`: Filter by country/region - `min_audience`: Minimum audience size - `categories`: Filter by podcast categories - `has_guests`: Filter for episodes with guests - `has_sponsors`: Filter for episodes with sponsors - `page`: Page number for pagination **search-podcasts-tool** Search podcasts by name, topic, or characteristics. Filter by audience size, language, categories, and whether they feature guests or sponsors. Parameters: - `query` (required): Search keywords - `language`: Filter by language - `min_audience`: Minimum audience size - `has_guests`: Filter for podcasts featuring guests - `has_sponsors`: Filter for podcasts with sponsors - `page`: Page number **search-people-brands-tool** Search for people and organizations mentioned in podcasts. Find hosts, guests, sponsors, or general mentions. Filter by role (host, guest, sponsor, producer, mention). Parameters: - `query` (required): Person or brand name - `role`: Filter by role type - `page`: Page number **search-topics-tool** Search for topics discussed in podcasts. Topics are subjects, themes, and keywords extracted from episode content. Parameters: - `query` (required): Topic keywords - `page`: Page number **search-publishers-tool** Search podcast publishers by name or description. Parameters: - `query` (required): Search keywords - `page`: Page number #### Podcast Retrieval Tools **get-podcast-tool** Get detailed information about a specific podcast including metadata, reach metrics, ratings, categories, and optionally recent episodes. Parameters: - `id` (required): Podcast ID (format: `pd_xxx`) - `include_episodes`: Whether to include recent episodes **get-podcast-episodes-tool** List episodes for a specific podcast. Filter by date range, guest/sponsor presence, and title keywords. Supports pagination and sorting. Parameters: - `id` (required): Podcast ID - `date_from`: Start date filter - `date_to`: End date filter - `has_guests`: Filter for episodes with guests - `has_sponsors`: Filter for episodes with sponsors - `search`: Title keyword search - `sort`: Sort order - `page`: Page number **get-similar-podcasts-tool** Find podcasts similar to a given podcast based on topic overlap, audience, and content analysis. Parameters: - `id` (required): Podcast ID **get-podcast-reviews-tool** Get review and rating information from Apple Podcasts and Spotify. Returns average ratings, rating counts, and rating distribution. Parameters: - `id` (required): Podcast ID **get-podcast-demographics-tool** Find podcasts matching specific demographic criteria. Filter by audience size, language, region, and categories. Parameters: - `language`: Language filter - `region`: Region/country filter - `min_audience`: Minimum audience size - `categories`: Category filter - `page`: Page number **get-publisher-tool** Get information about a podcast publisher or network including their portfolio of podcasts. Parameters: - `id` (required): Publisher ID (format: `pb_xxx`) **get-podcast-brand-safety-tool** Get GARM brand safety assessment for a podcast including risk level distribution. Parameters: - `id` (required): Podcast ID (format: `pd_xxx`) **get-latest-episode-tool** Get the most recent transcribed episode for a podcast. Parameters: - `id` (required): Podcast ID **get-latest-guests-tool** Get the latest episode featuring guests for a podcast. Parameters: - `id` (required): Podcast ID **get-latest-sponsors-tool** Get the latest episode mentioning sponsors for a podcast. Parameters: - `id` (required): Podcast ID **get-podcast-rankings-tool** Get podcasts ranked by Podcast Reach Score (PRS). Parameters: - `min_score`: Minimum PRS score - `max_score`: Maximum PRS score - `limit`: Number of results - `page`: Page number **get-podcast-analysis-tool** Get guest, sponsor, host, and catchup analysis for a podcast based on processed episode extractions. Parameters: - `podcast_id` (required): Podcast ID (format: `pd_xxx`) **get-podcast-chart-history-tool** Get chart position history and trend analysis for a podcast across Apple and Spotify charts. Parameters: - `podcast_id` (required): Podcast ID (format: `pd_xxx`) - `days`: Number of days of history (default: 30, min: 7, max: 30) #### Episode Retrieval Tools **get-episode-tool** Get detailed information about a specific episode including summary, topics, hosts, guests, sponsors, and optionally the transcript. Parameters: - `id` (required): Episode ID (format: `ep_xxx`) - `include_transcript`: Whether to include the full transcript **get-episode-transcript-tool** Get the full transcript of a podcast episode. Supports plain text or timestamped format. Can search within the transcript and return matching excerpts. Parameters: - `id` (required): Episode ID - `format`: "plain" or "timestamped" - `search`: Search within the transcript **get-recent-episodes-tool** Get the most recently published episodes across all podcasts. Filter by date range, categories, language, and guest/sponsor presence. Parameters: - `date_from`: Start date - `date_to`: End date - `categories`: Category filter - `language`: Language filter - `has_guests`: Filter for guest episodes - `has_sponsors`: Filter for sponsored episodes - `page`: Page number **get-episode-entities-tool** Get all people and organizations mentioned in an episode, grouped by role (host, guest, sponsor, mention). Parameters: - `id` (required): Episode ID (format: `ep_xxx`) **get-episode-demographics-tool** Get audience demographic insights for a specific episode. Parameters: - `id` (required): Episode ID **get-episode-brand-safety-tool** Get GARM brand safety assessment for a specific episode including risk level distribution. Parameters: - `id` (required): Episode ID (format: `ep_xxx`) #### Topic Tools **get-topic-tool** Get detailed information about a topic including occurrence count, momentum score, related topics, and optionally a 30-day mention history. Parameters: - `id` (required): Topic ID (format: `tp_xxx`) - `include_history`: Include 30-day mention history **get-topic-episodes-tool** Get episodes where a specific topic was mentioned. Filter by podcast characteristics like audience size, guest presence, and sponsors. Parameters: - `id` (required): Topic ID - `min_audience`: Minimum audience size - `has_guests`: Filter for guest episodes - `has_sponsors`: Filter for sponsored episodes - `page`: Page number **get-trending-topics-tool** Get topics currently trending based on mention growth and recent activity. Useful for trend analysis, content ideation, and market research. Parameters: - `include_history`: Include trend data - `include_related`: Include related topics - `page`: Page number **get-related-topics-tool** Get topics related to a specific topic by co-occurrence in episodes. Parameters: - `id` (required): Topic ID (format: `tp_xxx`) **get-topic-demographics-tool** Get audience demographics for podcasts discussing a specific topic. Returns demographic profiles (age, gender, education, engagement, purchasing power) for podcasts where this topic has been mentioned. Parameters: - `topic_id` (required): Topic ID (format: `tp_xxx`) - `page`: Page number for pagination - `per_page`: Results per page (max 100, default 20) #### Topic Collection Tools **list-topic-collections-tool** Browse curated topic collections — groups of podcasts organized by topic with relevance scoring. Parameters: - `limit`: Number of collections to return (default: 25, max: 100) - `page`: Page number for pagination (default: 1) **get-topic-collection-tool** Get details of a specific topic collection including its top podcasts. Parameters: - `slug` (required): Topic collection slug (URL-friendly identifier) - `limit`: Number of top podcasts to include (default: 25, max: 100) #### Entity Tools (People & Organizations) **get-entity-tool** Get detailed information about a person or organization including appearance statistics, social links, and optionally recent appearances. Parameters: - `id` (required): Entity ID (format: `en_xxx`) - `include_appearances`: Include recent appearances **get-entity-appearances-tool** Get all podcast appearances for an entity. Filter by role (host, guest, sponsor), date range, or specific podcast. Parameters: - `id` (required): Entity ID - `role`: Filter by role - `date_from`: Start date - `date_to`: End date - `podcast_id`: Filter to a specific podcast - `page`: Page number #### Chart Tools **get-charts-tool** Get podcast chart rankings from Apple Podcasts and Spotify. View top podcasts by category, country, and chart type. Parameters: - `platform`: "apple" or "spotify" - `country`: Country code (e.g., "us", "gb") - `category`: Chart category - `chart_type`: Type of chart **get-chart-countries-tool** Get available or supported countries for chart data. Parameters: - `type`: "available" or "supported" **get-chart-categories-tool** Get chart categories for a platform and country. Parameters: - `platform` (required): "apple" or "spotify" - `country` (required): Country code **get-chart-movements-tool** Get chart position movements for podcasts in a category. Parameters: - `platform` (required): "apple" or "spotify" - `country` (required): Country code - `category` (required): Category identifier **get-chart-top-podcasts-tool** Get top-ranked podcasts in a chart category. Parameters: - `platform` (required): "apple" or "spotify" - `country` (required): Country code - `category` (required): Category identifier **get-chart-trending-tool** Get trending podcasts for a country. Parameters: - `country` (required): Country code #### Category Tools **list-categories-tool** List all podcast categories. Parameters: None required. **list-iab-categories-tool** List IAB Tech Lab content taxonomy categories. Parameters: None required. #### Alert Tools **create-alert-tool** Create a content monitoring alert. Alerts monitor podcast transcripts, titles, and descriptions for matching content. Supports Boolean expressions (AND, OR, NOT) and wildcard patterns. Parameters: - `name` (required): Alert name - `filters` (required): Keywords/phrases to monitor (up to 10) - `webhook_url`: URL for real-time notifications **list-alerts-tool** List all content monitoring alerts for your team. Returns alert names, filter configurations, mention counts, and notification settings. Parameters: None required. **get-alert-mentions-tool** Get mentions found by a specific alert. Returns episode details, matched excerpts with timestamps, and sentiment analysis. Parameters: - `id` (required): Alert ID (format: `al_xxx`) - `page`: Page number **get-mention-detail-tool** Get detailed information about a specific alert mention. Parameters: - `id` (required): Mention ID (format: `mn_xxx`) **update-alert-tool** Modify an existing alert's settings, filters, or notification preferences. Parameters: - `id` (required): Alert ID (format: `al_xxx`) - `name`: New alert name - `filters`: Updated keywords/phrases - `enabled`: Enable/disable the alert **delete-alert-tool** Permanently remove an alert and all its mentions. Parameters: - `id` (required): Alert ID **export-mentions-tool** Export alert mentions as JSON or CSV with date filtering. Parameters: - `id` (required): Alert ID (format: `al_xxx`) - `format`: Export format ("json" or "csv") - `date_from`: Start date filter - `date_to`: End date filter #### List Tools **list-user-lists-tool** List all content collections (lists) for your team. Returns list names, descriptions, item counts, and creation dates. Parameters: None required. **get-list-items-tool** Get contents of a specific list including podcasts, episodes, entities, and topics. Parameters: - `id` (required): List ID (format: `cl_xxx`) - `page`: Page number **add-to-list-tool** Add items to an existing list. Supports podcasts, episodes, entities, topics, and mentions. Parameters: - `list_id` (required): List ID - `item_id` (required): ID of the item to add - `item_type` (required): Type of item ("podcast", "episode", "entity", "topic", "mention") **create-list-tool** Create a new content collection. Parameters: - `name` (required): List name - `description`: Optional description **remove-from-list-tool** Remove an item from an existing list. Parameters: - `list_id` (required): List ID - `item_id` (required): ID of the item to remove **update-list-tool** Update list name or description. Parameters: - `id` (required): List ID (format: `cl_xxx`) - `name`: New name - `description`: New description **delete-list-tool** Permanently delete a list and all its items. Parameters: - `id` (required): List ID #### Report Tools **list-reports-tool** List reports for your team with optional status filtering. Parameters: - `status`: Filter by status (pending, processing, completed, failed, cancelled) - `page`: Page number **create-report-tool** Create a historical search report across the podcast archive. Parameters: - `keywords` (required): Search terms - `lookback_days`: How far back to search (plan-dependent) - `language`: Language filter - `region`: Region filter - `categories`: Category filter **get-report-tool** Get full report details with paginated results. Parameters: - `id` (required): Report ID (format: `rp_xxx`) - `page`: Page number **get-report-status-tool** Lightweight polling for report processing progress. Parameters: - `id` (required): Report ID **cancel-report-tool** Cancel a pending or processing report. Parameters: - `id` (required): Report ID **retry-report-tool** Re-run a completed, failed, or cancelled report. Parameters: - `id` (required): Report ID **export-report-tool** Export report results as JSON or Markdown. Parameters: - `id` (required): Report ID - `format`: "json" or "markdown" **delete-report-tool** Archive a report (soft delete). Parameters: - `id` (required): Report ID **share-report-tool** Share a report via a public link that doesn't require authentication. Parameters: - `id` (required): Report ID (format: `rp_xxx`) **unshare-report-tool** Remove public sharing from a report, revoking the share link. Parameters: - `id` (required): Report ID (format: `rp_xxx`) #### Sponsor Tools **browse-sponsors-tool** Browse podcast sponsors with filtering and sorting options. Discover sponsors by mention count, reach, time period, and podcast categories. Parameters: - `sort`: Sort order (e.g., "mentions", "reach", "recent") - `categories`: Filter by podcast categories - `time_period`: Filter by time period - `page`: Page number **search-sponsors-tool** Search for podcast sponsors by name. Parameters: - `query` (required): Sponsor name to search - `page`: Page number **get-sponsor-tool** Get detailed sponsor profile including reach score, podcast count, episode count, and activity timeline. Optionally includes recent sponsor segment transcripts from episodes. Parameters: - `sponsor_id` (required): Sponsor entity ID (format: `en_xxx`) - `include_segment_transcripts`: Include recent ad read transcripts (default: false) **get-sponsor-podcasts-tool** Get podcasts where a sponsor has appeared with episode counts and date ranges. Parameters: - `sponsor_id` (required): Sponsor entity ID (format: `en_xxx`) - `page`: Page number **get-sponsor-trend-tool** Get sponsorship activity trend over time for a specific sponsor. Parameters: - `sponsor_id` (required): Sponsor entity ID (format: `en_xxx`) - `days`: Number of days of history (default: 90) #### Share of Voice Tools **list-competitive-sets-tool** List all Share of Voice competitive sets for your team. Parameters: None required. **create-competitive-set-tool** Create a new competitive intelligence set for tracking brand share of voice. Parameters: - `name` (required): Set name - `brands`: Initial brands to add **get-competitive-set-tool** Get details of a competitive set including all brands and their current SOV data. Parameters: - `id` (required): Competitive set ID **add-brand-to-set-tool** Add a brand to an existing competitive set. Parameters: - `set_id` (required): Competitive set ID - `brand_name` (required): Brand name to add - `keywords`: Additional keywords to monitor for this brand **get-sov-data-tool** Get current Share of Voice data for all brands in a competitive set. Parameters: - `set_id` (required): Competitive set ID **get-sov-time-series-tool** Get SOV trend data over time showing how brand conversation share changes. Parameters: - `set_id` (required): Competitive set ID - `days`: Number of days of history **get-sov-sentiment-tool** Get sentiment analysis breakdown per brand in a competitive set. Parameters: - `set_id` (required): Competitive set ID **get-sov-keyword-matches-tool** Get detailed keyword match drill-down for a Share of Voice brand, showing which episodes matched and why. Returns match details including keywords, excerpts, verification status, and episode context. Parameters: - `set_id` (required): Competitive set ID (format: `cs_xxx`) - `brand_id` (required): Brand/competitive set entity ID (format: `cb_xxx`) - `period`: Time period: "7d", "30d" (default), or "90d" - `page`: Page number for pagination (default: 1) #### Category Leaders **search-category-leaders-tool** Find top podcasts by Apple/Spotify category, IAB category, or chart position — includes contact data and audience metrics for outreach. Results are ranked by Podscan Reach Score (PRS) and deduplicated. Parameters: - `selections` (required): Array of category selections. Each needs: type ("category", "iab", or "chart"), id (category/chart ID). For chart type, also accepts country and platform. - `limit`: Maximum number of results to return (clamped to plan limit) #### Utility Tools **suggest-podcast-tool** Submit a new podcast for indexing by providing its RSS feed URL. Validates the URL, checks if the podcast already exists, and queues it for processing. Parameters: - `rss_url` (required): The RSS feed URL of the podcast to suggest --- ## 3. REST API ### Authentication All API requests require a Bearer token in the Authorization header: ``` Authorization: Bearer YOUR_API_TOKEN ``` Generate tokens in your Podscan dashboard under Team Settings > API Tokens. ### Base URL ``` https://api.podscan.fm/v1 ``` ### Interactive Documentation Full API reference with all endpoints, parameters, request/response examples, and the ability to try requests directly: - **Interactive API Docs (Scalar)**: https://podscan.fm/docs/rest-api - **OpenAPI Spec**: https://podscan.fm/docs/api.json Use the "Copy as Markdown" button in the interactive docs to export the full API spec for offline reference. ### Key Endpoints | Method | Endpoint | Description | |--------|----------|-------------| | GET | `/podcasts` | Search and list podcasts | | GET | `/podcasts/{id}` | Get podcast details | | GET | `/podcasts/{id}/episodes` | List podcast episodes | | GET | `/episodes` | Search episodes | | GET | `/episodes/{id}` | Get episode details | | GET | `/episodes/{id}/transcript` | Get episode transcript | | GET | `/entities` | Search people and brands | | GET | `/entities/{id}` | Get entity details | | GET | `/topics` | Search topics | | GET | `/topics/{id}` | Get topic details | | GET | `/topics/trending` | Get trending topics | | GET | `/scans` | List alerts | | POST | `/scans` | Create an alert | | GET | `/scans/{id}/mentions` | Get alert mentions | | GET | `/lists` | List collections | | GET | `/lists/{id}` | Get list items | | GET | `/charts` | Get podcast charts | | GET | `/podcasts/{id}/analysis` | Get podcast guest/sponsor/host analysis | | GET | `/podcasts/{id}/chart-history` | Get podcast chart ranking history | | GET | `/episodes/{id}/engagement` | Get episode listener engagement (add-on) | | GET | `/topics/{id}/demographics` | Get topic audience demographics | | GET | `/topics/trending/export` | Export trending topics as CSV | | GET | `/topic-collections` | List topic collections | | GET | `/topic-collections/{slug}` | Get topic collection details | | POST | `/category-leaders/search` | Search category leaders | | POST | `/category-leaders/export` | Export category leaders as CSV | | GET | `/teams/{team}/alert-groups` | List alert groups | | POST | `/teams/{team}/alert-groups` | Create alert group | ### Pagination All list endpoints support pagination via `page` parameter. Responses include pagination metadata: ```json { "data": [...], "meta": { "current_page": 1, "last_page": 10, "per_page": 25, "total": 250 } } ``` --- ## 4. Key Concepts ### ID Format All resources use encoded IDs with type prefixes for clarity: | Prefix | Resource | Example | |--------|----------|---------| | `pd_` | Podcast | `pd_abc123` | | `ep_` | Episode | `ep_def456` | | `tp_` | Topic | `tp_ghi789` | | `en_` | Entity (person/org) | `en_jkl012` | | `ea_` | Entity Appearance | `ea_mno345` | | `al_` | Alert | `al_pqr678` | | `mn_` | Mention | `mn_stu901` | | `cl_` | Collection (List) | `cl_vwx234` | | `pb_` | Publisher | `pb_yza567` | | `rp_` | Report | `rp_abc123` | | `ct_` | Category | `ct_bcd890` | ### Entity Types Entities represent people and organizations identified in podcast content: - **People**: Hosts, guests, producers, or anyone mentioned by name - **Organizations**: Companies, brands, agencies, or institutions Each entity appearance has a **role**: - `host` — The podcast host - `guest` — A guest on the episode - `sponsor` — A sponsor or advertiser - `producer` — The production team - `mention` — Someone mentioned in conversation but not present ### Topics Topics are themes and subjects automatically extracted from episode content. Each topic has: - **Occurrences**: Total number of episodes mentioning this topic - **Momentum**: A score reflecting growth in mentions over recent periods - **Related topics**: Other topics frequently discussed alongside this one ### Alerts (Scans) Alerts monitor new podcast content for keyword matches. Features: - **Boolean expressions**: Use AND, OR, NOT for precise matching - **Wildcards**: Use `*` for partial matching (e.g., `AI*` matches "AI", "AI-powered", "AIops") - **Up to 10 filters per alert**: Each filter is an independent search expression - **Context-aware questions**: Follow-up yes/no questions that filter mentions after keyword matching to reduce false positives - **Question suggestions**: Generates context-aware yes/no questions from your alert name and keyword filters, optimized to disambiguate your target topic from common false positive scenarios - **Sentiment analysis**: Automatic emotional context evaluation for each mention - **Webhooks**: Real-time HTTP notifications when matches are found ### Lists (Collections) Lists are curated collections for organizing content. A list can contain mixed item types: - Podcasts, Episodes, Entities, Topics, and Mentions --- ## 5. Common Use Cases ### Brand Monitoring Track when your brand, competitors, or industry terms are mentioned across podcasts. 1. Create an alert: `create-alert-tool` with brand name and variations 2. Check mentions regularly: `get-alert-mentions-tool` for matched content with sentiment 3. Search historically: `search-episodes-tool` for past mentions 4. Organize findings: `add-to-list-tool` to save important mentions **Example prompt**: "Set up monitoring for mentions of 'Acme Corp' or 'AcmeCo' across all podcasts and show me recent mentions with sentiment analysis." ### Competitive Intelligence Monitor competitor activity and industry discussions. 1. Search for competitor mentions: `search-people-brands-tool` with competitor name 2. Track their podcast appearances: `get-entity-appearances-tool` filtered by role 3. Find similar podcasts to theirs: `get-similar-podcasts-tool` 4. Monitor trending topics in your industry: `get-trending-topics-tool` **Example prompt**: "Find all podcast appearances by the CEO of [competitor] in the last 3 months and summarize what topics they discussed." ### Transcript Search & Analysis Search across millions of podcast transcripts for specific content. 1. Search episodes: `search-episodes-tool` with keywords 2. Get full transcripts: `get-episode-transcript-tool` with search highlighting 3. Analyze topics covered: `get-topic-tool` for topic details and trends 4. Explore related content: `get-topic-episodes-tool` for more episodes on the same topic **Example prompt**: "Find podcast episodes that discuss 'remote work productivity tools' and extract the key recommendations from the transcripts." ### Audience Research Understand podcast audiences and demographics for a target market. 1. Find podcasts by demographics: `get-podcast-demographics-tool` with audience criteria 2. Get detailed podcast info: `get-podcast-tool` for reach and audience metrics 3. Check reviews and ratings: `get-podcast-reviews-tool` for audience sentiment 4. Explore chart rankings: `get-charts-tool` for category performance **Example prompt**: "Find English-language podcasts about personal finance with at least 10,000 listeners and show me their audience demographics and ratings." ### PR & Guest Booking Find podcast opportunities for guest appearances. 1. Search relevant podcasts: `search-podcasts-tool` filtered by `has_guests: true` 2. Check podcast details: `get-podcast-tool` for contact info and audience size 3. Review recent episodes: `get-podcast-episodes-tool` to understand content fit 4. Find similar opportunities: `get-similar-podcasts-tool` **Example prompt**: "Find podcasts that regularly feature guests and discuss SaaS entrepreneurship, sorted by audience size." ### Trend Analysis Track emerging topics and industry trends through podcast discussions. 1. Get trending topics: `get-trending-topics-tool` for current trends 2. Explore topic details: `get-topic-tool` for momentum and history 3. Find related episodes: `get-topic-episodes-tool` for content covering the trend 4. Monitor over time: Create alerts for key topics using `create-alert-tool` **Example prompt**: "What topics are trending in podcasts right now? Show me the top 10 with their momentum scores and example episodes." --- ## 6. Rate Limits & Quotas API usage is subject to rate limits based on your subscription plan. Rate limit information is included in response headers: - `X-RateLimit-Limit`: Maximum requests per minute - `X-RateLimit-Remaining`: Remaining requests in current window - `X-RateLimit-Reset`: Timestamp when the limit resets MCP tool usage shares the same quota as REST API calls. --- ## Additional Resources - **Interactive API Docs**: https://podscan.fm/docs/rest-api - **OpenAPI Specification**: https://podscan.fm/docs/api.json - **MCP Server Setup**: https://podscan.fm/mcp-server - **Agent Discovery Card**: https://podscan.fm/.well-known/agent.json - **Pricing & Plans**: https://podscan.fm/pricing - **Support**: arvid@podscan.fm ~~~