# 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