Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.particle.pro/llms.txt

Use this file to discover all available pages before exploring further.

Most podcast APIs give you metadata — titles, descriptions, RSS feeds. Particle API gives you what’s in the audio. Every episode is transcribed and diarized, broken into structural segments (intros, ads, topic discussions, interviews), distilled into engagement-scored clips, and linked to a knowledge graph of speakers, entities, and topics. The shows themselves are scored for political bias with structured evidence.

​
What you can build

  • Entity tracking — Find every episode, segment, and dialogue line where a person or company is discussed.
  • Highlight reels — Pull engagement-scored clips with ready-to-share intro_statement copy and direct MP3 URLs.
  • Sponsor analytics — See which podcasts a competitor advertises on, who co-sponsors with whom, and host-read vs pre-recorded breakdowns.
  • Research tools — Search transcripts with timestamps, exports as JSON or SRT, scoped by speaker or time range.
  • Bias analysis — Audit a show’s leaning with structured transcript_evidence and web_research_evidence.

​
Resource hierarchy

Every resource is reachable both scoped to its parent (e.g., segments for a specific episode) and across the catalog (e.g., all segments matching a filter). Heavier endpoints — full transcripts, transcript mentions, cross-catalog segments and clip search, and advertising analytics — are priced higher per call than light metadata lookups; see Concepts → Pricing weight.

Episodes

Cross-podcast discovery, filtering, and per-episode sub-resources.

Guests

The people who appear on shows — lifetime profiles, appearances, trending press tours, and brand-suitability exposure.

Transcripts

Diarized dialogue, word-level timestamps, SRT export, and entity mentions in context.

Segments & clips

AI-identified structural sections and engagement-scored highlight moments.

Advertising

Sponsors, leaderboards, co-occurrence, and per-company ad presence.

External links

Every directory, social profile, video channel, and website the podcast lives on — with resolved URLs and audience metrics.

Lookup by external ID

Reverse the external-links index: resolve Apple, Spotify, YouTube, and other platform identifiers to Particle podcasts in bulk.

Publishers

Browse the organizations behind the catalog and pivot from a publisher to its full lineup of podcasts.

Ratings & reviews

User-generated 1–5 star ratings and review text, per-platform star histograms, and a periodic LLM-generated narrative summary of listener sentiment.

​
Get a podcast

Resolve by slug, canonical ID, or numeric Apple/iTunes collection ID: 
curl "https://api.particle.pro/v1/podcasts/pivot" \
  -H "X-API-Key: $PARTICLE_API_KEY"
Response from GET /v1/podcasts/pivot (truncated)
{
  "id": "QpMz7GYKfSNuUa6zKXA4Q",
  "title": "Pivot",
  "slug": "pivot",
  "language": "en",
  "episode_count": 167,
  "bias": "LEANS_LEFT",
  "political_context": "US",
  "speakers": [
    { "name": "Kara Swisher", "role": "HOST", "occurrences": 164, "entity_slug": "kara-swisher" },
    { "name": "Scott Galloway", "role": "HOST", "occurrences": 136, "entity_slug": "scott-galloway" }
  ]
}
The speakers array is the recurring cast aggregated across episodes. Each entity_slug is a knowledge-graph handle you can pass to entities endpoints or to GET /v1/podcasts/episodes?entity_id=… to follow that speaker across the whole catalog.
Already have a platform-native ID? A numeric Apple/iTunes collection ID can be passed straight into the {id} slot — e.g. GET /v1/podcasts/1535809341 — no lookup needed. For a Spotify show ID, YouTube channel ID, RSS feed URL, or other platform identifier, use GET /v1/podcasts/lookup to deterministically resolve any of them (or up to 100 in a single call) to Particle podcasts.

​
Search by name

If you only know the show by name, list podcasts with a fuzzy q= filter — it’s case-insensitive and matches title and description: 
curl --get "https://api.particle.pro/v1/podcasts" \
  --data-urlencode "q=hard fork" \
  --data-urlencode "limit=3" \
  -H "X-API-Key: $PARTICLE_API_KEY"
The response is a paginated list of compact podcast objects — same PageResponse<Podcast> envelope used by every list endpoint, ranked by match quality. q= is a ranked text search, not a deterministic mapping: the top hit is usually right but isn’t guaranteed to be. If you need a deterministic answer keyed on a platform-native identifier (Apple, Spotify, YouTube, …), use GET /v1/podcasts/lookup instead.

​
Curate by popularity and topic

The list endpoint is also a discovery tool. Filter by topic_id, language, or suitability_tier, and narrow to the most popular shows with popularity_threshold. Currently-charting podcasts carry a popularity field — a global popularity percentile in (0,1] (a cume_dist ranking over every charting podcast, where 1.0 is the single most popular show). It is omitted for podcasts not currently on any chart. popularity_threshold filters on that same value (and, because non-charting podcasts have no percentile, excludes them whenever it is set): 
curl --get "https://api.particle.pro/v1/podcasts" \
  --data-urlencode "topic_id=sports/football/fantasy-football" \
  --data-urlencode "popularity_threshold=0.75" \
  -H "X-API-Key: $PARTICLE_API_KEY"
This returns the top-quartile-popularity podcasts where fantasy football is a substantive share of the show — the topic_id filter requires the topic to carry at least 20% of a podcast’s episodes and ranks by topic concentration. popularity_threshold is always global: it ranks across all charting podcasts, never within topic_id or any other filter. Podcasts that aren’t currently charting have no percentile and are excluded whenever the filter is set, so a high threshold on a narrow topic can return nothing — lower or drop popularity_threshold to widen the set. This pairs naturally with the episode feed: curate a list here, then hand its podcast IDs to the feed as an explicit, stable podcast_ids set instead of the feed’s dynamic popularity stream.

​
Bias analysis

Every podcast carries a quick bias enum (LEANS_LEFT, LEANS_RIGHT, CENTER, MIXED, UNCLEAR) on the podcast resource. The bias endpoint returns the underlying analysis: structured reasoning, transcript-level evidence, web-research evidence, and the sample episodes that drove the conclusion. 
curl "https://api.particle.pro/v1/podcasts/pivot/bias" \
  -H "X-API-Key: $PARTICLE_API_KEY"
Response (truncated)
{
  "result": "LEANS_LEFT",
  "political_context": "US",
  "confidence": "MEDIUM",
  "reasoning": "…",
  "transcript_evidence": "…",
  "web_research_evidence": "…",
  "sample_episode_ids": ["…", "…"],
  "episodes_analyzed": 15,
  "evaluated_at": "2026-04-09T17:31:06Z"
}
Use the result for filtering or tagging; surface the reasoning and transcript_evidence fields when users want to know why.

​
Mentions across a podcast’s episodes

To find every episode of a single podcast where an entity comes up — without iterating episodes yourself — use the podcast-scoped mentions endpoint: 
curl "https://api.particle.pro/v1/podcasts/pivot/mentions?entity_id=sam-altman&limit=3" \
  -H "X-API-Key: $PARTICLE_API_KEY"
Response (truncated)
{
  "data": [
    {
      "episode": {
        "id": "78cgekLUjCJBUZbj3s5K8Y",
        "title": "WHCD Shooting Aftermath, Musk and Altman Face-Off, Spirit Airlines Bailout",
        "published_at": "2026-04-28T10:00:00Z",
        "has_transcript": true,
        "segment_count": 21,
        "clip_count": 8
      },
      "salience": 0.003,
      "occurrences": 8
    }
  ],
  "has_more": true,
  "cursor": "…"
}
For the dialogue lines around each mention, drill into one episode with transcript mentions.

​
Choosing the right endpoint

I want to…Use this
Resolve a podcast from a third-party identifier (Apple, Spotify, YouTube, …)GET /v1/podcasts/lookup?platform=…&identifier=…
Fuzzy-find a podcast by name when I only know what it’s calledGET /v1/podcasts?q=…
Get the full podcast detail object when I already have a Particle slug or IDGET /v1/podcasts/{id}
Find dialogue that means something — paraphrase-tolerantGET /v1/podcasts/search?semantic_search=…
Find dialogue containing exact tokens or phrases (BM25)GET /v1/podcasts/search?keyword_search=…
Find every line about a person or companyGET /v1/podcasts/mentions?entity_id=…
Combine: ranked dialogue scoped to a person or companyGET /v1/podcasts/search?semantic_search=…&entity_id=…
List every entity mentioned inside one episodeGET /v1/podcasts/episodes/{id}/transcript/mentions
Salience rollup of an entity across one podcast’s episodesGET /v1/podcasts/{id}/mentions?entity_id=…
Episode-level recall by entity (metadata only, no dialogue)GET /v1/podcasts/episodes?entity_id=…
Find the people who appeared on shows, with appearance history and statsGET /v1/podcasts/guests
Browse highlight clips ranked by engagementGET /v1/podcasts/clips — for clips that match dialogue content, use /v1/podcasts/search and read them off the result.
Browse publishers, or list every podcast a publisher producesGET /v1/podcasts/publishers
The split between Search and Mentions is deliberate: Search ranks dialogue by relevance to a query (similarity, BM25, or hybrid). Mentions returns episodes containing a named entity, ordered by recency, with every dialogue line where that name appears. Different shapes for genuinely different questions — see the Search and Mentions pages for full guidance.
  • Search — find dialogue by topic or exact phrase (semantic, keyword, hybrid)
  • Mentions — every line where a person or company is named
  • Guests — the people who appear on shows, their appearances, trends, and suitability exposure
  • Episodes — discovery, filtering, sub-resources
  • Transcripts — dialogue, words, mentions, SRT
  • Segments & clips — structural breakdown and highlight moments
  • Advertising — sponsor analytics
  • External links — directories, social profiles, websites with resolved URLs and audience metrics
  • Lookup by external ID — reverse the external-links index for Apple, Spotify, YouTube, and other platform identifiers
  • Publishers — browse organizations and pivot from a publisher to its catalog
  • Ratings & reviews — user-generated star ratings, review text, per-platform aggregates, and narrative sentiment summaries