--- title: "Search podcasts" method: GET path: "/v1/podcasts/search" tags: ["Podcasts", "tier:standard"] --- # Search podcasts `GET /v1/podcasts/search` ## Request - Base URL: `https://api.particle.pro` - URL: `https://api.particle.pro/v1/podcasts/search` - Auth: one of: - API key in header `X-API-Key` - HTTP bearer Searches the podcast catalog by show name — the canonical podcast search. Functionally equivalent to `GET /v1/podcasts?q=…`: the same forgiving, typo-tolerant ranked search, the same filters (topic, language, suitability tier, popularity, format), and the same `match_quality` signal on each result. To search *inside* episode dialogue, use `/v1/podcasts/episodes/search` instead. ## Query parameters - `limit` integer: Results per page - `cursor` string: Opaque pagination cursor from previous response - `q` string: Search the catalog by podcast name. GET /v1/podcasts/search is the canonical search endpoint and accepts the same parameters. The search is forgiving: it handles typos, missing or extra words ('offline jon favreau' finds Offline with Jon Favreau), a name plus qualifiers ('equity techcrunch'), and pasted episode titles ('Ferrari | Acquired' finds Acquired). The best matches come first, and each result's match_quality tells you how confident the match is — including when a show matched only through its description (match_quality=description) rather than its name. - `sort` 'relevance' | 'popularity': Result ordering. relevance — the default whenever q is present — ranks by how well each podcast matches the query, breaking ties by popularity. popularity orders purely by the global popularity percentile (most popular first; podcasts not currently charting sort last), and also overrides topic_id's concentration ordering. Without q or topic_id, results are popularity-ordered either way. - `slug` string: Filter by exact podcast slug (e.g., 'all-in'). Slugs are stable, human-readable identifiers returned on every podcast object. - `topic_id` string: Filter by topic ID, ancestry slug (e.g., technology/artificial-intelligence), or ancestry path hash. Matches podcasts where the topic accounts for at least 20% of the show's episodes, ranked by topic concentration — not merely podcasts that mention it once. - `language` string: Filter by the podcast's language (ISO 639-1 code, e.g. 'en', 'fr'). Matches the primary language subtag, so 'fr' covers 'fr-FR'. - `suitability_tier` 'SAFE' | 'LIMITED' | 'SENSITIVE' | 'UNSAFE': Filter by brand-suitability tier (IAB Tech Lab Brand Safety & Suitability Framework, formerly GARM). Only returns podcasts whose most recent suitability analysis assigned this tier. Podcasts without a suitability analysis are excluded when this filter is set. - `popularity_threshold` number, double: Restrict results to podcasts whose global popularity percentile is at least this value (accepted range [0,1]). Omitting the parameter or passing 0 disables the filter; only a value greater than 0 activates it. Popularity is always global — a cume_dist ranking over all currently-charting podcasts (Apple Podcasts) — never scoped to topic_id or any other filter. When the filter is active (threshold > 0), podcasts not currently charting have no percentile and are excluded, so a high threshold combined with a narrow topic_id may return zero results; lower or remove the threshold to widen the set. - `guest_frequency` string[], nullable: Filter by how often episodes feature a guest. Pass a comma-separated list to match any of several buckets — e.g. regular,always for interview-driven shows, or never for shows that don't host guests. Only matches podcasts with enough analyzed episodes to judge; values mirror the format.guest_frequency field on podcast responses. - `format_signal` string[], nullable: Filter by detected production format. Pass a comma-separated list to match any of several formats — e.g. panel,call_in. Values mirror the format.signals field on podcast responses; a show can carry several signals. - `has_ads` 'true' | 'false': Filter by advertiser presence. Pass false to find ad-free shows — an assertion that requires the show to have enough analyzed episodes, so sparsely-analyzed podcasts are excluded rather than presumed ad-free. - `has_video` 'true' | 'false': Filter by whether episodes have discovered video versions (e.g. YouTube releases). - `min_avg_episode_minutes` integer: Only podcasts whose average episode runs at least this many minutes. Combine with max_avg_episode_minutes to target a length band (e.g. 20–40 minute commute shows). - `max_avg_episode_minutes` integer: Only podcasts whose average episode runs at most this many minutes. - `min_episodes_per_week` number, double: Only podcasts publishing at least this many episodes per week on average (e.g. 5 for weekday dailies). Cadence is measured over the trailing 90 days; podcasts tracked too briefly to measure are excluded. - `max_episodes_per_week` number, double: Only podcasts publishing at most this many episodes per week on average (e.g. 0.5 for fortnightly-or-slower shows). - `publishing_status` 'active' | 'dormant': Filter by publishing activity: active shows have released an episode within the last 90 days; dormant shows have not. - `guest_occupation` string: Only shows whose analyzed guests include someone listed under this SOC 2018 or ISCO-08 occupation (code, slug, or title), including a SOC group or everyday name such as physicians or doctors. A word with no occupation that names a field of research, such as oncologists, filters by the field; one that names a capacity, such as founders, is rejected. - `guest_field` string: Only shows whose analyzed guests include someone listed under this ANZSRC 2020 field of research (code, slug, or title). - `min_analyzed_guest_appearances` integer: Only shows with at least this many guest appearances analyzed for expertise. Raise it to steady the share filters below on shows with few analyzed guests. - `min_established_guest_share` number, double: Only shows where at least this share of analyzed guest appearances are by guests whose standing others conferred (0-1; 0 sets no bound). - `min_in_field_guest_share` number, double: Only shows where at least this share of analyzed guest appearances stayed within the guest's field (0-1; 0 sets no bound). - `max_promotional_guest_share` number: Only shows where at most this share of analyzed guest appearances were mainly promotional (0-1); 0 keeps only shows with none. ## Response `200` OK - PagePodcast - `cursor` string: Pass to next request for more results - `data` Podcast[], nullable, required: List of results - `bias` string: Political bias rating for the podcast: EXTREME_LEFT, LEANS_LEFT, LEFT, CENTER, RIGHT, LEANS_RIGHT, or EXTREME_RIGHT. Empty when the podcast is not substantively political or has not been evaluated yet. Fetch GET /v1/podcasts/{id}/bias for the full analysis including reasoning and evidence. - `coverage` PodcastCoverage - `back_catalogue` BackCatalogueCoverage - `complete` boolean, required: true when the discovery sources listed the podcast's whole history. false when PodcastIndex capped its listing at 1,000 episodes, so older episodes may exist that neither it nor the podcast's own feed lists. - `feed_item_count` integer: Items the podcast's own feed listed. Absent when the feed could not be read. - `imported_at` string, date-time, required: When the back catalogue was last imported. - `podcastindex_episode_count` integer, required: Episodes PodcastIndex listed, at most 1,000. - `counted_at` string, date-time: When these counts were computed. They refresh hourly, so an episode ingested, transcribed or requested since is not reflected yet; each episode's own transcript_status is always current. - `discovered_episode_count` integer, required: Every episode we know of, transcribed or not: the episodes we have ingested plus the podcast's back catalogue. The transcript_statuses counts sum to it. - `newest_episode_published_at` string, date-time: Publication date of the newest discovered episode. - `oldest_episode_published_at` string, date-time: Publication date of the oldest discovered episode. - `transcript_statuses` TranscriptStatusCount[], nullable, required: Discovered episodes by transcript_status, one entry per status. Unlike episode_count on the podcast, which counts ingested episodes, these include the back catalogue. - `count` integer, required: Discovered episodes with this status. - `transcript_status` 'transcribed' | 'processing' | 'queued' | 'requestable' | 'unavailable', required: The status counted; see Episode.transcript_status. - `years` YearCoverage[], nullable, required: Discovered and transcribed episodes per publication year, newest year first. Episodes without a publication date are counted in the totals only. - `discovered` integer, required: Episodes published that year that we know of. - `transcribed` integer, required: Of those, episodes with a transcript. - `year` integer, required: Publication year (UTC). - `description` string: Podcast description - `episode_count` integer: Total number of episodes - `explicit` boolean, required: Whether the podcast contains explicit content - `format` PodcastFormat - `avg_episode_minutes` integer: Average episode length in minutes. Omitted when no episode durations are known. - `episodes_per_week` number, double: Publishing cadence over the trailing 90 days, in episodes per week (e.g. 5.0 for a weekday daily, 0.5 for a fortnightly show). Omitted until the show has been tracked long enough to measure reliably. - `guest_frequency` string: How often episodes feature a guest: never, rare, occasional, regular, or always. Derived from the share of analyzed episodes with at least one guest speaker. Omitted when too few episodes have been analyzed to judge. Filter the catalog with the guest_frequency query parameter on GET /v1/podcasts. - `has_ads` boolean: Whether episodes carry advertiser reads. Omitted when too few episodes have been analyzed to judge. The full advertising profile (sponsors, read types, ad load) is served by GET /v1/podcasts/{id}/advertising. - `has_video` boolean, required: Whether any episode has a discovered video version (e.g. a YouTube release). - `publishing_status` string: Whether the show is still releasing episodes: active (published within the last 90 days) or dormant. Omitted when no publish dates are known. - `signals` string[], nullable: Production formats detected from the show's speaker-role mix: interview, panel, call_in, and/or solo_narrated. A show can carry several (a panel show with call-in segments). Omitted when too few episodes have been analyzed to judge. - `id` string, required: Unique identifier - `image_url` string: Cover image URL - `language` string: ISO 639-1 language code - `match_quality` 'exact' | 'partial' | 'fuzzy' | 'description' | 'speculative': How confidently this result matches your q search, strongest first. exact: this is the show with that name. partial: the name matches your search strongly (your search may have included extra words). fuzzy: the name is similar but not the same — it may be the show you meant with a typo, or a different show with a near-identical name; verify before relying on it. description: your search text appears in the show's description rather than its name. speculative: a loose suggestion, listed last. When resolving a show programmatically, act on exact or partial results and treat anything weaker as candidates to confirm. Present only when q was provided. - `political_context` string: Political framework the bias rating is calibrated against: US, UK, EU, CANADA, AUSTRALIA, INDIA, OTHER. Omitted when the latest analysis returned NOT_POLITICAL or when no analysis has been run yet. - `popularity` number, double: Global popularity percentile in (0,1], a cume_dist ranking over all currently-charting podcasts (Apple Podcasts charts). Higher is more popular; the most popular podcast is 1.0. Always global — never scoped to a topic_id or other filter. Omitted when the podcast is not currently charting. Pair with the popularity_threshold query parameter on GET /v1/podcasts to filter the catalog by this value. - `publisher` PodcastPublisherCompact - `id` string, required: Publisher ID - `name` string, required: Publisher name - `slug` string: Human-readable slug identifier (e.g., 'goalhanger', 'iheartpodcasts'). When present, accepted in place of the ID anywhere a publisher reference is taken in the API. Occasionally absent on publishers whose name doesn't slugify (e.g., scripts not representable in ASCII URL slugs). - `recommended_guests` RecommendedGuest[], nullable: The five guests the show could plausibly book next (lean form, no via). Present only on GET /v1/podcasts/{id} with include=recommended_guests; the paged list is GET /v1/podcasts/{id}/recommendations/guests. - `band` 'strong' | 'moderate' | 'weak', required: Coarse class of the score. - `person` PersonCompact, required - `description` string: Short description (e.g. current role), when known. - `id` string, required: Encoded Person identifier - `image_url` string: Canonical headshot URL when one is known for the Person - `name` string, required: Display name - `slug` string: Stable human-readable handle (e.g. 'satya-nadella'). Recommended canonical identifier on every Particle Pro person surface. - `score` number, double, required: Strength of the recommendation in (0,1): how related the shows that booked this person are, counted once per publisher and damped for how widely the person already circulates. Recurring on any one show does not raise it, and circuit regulars who appear everywhere are excluded. - `shared_show_count` integer, required: How many of the show's related shows have booked this person. - `via` PodcastCompact[], nullable: The related shows that booked this person, strongest first. - `best_rank` PodcastRankingHandle - `captured_at` string, date-time, required - `category_slug` string - `chart_type` 'top_podcasts', required - `country` string - `rank` integer, required - `source` 'apple' | 'spotify', required - `id` string, required: Podcast ID - `image_url` string: Cover image URL - `popularity` number, double: Global popularity percentile in (0,1], a cume_dist ranking over all currently-charting podcasts (Apple Podcasts charts). Higher is more popular. Omitted when the podcast is not currently charting, on endpoints that build this resource from a projection rather than the full podcast row, and in episode stream, feed and archive payloads, which are stored and replayed: read it live from the podcast endpoints. - `publisher` PodcastPublisherCompact - `id` string, required: Publisher ID - `name` string, required: Publisher name - `slug` string: Human-readable slug identifier (e.g., 'goalhanger', 'iheartpodcasts'). When present, accepted in place of the ID anywhere a publisher reference is taken in the API. Occasionally absent on publishers whose name doesn't slugify (e.g., scripts not representable in ASCII URL slugs). - `slug` string: Human-readable slug identifier - `title` string, required: Podcast title - `recommended_sponsors` RecommendedSponsor[], nullable: The five advertisers most active on shows like this one that do not buy it yet (lean form, no via). Premium-grade: present only on GET /v1/podcasts/{id} with include=recommended_sponsors for plans that include premium endpoints; the paged list is GET /v1/podcasts/{id}/recommendations/sponsors. - `band` 'strong' | 'moderate' | 'weak', required: Coarse class of the score; branch on this rather than on exact thresholds. - `company_contested` boolean: Whether the company link is disputed: true when the recent majority is under 60%, when the declared domain does not map to a company, when a mapped domain is contradicted by an ad majority of 60% or more, and for every all-time fallback; a weak disagreement with a mapped domain is not contested. A contested company is the best available guess — it is still served, but contacts are withheld. - `contacts` RecommendedContact[], nullable: Up to three people at the sponsor's company most likely to own a podcast sponsorship decision (marketing, partnerships, brand, media, communications, growth, then other executives), each with the role class and a LinkedIn URL when known. Present only with include=contacts, only when the sponsor resolves to a company, and never when company_contested is true. - `linkedin_url` string: The person's LinkedIn profile when known — an InMail path even without an email. - `person` PersonCompact, required - `description` string: Short description (e.g. current role), when known. - `id` string, required: Encoded Person identifier - `image_url` string: Canonical headshot URL when one is known for the Person - `name` string, required: Display name - `slug` string: Stable human-readable handle (e.g. 'satya-nadella'). Recommended canonical identifier on every Particle Pro person surface. - `role` 'marketing' | 'brand' | 'partnerships' | 'media_advertising' | 'communications' | 'growth' | 'executive' | 'other', required: Contact role class derived from the title; contacts are ordered by how likely the class is to own a sponsorship decision. - `title` string: Current title at the company, as recorded. - `last_ad_at` string, date-time: Publish date of the sponsor's most recent ad across those shows. - `score` number, double, required: Strength of the recommendation in (0,1): how related the shows that run this sponsor are, counted once per publisher, weighted by whether it is still buying there and how much (saturating after about twenty reads). Compounds across publishers. - `shared_show_count` integer, required: How many of the show's related shows run this sponsor. - `sponsor` SponsorCompact, required - `company` CompanyCompact - `description` string: Short company description, when known. - `domain` string: Primary website domain (e.g. 'nvidia.com'), when known. - `id` string, required: Company identifier (domain, slug, or encoded ID) - `image_url` string: Company logo or image URL - `name` string, required: Company name - `slug` string: Stable human-readable handle (the linked knowledge-graph slug, e.g. 'nvidia'), when known. Companies have no slug of their own; prefer this for display and pass it (or id) to /v1/companies. - `ticker` string: Primary stock ticker symbol, when listed. - `id` string, required: Unique identifier - `name` string, required: Sponsor name - `total_ads` integer, required: The sponsor's ad reads summed over those related shows (network promos excluded). - `via` PodcastCompact[], nullable: The related shows that run this sponsor, most related first (at most three) — the peer set to cite in a pitch. - `best_rank` PodcastRankingHandle - `captured_at` string, date-time, required - `category_slug` string - `chart_type` 'top_podcasts', required - `country` string - `rank` integer, required - `source` 'apple' | 'spotify', required - `id` string, required: Podcast ID - `image_url` string: Cover image URL - `popularity` number, double: Global popularity percentile in (0,1], a cume_dist ranking over all currently-charting podcasts (Apple Podcasts charts). Higher is more popular. Omitted when the podcast is not currently charting, on endpoints that build this resource from a projection rather than the full podcast row, and in episode stream, feed and archive payloads, which are stored and replayed: read it live from the podcast endpoints. - `publisher` PodcastPublisherCompact - `id` string, required: Publisher ID - `name` string, required: Publisher name - `slug` string: Human-readable slug identifier (e.g., 'goalhanger', 'iheartpodcasts'). When present, accepted in place of the ID anywhere a publisher reference is taken in the API. Occasionally absent on publishers whose name doesn't slugify (e.g., scripts not representable in ASCII URL slugs). - `slug` string: Human-readable slug identifier - `title` string, required: Podcast title - `related` RelatedPodcast[], nullable: The five most related podcasts (lean form: podcast, score, band). Present only on GET /v1/podcasts/{id} with include=related, and omitted when the show's related set has not been computed yet. Fetch GET /v1/podcasts/{id}/related for the full ranked list with pagination and the basis (why) behind each result. - `band` 'strong' | 'moderate' | 'weak', required: Coarse class of the score: strong (same beat and audience), moderate (overlapping subject or audience), weak (a loose connection). Branch on this rather than on exact score thresholds. - `basis` RelatedPodcastBasis - `content_similarity` number, double: Cosine similarity of the two shows' content centroids in [0,1]; omitted when either show has too few embedded episodes. - `same_publisher` boolean, required: Both shows belong to the same multi-show publisher (network). - `shared_category_count` integer, required: Number of directory categories the shows share. - `shared_guest_count` integer, required: Number of guests who appeared on both shows. - `shared_guests` PersonCompact[], nullable: Up to three of the shared guests, most significant first. - `description` string: Short description (e.g. current role), when known. - `id` string, required: Encoded Person identifier - `image_url` string: Canonical headshot URL when one is known for the Person - `name` string, required: Display name - `slug` string: Stable human-readable handle (e.g. 'satya-nadella'). Recommended canonical identifier on every Particle Pro person surface. - `shared_sponsor_count` integer, required: Number of advertisers both shows have carried. - `shared_topics` Topic[], nullable: Up to three topics that contribute most to the overlap. - `ancestry` string: Human-readable breadcrumb path (e.g. Business > Technology > AI) - `ancestry_path` string: Hash-based ancestry path for programmatic filtering - `episode_count` integer: Number of episodes in this podcast that cover this topic (only populated for /v1/podcasts/{id} topic lists) - `id` string, required: Unique identifier - `name` string, required: Topic name - `slug` string, required: Ancestry-based slug (e.g., technology/artificial-intelligence). Can be used as topic_id. - `topic_overlap` number, double: Overlap of the shows' topic profiles in [0,1]. - `podcast` PodcastCompact, required - `best_rank` PodcastRankingHandle - `captured_at` string, date-time, required - `category_slug` string - `chart_type` 'top_podcasts', required - `country` string - `rank` integer, required - `source` 'apple' | 'spotify', required - `id` string, required: Podcast ID - `image_url` string: Cover image URL - `popularity` number, double: Global popularity percentile in (0,1], a cume_dist ranking over all currently-charting podcasts (Apple Podcasts charts). Higher is more popular. Omitted when the podcast is not currently charting, on endpoints that build this resource from a projection rather than the full podcast row, and in episode stream, feed and archive payloads, which are stored and replayed: read it live from the podcast endpoints. - `publisher` PodcastPublisherCompact - `id` string, required: Publisher ID - `name` string, required: Publisher name - `slug` string: Human-readable slug identifier (e.g., 'goalhanger', 'iheartpodcasts'). When present, accepted in place of the ID anywhere a publisher reference is taken in the API. Occasionally absent on publishers whose name doesn't slugify (e.g., scripts not representable in ASCII URL slugs). - `slug` string: Human-readable slug identifier - `title` string, required: Podcast title - `score` number, double, required: Fused relatedness in (0,1], calibrated so that higher values are more likely to be judged related. Comparable across shows. - `slug` string: Human-readable slug identifier - `speakers` PodcastSpeaker[], nullable: Top recurring speakers - `entity` EntityCompact - `company` EntityCompany - `domain` string: Company website domain - `id` string, required: Company identifier - `ticker` string: Primary stock ticker symbol - `description` string: Short description - `id` string, required: Entity ID - `image_url` string: Entity image URL - `name` string, required: Entity name - `person` EntityPerson - `company` string: Current company name - `id` string, required: Person identifier - `image_url` string: Person headshot URL - `title` string: Current role title - `slug` string, required: Human-readable slug identifier - `type` EntityType - `name` string, required: Human-friendly display label (e.g. 'Company'). - `slug` string, required: Stable identifier, safe to pass to the type query parameter (e.g. 'company'). - `wikipedia_url` string: Wikipedia URL - `name` string, required: Speaker name - `occurrences` integer: Number of episodes featuring this speaker - `role` string: Speaker role, drawn from the same canonical set as the episode speakers. This show-level view surfaces the podcast's recurring hosts, so expect HOST here; read the per-episode speakers for guests, advertisers, and the rest of the role range. - `suitability_tier` string: High-level brand-suitability verdict from the IAB Tech Lab Brand Safety & Suitability Framework (formerly GARM): SAFE, LIMITED, SENSITIVE, or UNSAFE. Empty when the podcast has not been evaluated yet. Per-category breakdown, evidence, and methodology are gated to GET /v1/podcasts/{id}/suitability. - `title` string, required: Podcast title - `topics` Topic[], nullable: Top topics discussed across episodes, ordered by frequency. Absent when the rollup exceeds its time budget. - `ancestry` string: Human-readable breadcrumb path (e.g. Business > Technology > AI) - `ancestry_path` string: Hash-based ancestry path for programmatic filtering - `episode_count` integer: Number of episodes in this podcast that cover this topic (only populated for /v1/podcasts/{id} topic lists) - `id` string, required: Unique identifier - `name` string, required: Topic name - `slug` string, required: Ancestry-based slug (e.g., technology/artificial-intelligence). Can be used as topic_id. - `url` string: RSS feed URL - `has_more` boolean, required: Whether more results exist ## Other responses - `402`: Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. - `default`: Error --- [API](https://skmtc.dev/particle/apis/particle-api.md) · [All operations](https://skmtc.dev/particle/apis/particle-api/llms.txt) · [OpenAPI document](https://skmtc.dev/particle/apis/particle-api/revisions/416ba82ab9d7?raw)