---
type: "firecrawl-provider"
description: "Podcast intelligence: speaker-labelled transcripts, episode and show search, the people who appear, the sponsors and companies advertising, chart rankings, and bias and brand-suitability analysis."
use_when: "Shows and the episodes inside them. Search finds an episode by what was said; a show's episodes, its publisher, its format, ratings and platform links, and the dialogue itself as transcripts, segments, clips and mentions.\n\nThe people on a podcast: the person record, the same person as a guest with their appearances and the shows that book them, a show's guest roster, who is trending, and who a show could book next.\n\nCompanies as the knowledge graph holds them: the directory by name, ticker, domain or CIK, the people and products behind one, its profile links and its competitors. The company record itself is advertising/company.\n\nWho is advertising and where. Sponsors and the companies behind them, the shows and networks they buy, the ads in an episode, leaderboards and trends, and the prospect lists for a show selling inventory or a brand buying it.\n\nApple and Spotify chart positions: today's chart for a country and category, its history, what moved, and one show's presence across every chart.\n\nPolitical bias analysis: where a show sits and the evidence behind it, and the roll-ups and leaderboards across a publisher's catalogue.\n\nBrand suitability against the IAB Tech Lab framework (formerly GARM): a show's assessment by category, a guest's exposure, and the publisher roll-ups and leaderboards that build inclusion and exclusion lists.\n\nEntity charts: what podcasts are talking about most this week, as ranked editions for TV, film, games, sports leagues and guests, with movement since the last edition.\n\nEntities named in an episode (companies, people, products, places), how to resolve one from a name or an external identifier, and the topic taxonomy episodes and shows are filed under."
categories: "Podcasts"
capabilities: 105
credits_per_call: "5-50"
---
# Particle on Firecrawl Alexandria

Podcast intelligence: speaker-labelled transcripts, episode and show search, the people who appear, the sponsors and companies advertising, chart rankings, and bias and brand-suitability analysis.

- Categories: Podcasts
- Category index: [Podcasts category](https://firecrawl.dev/alexandria/agents/categories/podcasts)
- Provider key: `particle`
- Access: Firecrawl credits
- Cost: 5–50 credits per call

## More

- [Human guide](https://firecrawl.dev/app/alexandria/particle)
- [OpenAPI spec](https://firecrawl.dev/alexandria/agents/providers/particle/openapi.json)

## Capabilities

- [Episode search](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/episodes/search): Matching transcript segments with compact episode records under data. Beside data the body carries the resolved entity or company block when one was passed, and a diagnostics block when nothing matched. Read episode.id and fetch podcasts/episode for the optional episode web URL or audio stream; search does not return those links.
- [Show search](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/search): Matching shows, each with a match_quality from exact down to speculative, and the same filters podcasts/list takes.
- [Show directory](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/list): Shows matching the filters, most popular first when no query is given.
- [Show lookup by platform id](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/lookup): One result per identifier passed, echoing it beside the matched podcast. An unresolved identifier has no podcast field.
- [Podcast episode](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/episode): One episode, returned directly: its show, publication date, duration, speakers, topics, and optional web and audio links.
- [Episode transcript](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/transcript): In the dialogue format: the full transcript as ordered, numbered, speaker-labelled lines under lines, with episode_id, language and duration_seconds beside them. The text and srt formats answer with that format's body instead.
- [Show profile](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/show): One show, returned directly: title, slug, publisher, language, episode count, popularity, topics, format profile, and its bias and suitability tiers when analysed.
- [Episodes of a show](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/show/episodes): The show's episodes, newest first, as full episode records.
- [Entity mentions in a show](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/show/mentions): Episodes of this show where the entity appears, newest first, each with salience, occurrence count and the roles it held.
- [Related shows](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/show/related): Shows most related to this one, best first, each with a calibrated score and a band (strong, moderate, weak). An empty page carries a coverage note saying why.
- [Show platform links](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/show/external-links): Every third-party presence of the show: directories (Apple Podcasts, Spotify), social profiles, video channels and the website, each with its platform-native id and resolved URL.
- [Show format profile](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/show/format): The show's format breakdown, returned directly: guest and panel rates, detected formats, ad and video presence, episode length percentiles, cadence, publish-day histogram and the sample sizes behind each. 404 when not yet computed.
- [Show ratings](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/show/ratings): Individual listener ratings, newest first: stars, optional title and review text, platform and locale. Today's source is Apple Podcasts across the Anglophone storefronts.
- [Show ratings summary](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/show/ratings-summary): One aggregate per platform and locale under entries, with a combined roll-up and, when generated, a narrative sentiment summary of recent reviews beside them.
- [Publisher profile](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/publisher): One publisher, returned directly: id, slug, name and catalogue size. Its shows are podcasts/publisher/shows.
- [Publisher directory](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/publishers): Publishers (networks), largest catalogue first.
- [Shows of a publisher](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/publisher/shows): The publisher's shows, most popular first.
- [Episode segment](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/segment): One segment, returned directly: its type, title, summary and where it sits in the recording. The words themselves are podcasts/segment/transcript.
- [Episode clip](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/clip): One clip, returned directly: a bounded highlight of an episode with its audio range, kind, engagement score and speaker.
- [Top-level topics by show count](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/topics): Top-level topics ordered by how many shows cover them.
- [Episode directory](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/episodes/list): Episodes across every show matching the filters, newest first, as full episode records.
- [Episode feed](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/episodes/feed): Episodes that reached the milestone since the cursor, in ingestion order, with a cursor to poll again.
- [Episode lookup by platform id](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/episodes/lookup): One result per identifier passed, echoing it beside the matched episode. An unresolved identifier has no episode field.
- [Episode counts over time](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/episodes/timeseries): Zero-filled UTC buckets under buckets, with range totals beside them at the top level. Totals: total_episodes, distinct_podcasts and, with a search term, total_mentions.
- [Episode speakers](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/episode/speakers): Identified speakers with their roles and speaking time. Everyone when limit is omitted.
- [Entities in an episode](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/episode/entities): Knowledge-graph entities mentioned in the episode with salience and occurrence counts. All of them when limit is omitted.
- [Episode topics](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/episode/topics): The taxonomy topics the episode is classified under. All of them when limit is omitted.
- [Related episodes](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/episode/related): Episodes from other shows covering the same story or subject, best first, each with a calibrated score and band. Empty when the episode has no embedded content yet.
- [Episode segments](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/episode/segments): The episode's AI-identified segments in order: intros, ad reads, topic discussions, interviews, outros. All of them when limit is omitted.
- [Episode clips](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/episode/clips): The episode's highlight clips, highest engagement score first.
- [Transcript excerpt at a moment](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/transcript/preview): In the dialogue format: one segment's lines, with excerpt true and segment_id, segment_start_seconds and segment_end_seconds beside them saying what was actually returned. The text and srt formats answer with that format's body instead.
- [Entity mentions in a transcript](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/transcript/mentions): Under entities, one row per entity mentioned, each with its mention windows and surrounding context. With entity_id the page is that entity's windows; without it the page is the entities.
- [Dialogue mentions of an entity](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/mentions): Under data, one row per episode with every mention window in it, newest episode first, mention lines flagged is_mention. Beside data the body carries the resolved entity, or person and company blocks and matched_by when matched by name.
- [Mention counts over time](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/mentions/timeseries): Zero-filled UTC buckets under buckets, with range totals beside them at the top level. Totals: total_episodes, total_mentions, distinct_podcasts, and the resolved entity or company block. Ranges are capped at 1000 buckets.
- [Segment directory](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/segments): Segments across episodes matching the filters. No global feed: a filter is required.
- [Segment transcript](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/segment/transcript): In the dialogue format: the segment's lines, renumbered from 1 with timestamps relative to the segment's start. The text and srt formats answer with that format's body instead.
- [Clip directory](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/clips): Highlight clips across episodes, ranked by engagement potential.
- [Clip transcript](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/clip/transcript): In the dialogue format: the clip's lines, renumbered from 1 with timestamps relative to the clip's start. The text and srt formats answer with that format's body instead.
- [Person profile](https://firecrawl.dev/alexandria/agents/providers/particle/people/profile): One person, returned directly: name, slug, bio, company-role history most recent first, known profile links and the linked knowledge-graph entity.
- [Guest profile](https://firecrawl.dev/alexandria/agents/providers/particle/people/guest): One guest, returned directly: the person record plus lifetime stats (appearances, distinct shows, speaking time, first and last appearance, mix by bias and suitability tier) and the shows they appear on most.
- [Person profile links](https://firecrawl.dev/alexandria/agents/providers/particle/people/external-links): Every known third-party profile of the person: LinkedIn, Wikipedia, social accounts, each with its identifier and URL. All of them when limit is omitted.
- [Guest directory](https://firecrawl.dev/alexandria/agents/providers/particle/people/guests): People who have appeared on at least one episode in a non-host role, with appearance counts.
- [Trending guests](https://firecrawl.dev/alexandria/agents/providers/particle/people/guests/trending): Guests whose recent cross-show interview activity is elevated above their own baseline, with in-window appearance counts. Perennial regulars and daily contributors are filtered out by design.
- [Guest appearances](https://firecrawl.dev/alexandria/agents/providers/particle/people/guest/appearances): The episodes the guest appeared on, most recent first, each with the show, speaking time and the show's bias and suitability tier when evaluated.
- [Shows a guest has appeared on](https://firecrawl.dev/alexandria/agents/providers/particle/people/guest/shows): The distinct shows the guest has appeared on, with per-show appearance counts, first and last dates, and the show's bias and suitability when evaluated.
- [Shows a guest could appear on](https://firecrawl.dev/alexandria/agents/providers/particle/people/guest/pitch-list): Shows the person has not appeared on, ranked by how related they are to the shows that booked them, each with a score and band. Empty for someone with no guest bookings on record.
- [Guest roster of a show](https://firecrawl.dev/alexandria/agents/providers/particle/people/show-guests): The identified guests of the show, grouped by person, with per-show appearance counts and first and last dates.
- [Guests a show could book](https://firecrawl.dev/alexandria/agents/providers/particle/people/show-recommended-guests): People who guested on the show's related shows but never on this one, ranked by venue relatedness and how many independent publishers chose them. Circuit regulars are excluded.
- [Company directory](https://firecrawl.dev/alexandria/agents/providers/particle/companies/search): Companies matching the filters, with their identifiers.
- [People at a company](https://firecrawl.dev/alexandria/agents/providers/particle/companies/people): People associated with the company, current roles first and most recently joined first, each a full person record.
- [Company products](https://firecrawl.dev/alexandria/agents/providers/particle/companies/products): The company's product hierarchy as a nested tree: segments containing product lines containing products.
- [Company profile links](https://firecrawl.dev/alexandria/agents/providers/particle/companies/external-links): Every known profile and identifier of the company: LinkedIn, social accounts, domain, Wikidata QID, SEC CIK, tickers. All of them when limit is omitted.
- [Company competitors](https://firecrawl.dev/alexandria/agents/providers/particle/companies/competitors): Competitors ordered by prominence (news coverage, market cap, podcast appearances, notability), each with the basis of the relationship.
- [Sponsor profile](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/sponsor): One sponsor, returned directly: name, the company behind it, and its ad count, show reach and episode reach in the window.
- [Company profile](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/company): One company as Particle holds it, returned directly: name, description, identifiers (slug, domain, ticker, CIK, QID) and profile links.
- [Sponsor directory](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/sponsors): Sponsors with their ad count, show reach and episode reach.
- [Trending sponsors](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/sponsors/trending): Sponsors whose ad volume is accelerating, ranked by the change between the trailing window and the one before it.
- [Shows a sponsor buys](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/sponsor/shows): Shows where the sponsor advertises, ordered by episodes carrying it. A company reference aggregates every sponsor linked to the company.
- [Publishers a sponsor buys across](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/sponsor/publishers): Publishers the sponsor advertises across, ordered by how many of each catalogue's shows it appears on. High coverage across a network is the signature of a network buy.
- [Ad reads of a sponsor](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/sponsor/segments): The individual ad segments attributed to the sponsor, newest episode first. Network promos are excluded.
- [Sponsor leaderboard](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/leaderboard): Sponsors ranked by the metric over the window.
- [Sponsor leaderboard, top ten](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/leaderboard/preview): The top ten sponsors of the trailing seven days, each with its movement against the seven-day window ending thirty days ago. The same board for every caller.
- [Publisher advertising leaderboard](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/publishers/leaderboard): Publishers ranked by advertising activity across their catalogue, all time.
- [Sponsors that appear together](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/co-occurrence): Pairs of sponsors that frequently share episodes.
- [Ad placements over time](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/timeseries): Zero-filled UTC buckets under buckets, with range totals beside them at the top level. Totals: total_ads, host_read_count, pre_recorded_count, distinct_podcasts, distinct_episodes. Network promos are excluded.
- [Show advertising profile](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/show): Advertising on one show, returned directly: totals, read-type split and top sponsors.
- [Sponsors of a show](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/show/sponsors): Per-sponsor activity on the show, most ads first. Network promos are excluded.
- [Sponsors a show could pitch](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/show/prospects): Advertisers that run on the show's related shows but not on it, ranked by venue relatedness, spend there and recency. Empty when the show's related set is not computed yet.
- [Publisher advertising profile](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/publisher): Advertising across a publisher's whole catalogue, returned directly: totals, coverage, read-type split, top sponsors and network buyers.
- [Shows of a publisher by ad volume](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/publisher/shows): The publisher's shows ordered by ad count, with monetisation data rather than audience signals.
- [Sponsors of a publisher](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/publisher/sponsors): Sponsors active across the publisher's catalogue, each with its coverage of that catalogue.
- [Ads in an episode](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/episode): The ad spots detected in the episode: sponsor, linked company, offer, read type and placement. Network promos are excluded.
- [Company advertising profile](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/company/overview): A company's podcast advertising, returned directly: totals, reach, read-type split and recent placements, across every sponsor linked to it.
- [Company ad placements](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/company/placements): Physical ad placements attributed to the company, newest first, each with episode and show context and every company-scoped sponsor attribution.
- [Shows carrying a company's ads](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/company/shows): Shows ranked by the company's ad count on them, each with its sponsor breakdown and recent preview segments. Beside data: company-wide sponsors and, when asked, facets.
- [Shows a company could advertise on](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/company/prospects): Shows the company does not advertise on, ranked by relatedness to the shows it does, anchored on its main venues. Empty for a company with no podcast advertising.
- [Chart entries](https://firecrawl.dev/alexandria/agents/providers/particle/rankings/charts): Entries of the live snapshot for one chart slot, rank ascending; charts run to 200. With podcast_id, that show's current appearances instead.
- [Ranking categories](https://firecrawl.dev/alexandria/agents/providers/particle/rankings/categories): Every category with current chart data, with the parent for Apple sub-categories. All of them when limit is omitted.
- [Ranking countries](https://firecrawl.dev/alexandria/agents/providers/particle/rankings/countries): Every country with current chart data. All of them when limit is omitted.
- [Ranking sources](https://firecrawl.dev/alexandria/agents/providers/particle/rankings/sources): Each source and chart type pair available, with row counts and freshness of the live snapshot.
- [Chart slot history](https://firecrawl.dev/alexandria/agents/providers/particle/rankings/history): Historical snapshots of one chart slot, most recent first.
- [Chart movers](https://firecrawl.dev/alexandria/agents/providers/particle/rankings/movers): Entries whose rank changed between the live snapshot and the comparison snapshot. Stable rows are excluded.
- [Current rankings of a show](https://firecrawl.dev/alexandria/agents/providers/particle/rankings/show): Every live chart appearance of the show across sources, countries and categories. All of them when limit is omitted.
- [Ranking history of a show](https://firecrawl.dev/alexandria/agents/providers/particle/rankings/show/history): The show's historical rank entries across chart slots, optionally narrowed to one source, country, category or date range.
- [Chart presence summary](https://firecrawl.dev/alexandria/agents/providers/particle/rankings/show/summary): The show's chart presence in one record: counts of slots, sources, countries and categories it appears on, its single best rank, and a per-source breakdown.
- [Show bias analysis](https://firecrawl.dev/alexandria/agents/providers/particle/bias/show): The show's most recent political bias analysis, returned directly: the result bucket, confidence, the political framework, the reasoning, the transcript and web evidence, and the sample episodes. 404 when not yet analysed.
- [Publisher bias profile](https://firecrawl.dev/alexandria/agents/providers/particle/bias/publisher): Bias rolled up across a publisher's analysed shows, returned directly: coverage, political share, average lean on a -3 to +3 scale, lean diversity, and the bucket and regional distributions.
- [Analysed shows of a publisher](https://firecrawl.dev/alexandria/agents/providers/particle/bias/publisher/shows): The publisher's analysed shows with their latest bias analysis attached.
- [Publisher bias leaderboard](https://firecrawl.dev/alexandria/agents/providers/particle/bias/publishers/leaderboard): Publishers ranked by the chosen bias metric, each with its coverage, political share and lean.
- [Publishers with shows in a bias bucket](https://firecrawl.dev/alexandria/agents/providers/particle/bias/publishers-by-bucket): Publishers whose analysed catalogue has shows in the bucket, ranked by count or share.
- [Show suitability assessment](https://firecrawl.dev/alexandria/agents/providers/particle/suitability/show): The show's latest brand-suitability assessment, returned directly: overall tier, per-category prevalence and treatment across the 12 categories, evidence excerpts and methodology. 404 when not yet analysed.
- [Guest suitability exposure](https://firecrawl.dev/alexandria/agents/providers/particle/suitability/guest): The distribution of suitability tiers across the shows a guest has appeared on, lifetime and in the last 90 days, plus the categories most often flagged there. A measure of exposure, not a verdict on the person.
- [Publisher suitability profile](https://firecrawl.dev/alexandria/agents/providers/particle/suitability/publisher): Suitability rolled up across a publisher's analysed shows, returned directly: tier composition, confidence distribution, exposure per category and the top concerns, with a coverage block saying how representative it is.
- [Assessed shows of a publisher](https://firecrawl.dev/alexandria/agents/providers/particle/suitability/publisher/shows): The publisher's assessed shows with their latest tier, confidence and flagged categories. Per-category reasoning is left to suitability/show.
- [Publisher suitability leaderboard](https://firecrawl.dev/alexandria/agents/providers/particle/suitability/publishers/leaderboard): Publishers ranked by suitability composition, each with its full tier breakdown and the value it was ranked by.
- [Publishers by exposure to a category](https://firecrawl.dev/alexandria/agents/providers/particle/suitability/category-publishers): Publishers ranked by catalogue exposure to one category, each with prevalence and treatment breakdowns and up to three example shows.
- [Entity charts](https://firecrawl.dev/alexandria/agents/providers/particle/charts/list): Every entity chart with the headline state of its current edition: date, whether narratives are written, what sits at rank 1, and the windows it publishes.
- [Entity chart edition](https://firecrawl.dev/alexandria/agents/providers/particle/charts/chart): The current edition of one chart under entries, each with its movement since the previous edition. Beside entries: category, edition date, window, source, status, methodology version and caveats. Mention charts rank by distinct podcasts mentioning the subject; the all chart blends reach with acceleration.
- [Entity search](https://firecrawl.dev/alexandria/agents/providers/particle/entities/search): Best matches by relevance, each with a match_quality telling an exact identification from a fuzzy guess and counts of podcast episodes and news articles naming it. The matched record sits under person, company or knowledge_graph_entity according to type.
- [Entity record](https://firecrawl.dev/alexandria/agents/providers/particle/entities/mentions): One knowledge-graph entity, returned directly: name, slug, type, description, and the linked company or person record.
- [Entity directory](https://firecrawl.dev/alexandria/agents/providers/particle/entities/list): Entities ranked by the number of distinct episodes featuring them, filtered by show or type, or exactly the ids asked for.
- [Entity lookup by external identifier](https://firecrawl.dev/alexandria/agents/providers/particle/entities/lookup): One result per identifier passed, echoing it with the people and companies that carry it. An identifier is not unique, so matches is a list and match_count its size; unresolved identifiers have an empty matches.
- [Types](https://firecrawl.dev/alexandria/agents/providers/particle/entities/types): Every entity category, as the slugs entities/list and the entity_type filter on episode search accept. All of them when limit is omitted.
- [Topic profile](https://firecrawl.dev/alexandria/agents/providers/particle/entities/topic): One topic, returned directly, with its breadcrumb ancestors and its top direct children by prominence. Children are capped; entities/topics with parent_id pages beyond the cap.
- [Topics](https://firecrawl.dev/alexandria/agents/providers/particle/entities/topics): The topic tree one level at a time, as the ids the topic_id filters accept.

## 1. Choose this provider when

Shows and the episodes inside them. Search finds an episode by what was said; a show's episodes, its publisher, its format, ratings and platform links, and the dialogue itself as transcripts, segments, clips and mentions.

The people on a podcast: the person record, the same person as a guest with their appearances and the shows that book them, a show's guest roster, who is trending, and who a show could book next.

Companies as the knowledge graph holds them: the directory by name, ticker, domain or CIK, the people and products behind one, its profile links and its competitors. The company record itself is advertising/company.

Who is advertising and where. Sponsors and the companies behind them, the shows and networks they buy, the ads in an episode, leaderboards and trends, and the prospect lists for a show selling inventory or a brand buying it.

Apple and Spotify chart positions: today's chart for a country and category, its history, what moved, and one show's presence across every chart.

Political bias analysis: where a show sits and the evidence behind it, and the roll-ups and leaderboards across a publisher's catalogue.

Brand suitability against the IAB Tech Lab framework (formerly GARM): a show's assessment by category, a guest's exposure, and the publisher roll-ups and leaderboards that build inclusion and exclusion lists.

Entity charts: what podcasts are talking about most this week, as ranked editions for TV, film, games, sports leagues and guests, with movement since the last edition.

Entities named in an episode (companies, people, products, places), how to resolve one from a name or an external identifier, and the topic taxonomy episodes and shows are filed under.

## 2. Minimal request

Call `POST https://api.firecrawl.dev/v2/scrape` with `{ alexandria: { provider, capability, options } }`. For a batch, send `{ alexandria: [...] }` with up to 10 calls.

```json
{
  "provider": "particle",
  "capability": "podcasts/episodes/search",
  "options": {
    "semantic_search": "<semantic_search>",
    "keyword_match": "required",
    "context": 1,
    "limit": 25
  }
}
```

## 3. Add provider options

Use only the options needed for the task:

- `semantic_search` (string): What was talked about, in your own words. Paraphrase-tolerant, so it finds dialogue that means this without containing these exact words. Describe a topic, not a name: for a person or company use entity_id or podcasts/mentions. Example: `<semantic_search>`
- `keyword_search` (string): Exact tokens or phrases to match in the transcript, ranked BM25. Use for tickers, drug names, product codes. Wrap a phrase in double quotes to require it contiguously. Example: `<keyword_search>`
- `keyword_match` (string): How unquoted keyword terms apply: required filters to segments containing every term (and constrains a hybrid query to their intersection); ranked lets them only boost. Example: `required`
- `entity_id` (string): Restrict to episodes featuring this entity, by slug or id. Ranking still comes from the search terms. Example: `<entity_id>`
- `entity_type` (string): Restrict to episodes that mention any entity of this category slug (company, school, book). Not combinable with role. Example: `<entity_type>`
- `company_id` (string): Restrict to episodes featuring this company, by slug, domain or id. Example: `<company_id>`
- `episode_id` (string): Restrict to one episode, by slug or id. Example: `<episode_id>`
- `podcast_id` (string): Restrict to one show, by slug, id or Apple collection id. Example: `<podcast_id>`
- `type` (string): Only segments of this type. Example: `INTRO`
- `role` (string): How the entity must relate to the episode: a speaking role, speaker for any speaking role, or mention for being talked about. Example: `guest`
- `language` (string): ISO 639-1 language code, for example en or fr. Matches the primary subtag, so fr covers fr-CA. Example: `<language>`
- `since` (string): Only segments from episodes published after this date. Example: `<since>`
- `until` (string): Only segments from episodes published on or before this date. A bare date covers the whole day. Example: `<until>`
- `sort` (string): relevance (default) or recency. Example: `relevance`
- `context` (number): Lines of surrounding dialogue around each matched line. Widen this instead of fetching the transcript. Example: `1`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

## 4. Request through your preferred interface

### JavaScript

```javascript
const result = await firecrawl.scrape({
  alexandria: {
    provider: "particle",
    capability: "podcasts/episodes/search",
    options: {
      semantic_search: "<semantic_search>",
      keyword_match: "required",
      context: 1,
      limit: 25,
    },
  },
});
```

### Python

```python
result = firecrawl.scrape_alexandria({
  "provider": "particle",
  "capability": "podcasts/episodes/search",
  "options": {
    "semantic_search": "<semantic_search>",
    "keyword_match": "required",
    "context": 1,
    "limit": 25
  }
})
```

### cURL

```sh
curl https://api.firecrawl.dev/v2/scrape \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "alexandria": {
    "provider": "particle",
    "capability": "podcasts/episodes/search",
    "options": {
      "semantic_search": "<semantic_search>",
      "keyword_match": "required",
      "context": 1,
      "limit": 25
    }
  }
}'
```

### CLI

```sh
firecrawl scrape 'particle/podcasts/episodes/search' \
  --options '{"semantic_search":"<semantic_search>","keyword_match":"required","context":1,"limit":25}'
```


### MCP

Call the FCX MCP retrieve tool with this object:

```json
{
  "provider": "particle",
  "capability": "podcasts/episodes/search",
  "options": {
    "semantic_search": "<semantic_search>",
    "keyword_match": "required",
    "context": 1,
    "limit": 25
  }
}
```

Ask for only the returned fields needed by the task.

## 5. Full request shape

```json
{
  "provider": "particle",
  "capability": "podcasts/episodes/search",
  "options": {
    "semantic_search": "<semantic_search>",
    "keyword_match": "required",
    "context": 1,
    "limit": 25
  }
}
```

## 6. Response data

The response includes `success`, `provider`, `capability`, `creditsCost` and `data`. This example shows the provider payload in `data`:

```json
{
  "data": [
    {
      "episode": {},
      "segment": {},
      "windows": [],
      "match": {},
      "clips": []
    }
  ]
}
```

## API reference-derived contract

The following capability contract is generated from the same normalized Alexandria API reference exposed in the API spec.

### Episode search

- Capability: `podcasts/episodes/search`
- Description: Matching transcript segments with compact episode records under data. Beside data the body carries the resolved entity or company block when one was passed, and a diagnostics block when nothing matched. Read episode.id and fetch podcasts/episode for the optional episode web URL or audio stream; search does not return those links.
- Instructions: Use to find episodes that discussed something. This is the entry point: it returns ids the other podcast capabilities take. For every line about one person or company use podcasts/mentions instead.
- Cost: 15 credits per call
- Capability file: [Episode search](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/episodes/search)

Accepted options:
- `semantic_search` (string): What was talked about, in your own words. Paraphrase-tolerant, so it finds dialogue that means this without containing these exact words. Describe a topic, not a name: for a person or company use entity_id or podcasts/mentions. Example: `<semantic_search>`
- `keyword_search` (string): Exact tokens or phrases to match in the transcript, ranked BM25. Use for tickers, drug names, product codes. Wrap a phrase in double quotes to require it contiguously. Example: `<keyword_search>`
- `keyword_match` (string): How unquoted keyword terms apply: required filters to segments containing every term (and constrains a hybrid query to their intersection); ranked lets them only boost. Example: `required`
- `entity_id` (string): Restrict to episodes featuring this entity, by slug or id. Ranking still comes from the search terms. Example: `<entity_id>`
- `entity_type` (string): Restrict to episodes that mention any entity of this category slug (company, school, book). Not combinable with role. Example: `<entity_type>`
- `company_id` (string): Restrict to episodes featuring this company, by slug, domain or id. Example: `<company_id>`
- `episode_id` (string): Restrict to one episode, by slug or id. Example: `<episode_id>`
- `podcast_id` (string): Restrict to one show, by slug, id or Apple collection id. Example: `<podcast_id>`
- `type` (string): Only segments of this type. Example: `INTRO`
- `role` (string): How the entity must relate to the episode: a speaking role, speaker for any speaking role, or mention for being talked about. Example: `guest`
- `language` (string): ISO 639-1 language code, for example en or fr. Matches the primary subtag, so fr covers fr-CA. Example: `<language>`
- `since` (string): Only segments from episodes published after this date. Example: `<since>`
- `until` (string): Only segments from episodes published on or before this date. A bare date covers the whole day. Example: `<until>`
- `sort` (string): relevance (default) or recency. Example: `relevance`
- `context` (number): Lines of surrounding dialogue around each matched line. Widen this instead of fetching the transcript. Example: `1`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "episode": {},
      "segment": {},
      "windows": [],
      "match": {},
      "clips": []
    }
  ]
}
```

### Show search

- Capability: `podcasts/search`
- Description: Matching shows, each with a match_quality from exact down to speculative, and the same filters podcasts/list takes.
- Instructions: Use to turn a show name into its slug and record. To find what was said inside one, search episodes instead: this matches show metadata, not transcripts. For an Apple, Spotify or YouTube id use podcasts/lookup.
- Cost: 5 credits per call
- Capability file: [Show search](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/search)

Accepted options:
- `q` (string, required): Show name, forgiving of typos, missing words and qualifiers (offline jon favreau, equity techcrunch). Example: `<q>`
- `topic_id` (string): Restrict to a topic, by topic id or ancestry slug such as technology/artificial-intelligence. Matches shows where the topic is at least a fifth of their episodes. Example: `<topic_id>`
- `language` (string): ISO 639-1 language code, for example en or fr. Matches the primary subtag, so fr covers fr-CA. Example: `<language>`
- `sort` (string): relevance ranks by match quality (the default with q); popularity orders by global popularity percentile. Example: `relevance`
- `suitability_tier` (string): Only shows whose latest brand-suitability assessment is this IAB Tech Lab tier. Shows never assessed are excluded when set. Example: `SAFE`
- `popularity_threshold` (number): Only shows at or above this global popularity percentile, in (0, 1]. Example: `1`
- `guest_frequency` (string): How often episodes feature a guest, comma-separated to match any: for example regular,always for interview shows, never for shows without guests. Example: `<guest_frequency>`
- `format_signal` (string): Detected production formats, comma-separated to match any: interview, panel, call_in, solo_narrated. Example: `<format_signal>`
- `has_ads` (string): true for shows with detected advertising, false for ad-free shows with enough analysed episodes to say so. Example: `true`
- `has_video` (string): Whether episodes have discovered video versions. Example: `true`
- `min_avg_episode_minutes` (number): Only shows whose average episode runs at least this many minutes. Example: `10`
- `max_avg_episode_minutes` (number): Only shows whose average episode runs at most this many minutes. Example: `10`
- `min_episodes_per_week` (number): Only shows publishing at least this many episodes a week over the trailing 90 days. Example: `10`
- `max_episodes_per_week` (number): Only shows publishing at most this many episodes a week. Example: `10`
- `publishing_status` (string): active has released an episode in the last 90 days; dormant has not. Example: `active`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "slug": "<slug>",
      "title": "<title>",
      "description": "<description>",
      "language": "<language>",
      "explicit": false,
      "episode_count": 0,
      "popularity": 0,
      "image_url": "<image_url>",
      "url": "<url>",
      "publisher": {},
      "topics": [],
      "speakers": [],
      "format": {},
      "bias": "<bias>",
      "political_context": "<political_context>",
      "suitability_tier": "<suitability_tier>",
      "match_quality": "<match_quality>",
      "related": [],
      "recommended_guests": [],
      "recommended_sponsors": []
    }
  ]
}
```

### Show directory

- Capability: `podcasts/list`
- Description: Shows matching the filters, most popular first when no query is given.
- Instructions: Use to browse shows by attribute rather than by name: a topic, a language, a brand-suitability tier, a length band, a cadence, an ad-free or interview format. For a name, podcasts/search is the canonical search.
- Cost: 5 credits per call
- Capability file: [Show directory](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/list)

Accepted options:
- `slug` (string): Exact slug of one show. Example: `<slug>`
- `topic_id` (string): Restrict to a topic, by topic id or ancestry slug such as technology/artificial-intelligence. Matches shows where the topic is at least a fifth of their episodes. Example: `<topic_id>`
- `language` (string): ISO 639-1 language code, for example en or fr. Matches the primary subtag, so fr covers fr-CA. Example: `<language>`
- `sort` (string): relevance ranks by match quality (the default with q); popularity orders by global popularity percentile. Example: `relevance`
- `suitability_tier` (string): Only shows whose latest brand-suitability assessment is this IAB Tech Lab tier. Shows never assessed are excluded when set. Example: `SAFE`
- `popularity_threshold` (number): Only shows at or above this global popularity percentile, in (0, 1]. Example: `1`
- `guest_frequency` (string): How often episodes feature a guest, comma-separated to match any: for example regular,always for interview shows, never for shows without guests. Example: `<guest_frequency>`
- `format_signal` (string): Detected production formats, comma-separated to match any: interview, panel, call_in, solo_narrated. Example: `<format_signal>`
- `has_ads` (string): true for shows with detected advertising, false for ad-free shows with enough analysed episodes to say so. Example: `true`
- `has_video` (string): Whether episodes have discovered video versions. Example: `true`
- `min_avg_episode_minutes` (number): Only shows whose average episode runs at least this many minutes. Example: `10`
- `max_avg_episode_minutes` (number): Only shows whose average episode runs at most this many minutes. Example: `10`
- `min_episodes_per_week` (number): Only shows publishing at least this many episodes a week over the trailing 90 days. Example: `10`
- `max_episodes_per_week` (number): Only shows publishing at most this many episodes a week. Example: `10`
- `publishing_status` (string): active has released an episode in the last 90 days; dormant has not. Example: `active`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "slug": "<slug>",
      "title": "<title>",
      "description": "<description>",
      "language": "<language>",
      "explicit": false,
      "episode_count": 0,
      "popularity": 0,
      "image_url": "<image_url>",
      "url": "<url>",
      "publisher": {},
      "topics": [],
      "speakers": [],
      "format": {},
      "bias": "<bias>",
      "political_context": "<political_context>",
      "suitability_tier": "<suitability_tier>",
      "match_quality": "<match_quality>",
      "related": [],
      "recommended_guests": [],
      "recommended_sponsors": []
    }
  ]
}
```

### Show lookup by platform id

- Capability: `podcasts/lookup`
- Description: One result per identifier passed, echoing it beside the matched podcast. An unresolved identifier has no podcast field.
- Instructions: Use when you already hold an Apple collection id, Spotify show id, YouTube channel id or RSS feed URL and need the Particle podcast deterministically. For a name, use podcasts/search.
- Cost: 5 credits per call
- Capability file: [Show lookup by platform id](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/lookup)

Accepted options:
- `platform` (string, required): The identifier's platform: apple (alias itunes), spotify, youtube, any slug reported by podcasts/show/external-links, or rss to match a feed URL. Example: `<platform>`
- `identifier` (string, required): One or more platform-native identifiers, comma-separated, up to 100 per call. Example: `<identifier>`

Response schema example:
```json
{
  "results": [
    {
      "identifier": "<identifier>",
      "podcast": {}
    }
  ]
}
```

### Podcast episode

- Capability: `podcasts/episode`
- Description: One episode, returned directly: its show, publication date, duration, speakers, topics, and optional web and audio links.
- Instructions: Use episode.id from a search match to get the full record and, when available, its web URL or direct audio stream. Neither link is guaranteed. For what was said, fetch podcasts/transcript.
- Cost: 5 credits per call
- Capability file: [Podcast episode](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/episode)

Accepted options:
- `id` (string, required): Episode slug or id: episode.id on a search match, or id on an episode list row. A podcast slug is not an episode id. Example: `<id>`

Response schema example:
```json
{
  "id": "<id>",
  "slug": "<slug>",
  "title": "<title>",
  "description": "<description>",
  "published_at": "<published_at>",
  "duration_seconds": 0,
  "explicit": false,
  "has_transcript": false,
  "language": "<language>",
  "episode_number": 0,
  "image_url": "<image_url>",
  "url": "<url>",
  "audio_url": "<audio_url>",
  "podcast": {},
  "speakers": [],
  "topics": [],
  "segments": [],
  "clips": [],
  "transcript": {},
  "videos": [],
  "clip_count": 0,
  "entity_count": 0,
  "segment_count": 0
}
```

### Episode transcript

- Capability: `podcasts/transcript`
- Description: In the dialogue format: the full transcript as ordered, numbered, speaker-labelled lines under lines, with episode_id, language and duration_seconds beside them. The text and srt formats answer with that format's body instead.
- Instructions: Use to read a whole episode rather than the excerpt a search returned. For one passage, podcasts/segment/transcript is smaller and cheaper; for a moment, podcasts/transcript/preview.
- Cost: 15 credits per call
- Capability file: [Episode transcript](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/transcript)

Accepted options:
- `id` (string, required): Episode slug or id: episode.id on a search match, or id on an episode list row. A podcast slug is not an episode id. Example: `<id>`
- `format` (string): Output format: dialogue (speaker-attributed JSON lines, the shape described here), text (Speaker: text lines), or srt (SubRip). The text and srt bodies are not the lines shape. Example: `dialogue`
- `speaker` (string): Only lines from this speaker: a full or partial name, case-insensitive, or an entity id or slug. Example: `<speaker>`
- `start` (number): Clip to lines starting at this offset in seconds. Example: `10`
- `end` (number): Clip to lines ending by this offset in seconds. Example: `10`

Response schema example:
```json
{
  "lines": [
    {
      "number": 0,
      "speaker": "<speaker>",
      "role": "<role>",
      "text": "<text>",
      "start_seconds": 0,
      "end_seconds": 0
    }
  ]
}
```

### Show profile

- Capability: `podcasts/show`
- Description: One show, returned directly: title, slug, publisher, language, episode count, popularity, topics, format profile, and its bias and suitability tiers when analysed.
- Instructions: Use when a search or an episode record gave you a podcast id and the full show record is needed, including the publisher to go up to and the slug every other show capability takes.
- Cost: 5 credits per call
- Capability file: [Show profile](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/show)

Accepted options:
- `id` (string, required): Podcast slug (for example all-in), Particle id, or numeric Apple collection id. Take slugs from responses; a constructed slug returns 404. Example: `<id>`
- `topic_limit` (number): How many aggregated topics to return; 0 for none. Example: `10`
- `include` (string): Optional sections, comma-separated: related (five most related shows), recommended_guests (five bookable guests), recommended_sponsors (five prospective advertisers; premium-grade). Example: `<include>`

Response schema example:
```json
{
  "id": "<id>",
  "slug": "<slug>",
  "title": "<title>",
  "description": "<description>",
  "language": "<language>",
  "explicit": false,
  "episode_count": 0,
  "popularity": 0,
  "image_url": "<image_url>",
  "url": "<url>",
  "publisher": {},
  "topics": [],
  "speakers": [],
  "format": {},
  "bias": "<bias>",
  "political_context": "<political_context>",
  "suitability_tier": "<suitability_tier>",
  "match_quality": "<match_quality>",
  "related": [],
  "recommended_guests": [],
  "recommended_sponsors": []
}
```

### Episodes of a show

- Capability: `podcasts/show/episodes`
- Description: The show's episodes, newest first, as full episode records.
- Instructions: Use to get from a show to its episodes and their ids: the latest episode, an episode by title, or the run of episodes in a date range. A podcast slug is never an episode id; this is how you get one.
- Cost: 15 credits per call
- Capability file: [Episodes of a show](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/show/episodes)

Accepted options:
- `id` (string, required): Podcast slug (for example all-in), Particle id, or numeric Apple collection id. Take slugs from responses; a constructed slug returns 404. Example: `<id>`
- `q` (string): Only episodes whose title contains this text, case-insensitively. Titles only; to search what was said use podcasts/episodes/search with podcast_id. Example: `<q>`
- `published_after` (string): Only episodes published after this ISO 8601 date or date-time. Example: `<published_after>`
- `published_before` (string): Only episodes published before this ISO 8601 date or date-time. Example: `<published_before>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "slug": "<slug>",
      "title": "<title>",
      "description": "<description>",
      "published_at": "<published_at>",
      "duration_seconds": 0,
      "explicit": false,
      "has_transcript": false,
      "language": "<language>",
      "episode_number": 0,
      "image_url": "<image_url>",
      "url": "<url>",
      "audio_url": "<audio_url>",
      "podcast": {},
      "speakers": [],
      "topics": [],
      "segments": [],
      "clips": [],
      "transcript": {},
      "videos": [],
      "clip_count": 0,
      "entity_count": 0,
      "segment_count": 0
    }
  ]
}
```

### Entity mentions in a show

- Capability: `podcasts/show/mentions`
- Description: Episodes of this show where the entity appears, newest first, each with salience, occurrence count and the roles it held.
- Instructions: Use for how much one show talks about a person or company: an episode-level roll-up inside one podcast. For the dialogue lines themselves, across shows, use podcasts/mentions.
- Cost: 15 credits per call
- Capability file: [Entity mentions in a show](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/show/mentions)

Accepted options:
- `id` (string, required): Podcast slug (for example all-in), Particle id, or numeric Apple collection id. Take slugs from responses; a constructed slug returns 404. Example: `<id>`
- `entity_id` (string): Entity slug (sam-altman, openai) or id. Example: `<entity_id>`
- `company_id` (string): Company slug, domain or id; resolves to its linked entity. Example: `<company_id>`
- `role` (string): Constrain how the entity participates. Example: `guest`
- `published_after` (string): Only episodes published after this ISO 8601 date or date-time. Example: `<published_after>`
- `published_before` (string): Only episodes published before this ISO 8601 date or date-time. Example: `<published_before>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "episode": {},
      "salience": 0,
      "occurrences": 0,
      "speaker_roles": []
    }
  ]
}
```

### Related shows

- Capability: `podcasts/show/related`
- Description: Shows most related to this one, best first, each with a calibrated score and a band (strong, moderate, weak). An empty page carries a coverage note saying why.
- Instructions: Use for shows like this one: competitive sets, a listener's next show, or the peer set a sponsor or guest pitch cites. Branch on band rather than on the raw score.
- Cost: 15 credits per call
- Capability file: [Related shows](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/show/related)

Accepted options:
- `id` (string, required): Podcast slug (for example all-in), Particle id, or numeric Apple collection id. Take slugs from responses; a constructed slug returns 404. Example: `<id>`
- `include` (string): Pass basis to attach, per result, the signals behind the pairing: content similarity, shared topics, shared guests by name, same publisher, shared sponsors. Example: `<include>`
- `min_score` (number): Only results at or above this fused score; the band field is the recommended way to filter. Example: `1`
- `language` (string): ISO 639-1 language code, for example en or fr. Matches the primary subtag, so fr covers fr-CA. Example: `<language>`
- `publishing_status` (string): Only active (episode in the last 90 days) or dormant shows. Example: `active`
- `suitability_tier` (string): Only shows whose latest brand-suitability assessment is this IAB Tech Lab tier. Shows never assessed are excluded when set. Example: `SAFE`
- `min_popularity` (number): Only shows at or above this popularity percentile. Example: `1`
- `exclude_same_publisher` (boolean): Drop shows from the source show's own publisher. Example: `false`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "podcast": {},
      "score": 0,
      "band": "<band>",
      "basis": {}
    }
  ]
}
```

### Show platform links

- Capability: `podcasts/show/external-links`
- Description: Every third-party presence of the show: directories (Apple Podcasts, Spotify), social profiles, video channels and the website, each with its platform-native id and resolved URL.
- Instructions: Use to get a show's Apple, Spotify or YouTube ids and links, its social handles, or its website. The reverse direction, platform id to show, is podcasts/lookup.
- Cost: 15 credits per call
- Capability file: [Show platform links](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/show/external-links)

Accepted options:
- `id` (string, required): Podcast slug (for example all-in), Particle id, or numeric Apple collection id. Take slugs from responses; a constructed slug returns 404. Example: `<id>`
- `limit` (number): Maximum records to return. Omit for all of them. Example: `10`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "platform": {},
      "identifier": "<identifier>",
      "url": "<url>",
      "attributes": []
    }
  ]
}
```

### Show format profile

- Capability: `podcasts/show/format`
- Description: The show's format breakdown, returned directly: guest and panel rates, detected formats, ad and video presence, episode length percentiles, cadence, publish-day histogram and the sample sizes behind each. 404 when not yet computed.
- Instructions: Use for the exact rates and distributions behind a show's format: how often it has guests, how long episodes run, how often it publishes and on which days. The compact form rides on every show record as format.
- Cost: 15 credits per call
- Capability file: [Show format profile](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/show/format)

Accepted options:
- `id` (string, required): Podcast slug (for example all-in), Particle id, or numeric Apple collection id. Take slugs from responses; a constructed slug returns 404. Example: `<id>`

Response schema example:
```json
{
  "guest_frequency": "<guest_frequency>",
  "guest_episode_rate": 0,
  "panel_episode_rate": 0,
  "call_in_episode_rate": 0,
  "signals": [],
  "has_ads": false,
  "ad_episode_rate": 0,
  "has_video": false,
  "avg_episode_minutes": 0,
  "episode_minutes_p25": 0,
  "episode_minutes_median": 0,
  "episode_minutes_p75": 0,
  "episodes_per_week": 0,
  "publish_days": {},
  "publishing_status": "<publishing_status>",
  "episode_count": 0,
  "analyzed_episodes": 0,
  "first_episode_published_at": "<first_episode_published_at>",
  "latest_episode_published_at": "<latest_episode_published_at>",
  "computed_at": "<computed_at>"
}
```

### Show ratings

- Capability: `podcasts/show/ratings`
- Description: Individual listener ratings, newest first: stars, optional title and review text, platform and locale. Today's source is Apple Podcasts across the Anglophone storefronts.
- Instructions: Use to read what listeners wrote about a show. For the averages and histogram use podcasts/show/ratings-summary.
- Cost: 5 credits per call
- Capability file: [Show ratings](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/show/ratings)

Accepted options:
- `id` (string, required): Podcast slug (for example all-in), Particle id, or numeric Apple collection id. Take slugs from responses; a constructed slug returns 404. Example: `<id>`
- `platform_slug` (string): Only ratings from one platform, for example apple. Example: `<platform_slug>`
- `locale` (string): Only one platform locale, for example the Apple storefront us. Example: `<locale>`
- `min_stars` (number): Lower bound on the star rating. Example: `5`
- `since` (string): Lower bound on posted_at, ISO 8601. Example: `<since>`
- `until` (string): Upper bound on posted_at, ISO 8601. Example: `<until>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "platform_rating_id": "<platform_rating_id>",
      "platform_slug": "<platform_slug>",
      "locale": "<locale>",
      "stars": 0,
      "title": "<title>",
      "body": "<body>",
      "author_display_name": "<author_display_name>",
      "author_uri": "<author_uri>",
      "link_href": "<link_href>",
      "posted_at": "<posted_at>"
    }
  ]
}
```

### Show ratings summary

- Capability: `podcasts/show/ratings-summary`
- Description: One aggregate per platform and locale under entries, with a combined roll-up and, when generated, a narrative sentiment summary of recent reviews beside them.
- Instructions: Use for a show's average rating and count per storefront, plus the combined figure and what recent reviews say in aggregate.
- Cost: 15 credits per call
- Capability file: [Show ratings summary](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/show/ratings-summary)

Accepted options:
- `id` (string, required): Podcast slug (for example all-in), Particle id, or numeric Apple collection id. Take slugs from responses; a constructed slug returns 404. Example: `<id>`

Response schema example:
```json
{
  "entries": [
    {
      "platform_slug": "<platform_slug>",
      "locale": "<locale>",
      "rating_average": 0,
      "rating_count": 0,
      "histogram": {},
      "computed_at": "<computed_at>"
    }
  ]
}
```

### Publisher profile

- Capability: `podcasts/publisher`
- Description: One publisher, returned directly: id, slug, name and catalogue size. Its shows are podcasts/publisher/shows.
- Instructions: Use to go from a show's publisher reference to the network record. For the network's shows call podcasts/publisher/shows; for its advertising, bias or suitability roll-ups use the capabilities under those concepts.
- Cost: 15 credits per call
- Capability file: [Publisher profile](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/publisher)

Accepted options:
- `id` (string, required): Publisher slug (for example iheartpodcasts, bbc-radio-4) or id, as carried on a podcast record's publisher. Example: `<id>`

Response schema example:
```json
{
  "id": "<id>",
  "slug": "<slug>",
  "name": "<name>",
  "podcast_count": 0
}
```

### Publisher directory

- Capability: `podcasts/publishers`
- Description: Publishers (networks), largest catalogue first.
- Instructions: Use to find a network's slug by name before asking about its shows, advertising, bias or suitability.
- Cost: 15 credits per call
- Capability file: [Publisher directory](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/publishers)

Accepted options:
- `q` (string): Case-insensitive substring of the publisher's name or slug; an exact name match sorts first. Example: `<q>`
- `sort` (string): podcast_count ranks by catalogue size (default); name is alphabetical. Example: `podcast_count`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "slug": "<slug>",
      "name": "<name>",
      "podcast_count": 0
    }
  ]
}
```

### Shows of a publisher

- Capability: `podcasts/publisher/shows`
- Description: The publisher's shows, most popular first.
- Instructions: Use to walk a network's catalogue by audience. For the same catalogue ranked by ad volume use advertising/publisher/shows.
- Cost: 15 credits per call
- Capability file: [Shows of a publisher](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/publisher/shows)

Accepted options:
- `id` (string, required): Publisher slug (for example iheartpodcasts, bbc-radio-4) or id, as carried on a podcast record's publisher. Example: `<id>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "slug": "<slug>",
      "title": "<title>",
      "description": "<description>",
      "language": "<language>",
      "explicit": false,
      "episode_count": 0,
      "popularity": 0,
      "image_url": "<image_url>",
      "url": "<url>",
      "publisher": {},
      "topics": [],
      "speakers": [],
      "format": {},
      "bias": "<bias>",
      "political_context": "<political_context>",
      "suitability_tier": "<suitability_tier>",
      "match_quality": "<match_quality>",
      "related": [],
      "recommended_guests": [],
      "recommended_sponsors": []
    }
  ]
}
```

### Episode segment

- Capability: `podcasts/segment`
- Description: One segment, returned directly: its type, title, summary and where it sits in the recording. The words themselves are podcasts/segment/transcript.
- Instructions: Use to see what a matched segment is (an interview, a topic discussion, an ad) and its time range. For its text call podcasts/segment/transcript.
- Cost: 5 credits per call
- Capability file: [Episode segment](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/segment)

Accepted options:
- `id` (string, required): Segment id, from a search match or a segment list. Example: `<id>`

Response schema example:
```json
{
  "id": "<id>",
  "number": 0,
  "title": "<title>",
  "type": "<type>",
  "description": "<description>",
  "summary": "<summary>",
  "start_seconds": 0,
  "end_seconds": 0,
  "duration_seconds": 0,
  "start_line": 0,
  "end_line": 0,
  "read_type": "<read_type>",
  "audio_url": "<audio_url>",
  "episode": {}
}
```

### Episode clip

- Capability: `podcasts/clip`
- Description: One clip, returned directly: a bounded highlight of an episode with its audio range, kind, engagement score and speaker.
- Instructions: Use when a segment needs to be cited as a playable range rather than as text. For its words call podcasts/clip/transcript.
- Cost: 15 credits per call
- Capability file: [Episode clip](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/clip)

Accepted options:
- `id` (string, required): Clip id, from a search match's clips or a clip list. Example: `<id>`

Response schema example:
```json
{
  "id": "<id>",
  "title": "<title>",
  "description": "<description>",
  "type": "<type>",
  "engagement_score": 0,
  "intro_statement": "<intro_statement>",
  "start_seconds": 0,
  "end_seconds": 0,
  "duration_seconds": 0,
  "audio_url": "<audio_url>",
  "episode": {},
  "segment": {},
  "speaker": {}
}
```

### Top-level topics by show count

- Capability: `podcasts/topics`
- Description: Top-level topics ordered by how many shows cover them.
- Instructions: Use to see which subject areas have the most shows. For the full taxonomy tree use entities/topics; for the shows in one topic use podcasts/list with topic_id.
- Cost: 15 credits per call
- Capability file: [Top-level topics by show count](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/topics)

Accepted options:
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "slug": "<slug>",
      "name": "<name>",
      "ancestry_path": "<ancestry_path>",
      "podcast_count": 0
    }
  ]
}
```

### Episode directory

- Capability: `podcasts/episodes/list`
- Description: Episodes across every show matching the filters, newest first, as full episode records.
- Instructions: Use for episode-level filtering without dialogue: every episode a person spoke on, every episode featuring a company, a show's episodes in a date range, episodes in a language. When the question is about what was said, search episodes instead.
- Cost: 5 credits per call
- Capability file: [Episode directory](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/episodes/list)

Accepted options:
- `podcast_id` (string): Restrict to one show, by slug, id or Apple collection id. Example: `<podcast_id>`
- `entity_id` (string): Episodes featuring this entity as a speaker or a mention, by slug (elon-musk, openai) or id. Example: `<entity_id>`
- `person_id` (string): Episodes where this person speaks, by person slug, entity slug or id. Works when the speaker has no knowledge-graph entity. Example: `<person_id>`
- `company_id` (string): Episodes featuring this company, by slug, domain or id. Example: `<company_id>`
- `role` (string): How the entity must relate to the episode: a speaking role, speaker for any speaking role, or mention for being talked about. Example: `guest`
- `published_after` (string): Only episodes published after this ISO 8601 date or date-time. Example: `<published_after>`
- `published_before` (string): Only episodes published before this ISO 8601 date or date-time. Example: `<published_before>`
- `language` (string): ISO 639-1 language code, for example en or fr. Matches the primary subtag, so fr covers fr-CA. Example: `<language>`
- `has_transcript` (boolean): Only episodes with a completed transcript. Example: `false`
- `fully_ingested` (boolean): Only episodes that reached the terminal ingestion milestone. Example: `false`
- `min_duration` (number): Minimum length in seconds. Example: `10`
- `max_duration` (number): Maximum length in seconds. Example: `10`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "slug": "<slug>",
      "title": "<title>",
      "description": "<description>",
      "published_at": "<published_at>",
      "duration_seconds": 0,
      "explicit": false,
      "has_transcript": false,
      "language": "<language>",
      "episode_number": 0,
      "image_url": "<image_url>",
      "url": "<url>",
      "audio_url": "<audio_url>",
      "podcast": {},
      "speakers": [],
      "topics": [],
      "segments": [],
      "clips": [],
      "transcript": {},
      "videos": [],
      "clip_count": 0,
      "entity_count": 0,
      "segment_count": 0
    }
  ]
}
```

### Episode feed

- Capability: `podcasts/episodes/feed`
- Description: Episodes that reached the milestone since the cursor, in ingestion order, with a cursor to poll again.
- Instructions: Use to poll for new episodes of a set of shows or topics as they are transcribed: a resumable, strictly ordered pull. A filter is required. For a one-off list by date use podcasts/episodes/list.
- Cost: 5 credits per call
- Capability file: [Episode feed](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/episodes/feed)

Accepted options:
- `milestone` (string): Deliver episodes once they reach this ingestion stage; ordered discovered, transcribed, segmented, fully_ingested. Example: `transcribed`
- `podcast_ids` (string): Shows to follow, comma-separated slugs or ids, at most 100. Example: `<podcast_ids>`
- `topic_ids` (string): Topics to follow, comma-separated slug paths (sports/football), ids or path hashes. A topic matches its descendants. Example: `<topic_ids>`
- `popularity_threshold` (number): Follow the most popular shows at or above this percentile, in (0, 1). The feed covers at most 100 shows in total. Example: `10`
- `since` (string): ISO 8601 start when no cursor is supplied. Omit both to start from now. Example: `<since>`
- `include` (string): Heavy relations to embed per episode, comma-separated: transcript, segments, clips, or all. Only valid when the milestone guarantees the data. Example: `<include>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "slug": "<slug>",
      "title": "<title>",
      "description": "<description>",
      "published_at": "<published_at>",
      "duration_seconds": 0,
      "explicit": false,
      "has_transcript": false,
      "language": "<language>",
      "episode_number": 0,
      "image_url": "<image_url>",
      "url": "<url>",
      "audio_url": "<audio_url>",
      "podcast": {},
      "speakers": [],
      "topics": [],
      "segments": [],
      "clips": [],
      "transcript": {},
      "videos": [],
      "clip_count": 0,
      "entity_count": 0,
      "segment_count": 0
    }
  ]
}
```

### Episode lookup by platform id

- Capability: `podcasts/episodes/lookup`
- Description: One result per identifier passed, echoing it beside the matched episode. An unresolved identifier has no episode field.
- Instructions: Use when you hold an Apple Podcasts episode URL or id, a YouTube video id, or an RSS guid and need the Particle episode id to read its transcript. Guids match exactly as supplied.
- Cost: 5 credits per call
- Capability file: [Episode lookup by platform id](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/episodes/lookup)

Accepted options:
- `platform` (string, required): Kind of identifier: apple (alias itunes) for Apple Podcasts episode ids, youtube for video ids, guid for the RSS guid, podcastindex, or the hosting platforms megaphone, omny, acast and art19. Example: `<platform>`
- `identifier` (string, required): One or more identifiers, comma-separated, up to 100. A full Apple Podcasts or YouTube URL is accepted in place of the bare id. Example: `<identifier>`

Response schema example:
```json
{
  "results": [
    {
      "identifier": "<identifier>",
      "episode": {}
    }
  ]
}
```

### Episode counts over time

- Capability: `podcasts/episodes/timeseries`
- Description: Zero-filled UTC buckets under buckets, with range totals beside them at the top level. Totals: total_episodes, distinct_podcasts and, with a search term, total_mentions.
- Instructions: Use for a trend rather than a list: how often a person appeared by month, how a show's output changed, how many episodes discussed a term each week. One call replaces paging the episode list per period.
- Cost: 5 credits per call
- Capability file: [Episode counts over time](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/episodes/timeseries)

Accepted options:
- `podcast_id` (string): Restrict to one show, by slug, id or Apple collection id. Example: `<podcast_id>`
- `entity_id` (string): Episodes featuring this entity as a speaker or a mention, by slug (elon-musk, openai) or id. Example: `<entity_id>`
- `person_id` (string): Episodes where this person speaks, by person slug, entity slug or id. Works when the speaker has no knowledge-graph entity. Example: `<person_id>`
- `company_id` (string): Episodes featuring this company, by slug, domain or id. Example: `<company_id>`
- `role` (string): How the entity must relate to the episode: a speaking role, speaker for any speaking role, or mention for being talked about. Example: `guest`
- `keyword_search` (string): Count episodes whose transcripts contain these terms (quoted phrases exact). Adds per-bucket mention_count. Not combinable with semantic_search. Example: `<keyword_search>`
- `semantic_search` (string): Count episodes whose transcripts match this meaning, at the search endpoint's threshold. Requires published_after. Not combinable with keyword_search. Example: `<semantic_search>`
- `published_after` (string): Only episodes published after this ISO 8601 date or date-time. Example: `<published_after>`
- `published_before` (string): Only episodes published before this ISO 8601 date or date-time. Example: `<published_before>`
- `interval` (string): Bucket width. Weeks start on Monday; all buckets are UTC-aligned. Example: `week`
- `language` (string): ISO 639-1 language code, for example en or fr. Matches the primary subtag, so fr covers fr-CA. Example: `<language>`
- `has_transcript` (boolean): Only episodes with a completed transcript. Example: `false`
- `fully_ingested` (boolean): Only episodes that reached the terminal ingestion milestone. Example: `false`
- `min_duration` (number): Minimum length in seconds. Example: `10`
- `max_duration` (number): Maximum length in seconds. Example: `10`

Response schema example:
```json
{
  "buckets": [
    {
      "start": "<start>",
      "count": 0,
      "mention_count": 0
    }
  ]
}
```

### Episode speakers

- Capability: `podcasts/episode/speakers`
- Description: Identified speakers with their roles and speaking time. Everyone when limit is omitted.
- Instructions: Use to find who was on an episode and in what role, with the person slug to follow into people/profile or people/guest. Ask for the advertiser role to see who voiced the sponsor reads.
- Cost: 15 credits per call
- Capability file: [Episode speakers](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/episode/speakers)

Accepted options:
- `id` (string, required): Episode slug or id: episode.id on a search match, or id on an episode list row. A podcast slug is not an episode id. Example: `<id>`
- `role` (string): Speaker roles to include, comma-separated and case-insensitive. Defaults to host,guest,panelist,correspondent; add advertiser for sponsor reads, soundbite_speaker for played clips, narrator or announcer for scripted voices. Example: `<role>`
- `limit` (number): Maximum records to return. Omit for all of them. Example: `10`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "association_id": "<association_id>",
      "name": "<name>",
      "role": "<role>",
      "descriptor": "<descriptor>",
      "description": "<description>",
      "speaking_duration_seconds": 0,
      "person": {},
      "entity": {}
    }
  ]
}
```

### Entities in an episode

- Capability: `podcasts/episode/entities`
- Description: Knowledge-graph entities mentioned in the episode with salience and occurrence counts. All of them when limit is omitted.
- Instructions: Use for what an episode was about in named things: the companies, people and products it discussed, ranked by salience. For where each one came up in the dialogue use podcasts/transcript/mentions.
- Cost: 15 credits per call
- Capability file: [Entities in an episode](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/episode/entities)

Accepted options:
- `id` (string, required): Episode slug or id: episode.id on a search match, or id on an episode list row. A podcast slug is not an episode id. Example: `<id>`
- `limit` (number): Maximum records to return. Omit for all of them. Example: `10`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "entity": {},
      "salience": 0,
      "occurrences": 0
    }
  ]
}
```

### Episode topics

- Capability: `podcasts/episode/topics`
- Description: The taxonomy topics the episode is classified under. All of them when limit is omitted.
- Instructions: Use to classify an episode by subject area, or to pick up a topic_id for filtering shows and episodes.
- Cost: 15 credits per call
- Capability file: [Episode topics](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/episode/topics)

Accepted options:
- `id` (string, required): Episode slug or id: episode.id on a search match, or id on an episode list row. A podcast slug is not an episode id. Example: `<id>`
- `limit` (number): Maximum records to return. Omit for all of them. Example: `10`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "slug": "<slug>",
      "name": "<name>",
      "ancestry": "<ancestry>",
      "ancestry_path": "<ancestry_path>",
      "episode_count": 0
    }
  ]
}
```

### Related episodes

- Capability: `podcasts/episode/related`
- Description: Episodes from other shows covering the same story or subject, best first, each with a calibrated score and band. Empty when the episode has no embedded content yet.
- Instructions: Use for who else covered this: the same story or subject on other shows, optionally within a week of the episode.
- Cost: 15 credits per call
- Capability file: [Related episodes](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/episode/related)

Accepted options:
- `id` (string, required): Episode slug or id: episode.id on a search match, or id on an episode list row. A podcast slug is not an episode id. Example: `<id>`
- `same_podcast` (boolean): Admit episodes of the same show. Off by default: a show's own episodes are its episode list. Example: `false`
- `published_within_days` (number): Only episodes published within this many days of the query episode, either side. A short window (7 to 30) answers who else covered this story. Example: `10`
- `include` (string): Pass basis to attach the signals behind each match: content similarity, shared entities, topics, news story, guests, and days apart. Example: `<include>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "episode": {},
      "score": 0,
      "band": "<band>",
      "basis": {}
    }
  ]
}
```

### Episode segments

- Capability: `podcasts/episode/segments`
- Description: The episode's AI-identified segments in order: intros, ad reads, topic discussions, interviews, outros. All of them when limit is omitted.
- Instructions: Use to see the structure of an episode and pick the section to read: which time ranges are ads to skip, where the interview starts, what each discussion covers. Then podcasts/segment/transcript for the words.
- Cost: 15 credits per call
- Capability file: [Episode segments](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/episode/segments)

Accepted options:
- `id` (string, required): Episode slug or id: episode.id on a search match, or id on an episode list row. A podcast slug is not an episode id. Example: `<id>`
- `limit` (number): Maximum records to return. Omit for all of them. Example: `10`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "number": 0,
      "title": "<title>",
      "type": "<type>",
      "description": "<description>",
      "summary": "<summary>",
      "start_seconds": 0,
      "end_seconds": 0,
      "duration_seconds": 0,
      "start_line": 0,
      "end_line": 0,
      "read_type": "<read_type>",
      "audio_url": "<audio_url>",
      "episode": {}
    }
  ]
}
```

### Episode clips

- Capability: `podcasts/episode/clips`
- Description: The episode's highlight clips, highest engagement score first.
- Instructions: Use for the quotable moments of an episode as bounded, playable ranges with a kind and a speaker.
- Cost: 5 credits per call
- Capability file: [Episode clips](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/episode/clips)

Accepted options:
- `id` (string, required): Episode slug or id: episode.id on a search match, or id on an episode list row. A podcast slug is not an episode id. Example: `<id>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "title": "<title>",
      "description": "<description>",
      "type": "<type>",
      "engagement_score": 0,
      "intro_statement": "<intro_statement>",
      "start_seconds": 0,
      "end_seconds": 0,
      "duration_seconds": 0,
      "audio_url": "<audio_url>",
      "episode": {},
      "segment": {},
      "speaker": {}
    }
  ]
}
```

### Transcript excerpt at a moment

- Capability: `podcasts/transcript/preview`
- Description: In the dialogue format: one segment's lines, with excerpt true and segment_id, segment_start_seconds and segment_end_seconds beside them saying what was actually returned. The text and srt formats answer with that format's body instead.
- Instructions: Use to read what was being said at a timestamp, or the opening of an episode, at a fifth of the full transcript's price. For a whole episode use podcasts/transcript.
- Cost: 15 credits per call
- Capability file: [Transcript excerpt at a moment](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/transcript/preview)

Accepted options:
- `id` (string, required): Episode slug or id: episode.id on a search match, or id on an episode list row. A podcast slug is not an episode id. Example: `<id>`
- `at` (number): A moment in the episode, in seconds. Returns the latest segment starting at or before it; a moment outside the episode clamps to the first or last segment. Omit for the opening segment. Example: `10`
- `format` (string): Output format: dialogue (speaker-attributed JSON lines, the shape described here), text (Speaker: text lines), or srt (SubRip). The text and srt bodies are not the lines shape. Example: `dialogue`

Response schema example:
```json
{
  "lines": [
    {
      "number": 0,
      "speaker": "<speaker>",
      "role": "<role>",
      "text": "<text>",
      "start_seconds": 0,
      "end_seconds": 0
    }
  ]
}
```

### Entity mentions in a transcript

- Capability: `podcasts/transcript/mentions`
- Description: Under entities, one row per entity mentioned, each with its mention windows and surrounding context. With entity_id the page is that entity's windows; without it the page is the entities.
- Instructions: Use to see exactly where and how a company, person or product was discussed within one episode, with the dialogue around each mention. Across episodes, use podcasts/mentions.
- Cost: 15 credits per call
- Capability file: [Entity mentions in a transcript](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/transcript/mentions)

Accepted options:
- `id` (string, required): Episode slug or id: episode.id on a search match, or id on an episode list row. A podcast slug is not an episode id. Example: `<id>`
- `entity_id` (string): Entity id or slug. Omit to return mentions of every entity in the episode. Example: `<entity_id>`
- `context_lines` (number): Dialogue lines of context on each side of every mention line; adjacent windows merge. Example: `2`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "entities": [
    {
      "entity": {},
      "total_mention_count": 0,
      "mention_variants": [],
      "mentions": []
    }
  ]
}
```

### Dialogue mentions of an entity

- Capability: `podcasts/mentions`
- Description: Under data, one row per episode with every mention window in it, newest episode first, mention lines flagged is_mention. Beside data the body carries the resolved entity, or person and company blocks and matched_by when matched by name.
- Instructions: Use for every line of dialogue about one person or company across podcasts: the read-everything-about-X call. Resolve the subject with entities/search first. For dialogue by topic or exact phrase use podcasts/episodes/search.
- Cost: 15 credits per call
- Capability file: [Dialogue mentions of an entity](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/mentions)

Accepted options:
- `entity_id` (string): Entity slug (sam-altman) or id. A person slug also resolves; a person without a linked entity falls back to name matching. Example: `<entity_id>`
- `company_id` (string): Company slug, domain or id; resolves to its linked entity or falls back to name matching. Example: `<company_id>`
- `podcast_id` (string): Only mentions inside one show. Example: `<podcast_id>`
- `publisher_id` (string): Only mentions on one publisher's shows, by slug or id. Example: `<publisher_id>`
- `episode_id` (string): Only mentions inside one episode. Example: `<episode_id>`
- `role` (string): Constrain how the entity participates. Example: `guest`
- `sort` (string): recency (default), popularity of the parent show, or favorites. Example: `recency`
- `include_ads` (boolean): Include mentions inside ad reads, which are excluded by default. Example: `false`
- `language` (string): ISO 639-1 language code, for example en or fr. Matches the primary subtag, so fr covers fr-CA. Example: `<language>`
- `since` (string): Only episodes published after this date. Example: `<since>`
- `until` (string): Only episodes published before this date. Example: `<until>`
- `context_lines` (number): Surrounding dialogue lines around each mention. Example: `2`
- `limit` (number): Episodes per page; each episode's full set of windows arrives in one page. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "episode": {},
      "mention_count": 0,
      "mention_variants": [],
      "windows": [],
      "truncated": false
    }
  ]
}
```

### Mention counts over time

- Capability: `podcasts/mentions/timeseries`
- Description: Zero-filled UTC buckets under buckets, with range totals beside them at the top level. Totals: total_episodes, total_mentions, distinct_podcasts, and the resolved entity or company block. Ranges are capped at 1000 buckets.
- Instructions: Use for how mentions of a person or company trend by day, week or month, optionally within one show or network. One call instead of paging podcasts/mentions per period.
- Cost: 15 credits per call
- Capability file: [Mention counts over time](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/mentions/timeseries)

Accepted options:
- `entity_id` (string): Entity slug or id. Example: `<entity_id>`
- `company_id` (string): Company slug, domain or id. Example: `<company_id>`
- `podcast_id` (string): Only mentions inside one show. Example: `<podcast_id>`
- `publisher_id` (string): Only mentions on one publisher's shows. Example: `<publisher_id>`
- `role` (string): Constrain how the entity participates. Example: `guest`
- `include_ads` (boolean): Count mentions inside ad reads too. Example: `false`
- `language` (string): ISO 639-1 language code, for example en or fr. Matches the primary subtag, so fr covers fr-CA. Example: `<language>`
- `published_after` (string): Only episodes published on or after this date. Omit for all time. Example: `<published_after>`
- `published_before` (string): Only episodes published on or before this date. Defaults to now. Example: `<published_before>`
- `interval` (string): Bucket width. Weeks start on Monday; all buckets are UTC-aligned. Example: `week`

Response schema example:
```json
{
  "buckets": [
    {
      "start": "<start>",
      "episode_count": 0,
      "mention_count": 0
    }
  ]
}
```

### Segment directory

- Capability: `podcasts/segments`
- Description: Segments across episodes matching the filters. No global feed: a filter is required.
- Instructions: Use to pull one kind of section across a show: every interview, every ad read, every topic discussion in a date range. For one episode's structure use podcasts/episode/segments.
- Cost: 5 credits per call
- Capability file: [Segment directory](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/segments)

Accepted options:
- `episode_id` (string): Only segments of one episode, by slug or id. Example: `<episode_id>`
- `podcast_id` (string): Only segments from one show, by slug, id or Apple collection id. Example: `<podcast_id>`
- `type` (string): Only this segment type. Example: `INTRO`
- `since` (string): Only episodes published on or after this ISO 8601 date or date-time. Example: `<since>`
- `until` (string): Only episodes published before this ISO 8601 date or date-time. A bare date covers that whole UTC day. Example: `<until>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "number": 0,
      "title": "<title>",
      "type": "<type>",
      "description": "<description>",
      "summary": "<summary>",
      "start_seconds": 0,
      "end_seconds": 0,
      "duration_seconds": 0,
      "start_line": 0,
      "end_line": 0,
      "read_type": "<read_type>",
      "audio_url": "<audio_url>",
      "episode": {}
    }
  ]
}
```

### Segment transcript

- Capability: `podcasts/segment/transcript`
- Description: In the dialogue format: the segment's lines, renumbered from 1 with timestamps relative to the segment's start. The text and srt formats answer with that format's body instead.
- Instructions: Use to read the words of one segment in full and in order, at the price of a segment rather than an episode.
- Cost: 15 credits per call
- Capability file: [Segment transcript](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/segment/transcript)

Accepted options:
- `id` (string, required): Segment id. Example: `<id>`
- `format` (string): Output format: dialogue (speaker-attributed JSON lines, the shape described here), text (Speaker: text lines), or srt (SubRip). The text and srt bodies are not the lines shape. Example: `dialogue`

Response schema example:
```json
{
  "lines": [
    {
      "number": 0,
      "speaker": "<speaker>",
      "role": "<role>",
      "text": "<text>",
      "start_seconds": 0,
      "end_seconds": 0
    }
  ]
}
```

### Clip directory

- Capability: `podcasts/clips`
- Description: Highlight clips across episodes, ranked by engagement potential.
- Instructions: Use to browse quotable moments by show, speaker or kind. For clips about a subject, search episodes: matching clips ride inside each search result.
- Cost: 15 credits per call
- Capability file: [Clip directory](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/clips)

Accepted options:
- `episode_id` (string): Only clips from one episode. Example: `<episode_id>`
- `podcast_id` (string): Only clips from one show. Example: `<podcast_id>`
- `speaker` (string): Only clips whose primary speaker is this person, by person slug, entity slug or id. Example: `<speaker>`
- `type` (string): Clip kind: SPICY, CONTROVERSIAL, EMOTIONAL, FUNNY, SHOCKING, INSIGHTFUL, INFORMATIVE, EDUCATIONAL, PHILOSOPHICAL, AHA_MOMENT, NOTABLE_LINE, BEST_STORY or DEBATE_DISAGREEMENT. Example: `<type>`
- `min_engagement` (number): Minimum engagement potential, 0 to 100; above 70 is a strong clip. Example: `10`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "title": "<title>",
      "description": "<description>",
      "type": "<type>",
      "engagement_score": 0,
      "intro_statement": "<intro_statement>",
      "start_seconds": 0,
      "end_seconds": 0,
      "duration_seconds": 0,
      "audio_url": "<audio_url>",
      "episode": {},
      "segment": {},
      "speaker": {}
    }
  ]
}
```

### Clip transcript

- Capability: `podcasts/clip/transcript`
- Description: In the dialogue format: the clip's lines, renumbered from 1 with timestamps relative to the clip's start. The text and srt formats answer with that format's body instead.
- Instructions: Use to quote a clip verbatim with speaker labels, or export it as subtitles with format srt.
- Cost: 15 credits per call
- Capability file: [Clip transcript](https://firecrawl.dev/alexandria/agents/providers/particle/podcasts/clip/transcript)

Accepted options:
- `id` (string, required): Clip id. Example: `<id>`
- `format` (string): Output format: dialogue (speaker-attributed JSON lines, the shape described here), text (Speaker: text lines), or srt (SubRip). The text and srt bodies are not the lines shape. Example: `dialogue`

Response schema example:
```json
{
  "lines": [
    {
      "number": 0,
      "speaker": "<speaker>",
      "role": "<role>",
      "text": "<text>",
      "start_seconds": 0,
      "end_seconds": 0
    }
  ]
}
```

### Person profile

- Capability: `people/profile`
- Description: One person, returned directly: name, slug, bio, company-role history most recent first, known profile links and the linked knowledge-graph entity.
- Instructions: Use to go from a name on an episode to the person: who they are, where they work and worked, and their profile links. For their podcast appearances use people/guest.
- Cost: 5 credits per call
- Capability file: [Person profile](https://firecrawl.dev/alexandria/agents/providers/particle/people/profile)

Accepted options:
- `id` (string, required): Person slug (recommended), the person's knowledge-graph entity slug, or the encoded person id. Example: `<id>`

Response schema example:
```json
{
  "id": "<id>",
  "slug": "<slug>",
  "name": "<name>",
  "description": "<description>",
  "detailed_description": "<detailed_description>",
  "image_url": "<image_url>",
  "current_role": {},
  "roles": [],
  "external_links": [],
  "knowledge_graph_entity": {}
}
```

### Guest profile

- Capability: `people/guest`
- Description: One guest, returned directly: the person record plus lifetime stats (appearances, distinct shows, speaking time, first and last appearance, mix by bias and suitability tier) and the shows they appear on most.
- Instructions: Use when the question is about someone as a podcast guest: how often they appear, where, and since when. For the episode list use people/guest/appearances.
- Cost: 15 credits per call
- Capability file: [Guest profile](https://firecrawl.dev/alexandria/agents/providers/particle/people/guest)

Accepted options:
- `id` (string, required): Person slug (recommended), the person's knowledge-graph entity slug, or the encoded person id. Example: `<id>`

Response schema example:
```json
{
  "id": "<id>",
  "slug": "<slug>",
  "name": "<name>",
  "description": "<description>",
  "detailed_description": "<detailed_description>",
  "image_url": "<image_url>",
  "current_role": {},
  "roles": [],
  "external_links": [],
  "knowledge_graph_entity": {},
  "stats": {},
  "top_podcasts": []
}
```

### Person profile links

- Capability: `people/external-links`
- Description: Every known third-party profile of the person: LinkedIn, Wikipedia, social accounts, each with its identifier and URL. All of them when limit is omitted.
- Instructions: Use to get a person's LinkedIn or social handles. The reverse, handle to person, is entities/lookup.
- Cost: 15 credits per call
- Capability file: [Person profile links](https://firecrawl.dev/alexandria/agents/providers/particle/people/external-links)

Accepted options:
- `id` (string, required): Person slug (recommended), the person's knowledge-graph entity slug, or the encoded person id. Example: `<id>`
- `limit` (number): Maximum records to return. Omit for all of them. Example: `10`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "platform": {},
      "identifier": "<identifier>",
      "url": "<url>",
      "attributes": []
    }
  ]
}
```

### Guest directory

- Capability: `people/guests`
- Description: People who have appeared on at least one episode in a non-host role, with appearance counts.
- Instructions: Use to find guests by name, by show, by topic or by how often they appear, and pick up the person slug. For who is currently making the rounds use people/guests/trending.
- Cost: 15 credits per call
- Capability file: [Guest directory](https://firecrawl.dev/alexandria/agents/providers/particle/people/guests)

Accepted options:
- `q` (string): Case-insensitive substring of the guest's display name. Example: `<q>`
- `min_appearances` (number): Only guests with at least this many lifetime appearances. Example: `10`
- `podcast_id` (string): Only guests who have appeared on this show. Example: `<podcast_id>`
- `topic_id` (string): Only guests with an appearance on an episode under this topic. Example: `<topic_id>`
- `appeared_since` (string): Only guests with an appearance published on or after this ISO 8601 date. Example: `<appeared_since>`
- `suitability_tier_max` (string): Only appearances on podcasts at or below this IAB Tech Lab brand-suitability tier. Example: `SAFE`
- `sort` (string): appearances (default) or recency. Example: `appearances`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "slug": "<slug>",
      "name": "<name>",
      "description": "<description>",
      "image_url": "<image_url>",
      "appearance_count": 0,
      "distinct_podcasts": 0,
      "first_appearance_at": "<first_appearance_at>",
      "last_appearance_at": "<last_appearance_at>"
    }
  ]
}
```

### Trending guests

- Capability: `people/guests/trending`
- Description: Guests whose recent cross-show interview activity is elevated above their own baseline, with in-window appearance counts. Perennial regulars and daily contributors are filtered out by design.
- Instructions: Use for who is doing the podcast circuit right now: a book launch, a product unveil, a news moment, or someone new. For a steady-state directory use people/guests.
- Cost: 25 credits per call
- Capability file: [Trending guests](https://firecrawl.dev/alexandria/agents/providers/particle/people/guests/trending)

Accepted options:
- `since` (string): Inclusive start of the trend window. Default 30 days ago. Example: `<since>`
- `min_distinct_podcasts` (number): Minimum distinct shows appeared on inside the window. Default 2. Example: `10`
- `first_appearance_since` (string): Only guests whose first ever appearance is on or after this date: the new-on-the-scene cut. Example: `<first_appearance_since>`
- `topic_id` (string): Only guests with an in-window appearance under this topic. Example: `<topic_id>`
- `suitability_tier_max` (string): Only appearances on podcasts at or below this IAB Tech Lab brand-suitability tier. Example: `SAFE`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "guest": {},
      "recent_appearances": 0,
      "first_appearance_in_window": "<first_appearance_in_window>",
      "last_appearance_at": "<last_appearance_at>"
    }
  ]
}
```

### Guest appearances

- Capability: `people/guest/appearances`
- Description: The episodes the guest appeared on, most recent first, each with the show, speaking time and the show's bias and suitability tier when evaluated.
- Instructions: Use for where someone has appeared, episode by episode, to read what they said: take episode.id to podcasts/transcript with speaker set to their name.
- Cost: 15 credits per call
- Capability file: [Guest appearances](https://firecrawl.dev/alexandria/agents/providers/particle/people/guest/appearances)

Accepted options:
- `id` (string, required): Person slug (recommended), the person's knowledge-graph entity slug, or the encoded person id. Example: `<id>`
- `podcast_id` (string): Only appearances on one show. Example: `<podcast_id>`
- `topic_id` (string): Only appearances on episodes under this topic. Example: `<topic_id>`
- `published_after` (string): Only episodes published after this ISO 8601 date or date-time. Example: `<published_after>`
- `published_before` (string): Only episodes published before this ISO 8601 date or date-time. Example: `<published_before>`
- `suitability_tier_max` (string): Only appearances on podcasts at or below this IAB Tech Lab brand-suitability tier. Example: `SAFE`
- `min_speaking_seconds` (number): Only appearances with at least this much identified speaking time. Example: `10`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "episode": {},
      "podcast": {},
      "speaking_seconds": 0,
      "bias": "<bias>",
      "suitability_tier": "<suitability_tier>"
    }
  ]
}
```

### Shows a guest has appeared on

- Capability: `people/guest/shows`
- Description: The distinct shows the guest has appeared on, with per-show appearance counts, first and last dates, and the show's bias and suitability when evaluated.
- Instructions: Use for the set of shows behind a guest rather than the episodes: which shows book them and how often.
- Cost: 15 credits per call
- Capability file: [Shows a guest has appeared on](https://firecrawl.dev/alexandria/agents/providers/particle/people/guest/shows)

Accepted options:
- `id` (string, required): Person slug (recommended), the person's knowledge-graph entity slug, or the encoded person id. Example: `<id>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "podcast": {},
      "appearance_count": 0,
      "first_appearance_at": "<first_appearance_at>",
      "last_appearance_at": "<last_appearance_at>",
      "bias": "<bias>",
      "suitability_tier": "<suitability_tier>"
    }
  ]
}
```

### Shows a guest could appear on

- Capability: `people/guest/pitch-list`
- Description: Shows the person has not appeared on, ranked by how related they are to the shows that booked them, each with a score and band. Empty for someone with no guest bookings on record.
- Instructions: Use to build a pitch list for a guest: the shows most like the ones that already booked them, with the venues to cite.
- Cost: 25 credits per call
- Capability file: [Shows a guest could appear on](https://firecrawl.dev/alexandria/agents/providers/particle/people/guest/pitch-list)

Accepted options:
- `id` (string, required): Person slug (recommended), the person's knowledge-graph entity slug, or the encoded person id. Example: `<id>`
- `include` (string): Pass via to attach, per recommendation, the person's own shows that led to it. Example: `<include>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "podcast": {},
      "score": 0,
      "band": "<band>",
      "via": []
    }
  ]
}
```

### Guest roster of a show

- Capability: `people/show-guests`
- Description: The identified guests of the show, grouped by person, with per-show appearance counts and first and last dates.
- Instructions: Use for who has been on a show and how often. For who it could book next use people/show-recommended-guests.
- Cost: 15 credits per call
- Capability file: [Guest roster of a show](https://firecrawl.dev/alexandria/agents/providers/particle/people/show-guests)

Accepted options:
- `id` (string, required): Podcast slug (for example all-in), Particle id, or numeric Apple collection id. Take slugs from responses; a constructed slug returns 404. Example: `<id>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "slug": "<slug>",
      "name": "<name>",
      "description": "<description>",
      "image_url": "<image_url>",
      "appearance_count": 0,
      "distinct_podcasts": 0,
      "first_appearance_at": "<first_appearance_at>",
      "last_appearance_at": "<last_appearance_at>"
    }
  ]
}
```

### Guests a show could book

- Capability: `people/show-recommended-guests`
- Description: People who guested on the show's related shows but never on this one, ranked by venue relatedness and how many independent publishers chose them. Circuit regulars are excluded.
- Instructions: Use as a booking pipeline for a show: guests its peers chose that it has not had yet.
- Cost: 25 credits per call
- Capability file: [Guests a show could book](https://firecrawl.dev/alexandria/agents/providers/particle/people/show-recommended-guests)

Accepted options:
- `id` (string, required): Podcast slug (for example all-in), Particle id, or numeric Apple collection id. Take slugs from responses; a constructed slug returns 404. Example: `<id>`
- `include` (string): Pass via to attach, per recommended guest, the related shows that booked them. Example: `<include>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "person": {},
      "score": 0,
      "band": "<band>",
      "shared_show_count": 0,
      "via": []
    }
  ]
}
```

### Company directory

- Capability: `companies/search`
- Description: Companies matching the filters, with their identifiers.
- Instructions: Use to resolve a company by name, ticker, domain, CIK or Wikidata QID to the slug every company capability takes. The record itself is advertising/company.
- Cost: 5 credits per call
- Capability file: [Company directory](https://firecrawl.dev/alexandria/agents/providers/particle/companies/search)

Accepted options:
- `q` (string): Company name, case-insensitive partial match. Example: `<q>`
- `ids` (string): Bulk get: comma-separated slugs, domains or ids, up to 100. Other filters and paging are ignored when set. Example: `<ids>`
- `ticker` (string): Stock ticker symbols, comma-separated. Example: `AAPL`
- `domain` (string): Company domains, comma-separated. Example: `<domain>`
- `cik` (string): SEC CIKs, comma-separated. Example: `<cik>`
- `qid` (string): Wikidata QIDs, comma-separated. Example: `<qid>`
- `entity_id` (string): Knowledge-graph entity slugs or ids, comma-separated. Example: `<entity_id>`
- `updated_after` (string): Only companies updated after this ISO 8601 date or date-time. Example: `<updated_after>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "name": "<name>",
      "description": "<description>",
      "identifiers": {},
      "external_links": [],
      "image_url": "<image_url>",
      "image_mode": "<image_mode>",
      "updated_at": "<updated_at>"
    }
  ]
}
```

### People at a company

- Capability: `companies/people`
- Description: People associated with the company, current roles first and most recently joined first, each a full person record.
- Instructions: Use to find executives and role holders at a company, or the marketing, brand and partnerships contacts a sponsorship conversation would go to.
- Cost: 25 credits per call
- Capability file: [People at a company](https://firecrawl.dev/alexandria/agents/providers/particle/companies/people)

Accepted options:
- `id` (string, required): Company slug (for example nvidia), domain (nvidia.com), or id. Example: `<id>`
- `current_only` (string): Only people currently in a role there. Set false to include past roles. Example: `true`
- `title` (string): Case-insensitive substring of the role title, for example chief or founder. Example: `<title>`
- `role` (string): Only people in this contact role class, the ones a sponsorship pitch would reach. Example: `marketing`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "slug": "<slug>",
      "name": "<name>",
      "description": "<description>",
      "detailed_description": "<detailed_description>",
      "image_url": "<image_url>",
      "current_role": {},
      "roles": [],
      "external_links": [],
      "knowledge_graph_entity": {}
    }
  ]
}
```

### Company products

- Capability: `companies/products`
- Description: The company's product hierarchy as a nested tree: segments containing product lines containing products.
- Instructions: Use to see what a company sells, structured by segment and product line, for example to match an ad read's offer to a product.
- Cost: 25 credits per call
- Capability file: [Company products](https://firecrawl.dev/alexandria/agents/providers/particle/companies/products)

Accepted options:
- `id` (string, required): Company slug (for example nvidia), domain (nvidia.com), or id. Example: `<id>`
- `status` (string): Lifecycle statuses to include, comma-separated. Default active. Example: `<status>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "company_id": "<company_id>",
      "name": "<name>",
      "level": "<level>",
      "description": "<description>",
      "status": "<status>",
      "product_url": "<product_url>",
      "children": [],
      "updated_at": "<updated_at>"
    }
  ]
}
```

### Company profile links

- Capability: `companies/external-links`
- Description: Every known profile and identifier of the company: LinkedIn, social accounts, domain, Wikidata QID, SEC CIK, tickers. All of them when limit is omitted.
- Instructions: Use to get a company's handles, domain, CIK or ticker. The reverse, identifier to company, is entities/lookup.
- Cost: 15 credits per call
- Capability file: [Company profile links](https://firecrawl.dev/alexandria/agents/providers/particle/companies/external-links)

Accepted options:
- `id` (string, required): Company slug (for example nvidia), domain (nvidia.com), or id. Example: `<id>`
- `limit` (number): Maximum records to return. Omit for all of them. Example: `10`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "platform": {},
      "identifier": "<identifier>",
      "url": "<url>",
      "attributes": []
    }
  ]
}
```

### Company competitors

- Capability: `companies/competitors`
- Description: Competitors ordered by prominence (news coverage, market cap, podcast appearances, notability), each with the basis of the relationship.
- Instructions: Use for a company's competitive set with the reason each one is on it, before comparing their podcast presence or advertising.
- Cost: 25 credits per call
- Capability file: [Company competitors](https://firecrawl.dev/alexandria/agents/providers/particle/companies/competitors)

Accepted options:
- `id` (string, required): Company slug (for example nvidia), domain (nvidia.com), or id. Example: `<id>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "company": {},
      "competitive_basis": "<competitive_basis>"
    }
  ]
}
```

### Sponsor profile

- Capability: `advertising/sponsor`
- Description: One sponsor, returned directly: name, the company behind it, and its ad count, show reach and episode reach in the window.
- Instructions: Use to find who is buying advertising, or to go from a sponsor back to the company paying for it. For where it runs use advertising/sponsor/shows.
- Cost: 25 credits per call
- Capability file: [Sponsor profile](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/sponsor)

Accepted options:
- `id` (string, required): Sponsor id, or a company slug, domain, or id: a company reference aggregates across every sponsor linked to it. Example: `<id>`
- `since` (string): Only episodes published on or after this ISO 8601 date or date-time. Example: `<since>`
- `until` (string): Only episodes published before this ISO 8601 date or date-time. A bare date covers that whole UTC day. Example: `<until>`

Response schema example:
```json
{
  "id": "<id>",
  "name": "<name>",
  "company": {},
  "ad_count": 0,
  "podcast_reach": 0,
  "episode_reach": 0,
  "first_seen_at": "<first_seen_at>",
  "last_seen_at": "<last_seen_at>"
}
```

### Company profile

- Capability: `advertising/company`
- Description: One company as Particle holds it, returned directly: name, description, identifiers (slug, domain, ticker, CIK, QID) and profile links.
- Instructions: Use for the company record behind a sponsor, an entity or a companies/search hit. For its podcast advertising footprint use advertising/company/overview; for firmographics or funding, a company data provider is the better source.
- Cost: 5 credits per call
- Capability file: [Company profile](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/company)

Accepted options:
- `id` (string, required): Company slug (for example nvidia), domain (nvidia.com), or id. Example: `<id>`

Response schema example:
```json
{
  "id": "<id>",
  "name": "<name>",
  "description": "<description>",
  "identifiers": {},
  "external_links": [],
  "image_url": "<image_url>",
  "image_mode": "<image_mode>",
  "updated_at": "<updated_at>"
}
```

### Sponsor directory

- Capability: `advertising/sponsors`
- Description: Sponsors with their ad count, show reach and episode reach.
- Instructions: Use to find a sponsor by name or by company and pick up its id. For the biggest spenders use advertising/leaderboard.
- Cost: 25 credits per call
- Capability file: [Sponsor directory](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/sponsors)

Accepted options:
- `q` (string): Sponsor name, case-insensitive partial match. Example: `<q>`
- `company_id` (string): Only sponsors linked to this company, by id, domain or entity slug. Example: `<company_id>`
- `since` (string): Scope each sponsor's counts to ads from episodes published on or after this date. Sponsors with no activity in the window are still listed. Example: `<since>`
- `until` (string): Scope each sponsor's counts to ads from episodes published before this date. Example: `<until>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "name": "<name>",
      "company": {},
      "ad_count": 0,
      "podcast_reach": 0,
      "episode_reach": 0,
      "first_seen_at": "<first_seen_at>",
      "last_seen_at": "<last_seen_at>"
    }
  ]
}
```

### Trending sponsors

- Capability: `advertising/sponsors/trending`
- Description: Sponsors whose ad volume is accelerating, ranked by the change between the trailing window and the one before it.
- Instructions: Use for which advertisers are ramping podcast spend right now, by airdate.
- Cost: 25 credits per call
- Capability file: [Trending sponsors](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/sponsors/trending)

Accepted options:
- `window_days` (number): Length of each comparison window; the trailing window is ranked against the equal window before it. Example: `7`
- `min_podcast_reach` (number): Only sponsors whose in-window ads span at least this many shows. Example: `3`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "sponsor": {},
      "recent_ad_count": 0,
      "previous_ad_count": 0,
      "ad_count_delta": 0,
      "last_ad_at": "<last_ad_at>"
    }
  ]
}
```

### Shows a sponsor buys

- Capability: `advertising/sponsor/shows`
- Description: Shows where the sponsor advertises, ordered by episodes carrying it. A company reference aggregates every sponsor linked to the company.
- Instructions: Use for where an advertiser buys: the canonical footprint of one sponsor, or of a whole company across its brands.
- Cost: 25 credits per call
- Capability file: [Shows a sponsor buys](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/sponsor/shows)

Accepted options:
- `id` (string, required): Sponsor id, or a company slug, domain, or id: a company reference aggregates across every sponsor linked to it. Example: `<id>`
- `since` (string): Only episodes published on or after this ISO 8601 date or date-time. Example: `<since>`
- `until` (string): Only episodes published before this ISO 8601 date or date-time. A bare date covers that whole UTC day. Example: `<until>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "podcast": {},
      "ad_count": 0,
      "episode_count": 0,
      "last_seen_at": "<last_seen_at>"
    }
  ]
}
```

### Publishers a sponsor buys across

- Capability: `advertising/sponsor/publishers`
- Description: Publishers the sponsor advertises across, ordered by how many of each catalogue's shows it appears on. High coverage across a network is the signature of a network buy.
- Instructions: Use to tell network buys from per-show buys: a sponsor at 60 to 100 percent coverage of several publishers is buying bundles.
- Cost: 25 credits per call
- Capability file: [Publishers a sponsor buys across](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/sponsor/publishers)

Accepted options:
- `id` (string, required): Sponsor id, or a company slug, domain, or id: a company reference aggregates across every sponsor linked to it. Example: `<id>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "publisher": {},
      "podcast_coverage": 0,
      "publisher_podcast_count": 0,
      "coverage_share": 0,
      "ad_count": 0,
      "episode_reach": 0,
      "first_seen_at": "<first_seen_at>",
      "last_seen_at": "<last_seen_at>"
    }
  ]
}
```

### Ad reads of a sponsor

- Capability: `advertising/sponsor/segments`
- Description: The individual ad segments attributed to the sponsor, newest episode first. Network promos are excluded.
- Instructions: Use to read the actual ad reads for a sponsor, then podcasts/segment/transcript for the words of one.
- Cost: 25 credits per call
- Capability file: [Ad reads of a sponsor](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/sponsor/segments)

Accepted options:
- `id` (string, required): Sponsor id, or a company slug, domain, or id: a company reference aggregates across every sponsor linked to it. Example: `<id>`
- `podcast_id` (string): Only ads on one show, by slug, id or Apple collection id. Example: `<podcast_id>`
- `since` (string): Only episodes published on or after this ISO 8601 date or date-time. Example: `<since>`
- `until` (string): Only episodes published before this ISO 8601 date or date-time. A bare date covers that whole UTC day. Example: `<until>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "number": 0,
      "title": "<title>",
      "type": "<type>",
      "description": "<description>",
      "summary": "<summary>",
      "start_seconds": 0,
      "end_seconds": 0,
      "duration_seconds": 0,
      "start_line": 0,
      "end_line": 0,
      "read_type": "<read_type>",
      "audio_url": "<audio_url>",
      "episode": {}
    }
  ]
}
```

### Sponsor leaderboard

- Capability: `advertising/leaderboard`
- Description: Sponsors ranked by the metric over the window.
- Instructions: Use for the biggest podcast advertisers overall, in a period, or on one network. For the top-ten snapshot use advertising/leaderboard/preview.
- Cost: 25 credits per call
- Capability file: [Sponsor leaderboard](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/leaderboard)

Accepted options:
- `metric` (string): Metric to rank by. Example: `ad_count`
- `since` (string): Only episodes published on or after this ISO 8601 date or date-time. Example: `<since>`
- `until` (string): Only episodes published before this ISO 8601 date or date-time. A bare date covers that whole UTC day. Example: `<until>`
- `company_id` (string): Only sponsors linked to this company. Example: `<company_id>`
- `publisher_id` (string): Only ads on this publisher's shows, by slug or id. Example: `<publisher_id>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "rank": 0,
      "sponsor": {}
    }
  ]
}
```

### Sponsor leaderboard, top ten

- Capability: `advertising/leaderboard/preview`
- Description: The top ten sponsors of the trailing seven days, each with its movement against the seven-day window ending thirty days ago. The same board for every caller.
- Instructions: Use for a quick read of who is spending most on podcasts this week and who is climbing. For deeper pages, other windows or filters use advertising/leaderboard.
- Cost: 25 credits per call
- Capability file: [Sponsor leaderboard, top ten](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/leaderboard/preview)

Accepted options:
- `metric` (string): Metric to rank by. Example: `ad_count`

Response schema example:
```json
{
  "data": [
    {
      "rank": 0,
      "previous_rank": 0,
      "rank_change": 0,
      "movement": "<movement>",
      "sponsor": {}
    }
  ]
}
```

### Publisher advertising leaderboard

- Capability: `advertising/publishers/leaderboard`
- Description: Publishers ranked by advertising activity across their catalogue, all time.
- Instructions: Use for which networks carry the most advertising, or monetise their catalogue most densely.
- Cost: 25 credits per call
- Capability file: [Publisher advertising leaderboard](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/publishers/leaderboard)

Accepted options:
- `metric` (string): Metric to rank publishers by. ads_per_active_podcast is monetisation density, where small sub-networks outrank broad catalogues. Example: `ad_count`
- `min_active_podcasts` (number): Only publishers with at least this many shows that have run an ad. Example: `5`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "rank": 0,
      "publisher": {},
      "ad_count": 0,
      "unique_sponsors": 0,
      "episode_reach": 0,
      "ads_per_active_podcast": 0,
      "coverage": {}
    }
  ]
}
```

### Sponsors that appear together

- Capability: `advertising/co-occurrence`
- Description: Pairs of sponsors that frequently share episodes.
- Instructions: Use for who a sponsor shares ad breaks with: the advertisers that buy the same inventory.
- Cost: 25 credits per call
- Capability file: [Sponsors that appear together](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/co-occurrence)

Accepted options:
- `sponsor_id` (string): Only pairs involving this sponsor. Example: `<sponsor_id>`
- `company_id` (string): Only pairs involving this company, by id, domain or entity slug. Example: `<company_id>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "sponsor_a": {},
      "sponsor_b": {},
      "shared_episodes": 0
    }
  ]
}
```

### Ad placements over time

- Capability: `advertising/timeseries`
- Description: Zero-filled UTC buckets under buckets, with range totals beside them at the top level. Totals: total_ads, host_read_count, pre_recorded_count, distinct_podcasts, distinct_episodes. Network promos are excluded.
- Instructions: Use for how an advertiser's podcast spend trends by week or month, optionally on one show or network, and its host-read mix.
- Cost: 25 credits per call
- Capability file: [Ad placements over time](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/timeseries)

Accepted options:
- `sponsor_id` (string): Sponsor id. Exactly one of sponsor_id or company_id. Example: `<sponsor_id>`
- `company_id` (string): Company id, domain or entity slug; aggregates every sponsor linked to it. Example: `<company_id>`
- `podcast_id` (string): Only placements on one show. Example: `<podcast_id>`
- `publisher_id` (string): Only placements on one publisher's shows. Example: `<publisher_id>`
- `published_after` (string): Inclusive start of the range. Omit for all time. Example: `<published_after>`
- `published_before` (string): End of the range; a bare date covers the whole day. Defaults to now. Example: `<published_before>`
- `interval` (string): Bucket width. Weeks start on Monday; all buckets are UTC-aligned. Example: `week`

Response schema example:
```json
{
  "buckets": [
    {
      "start": "<start>",
      "count": 0,
      "host_read_count": 0,
      "pre_recorded_count": 0
    }
  ]
}
```

### Show advertising profile

- Capability: `advertising/show`
- Description: Advertising on one show, returned directly: totals, read-type split and top sponsors.
- Instructions: Use for who sponsors a show and how heavily it is monetised. For the full per-sponsor list use advertising/show/sponsors.
- Cost: 25 credits per call
- Capability file: [Show advertising profile](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/show)

Accepted options:
- `id` (string, required): Podcast slug (for example all-in), Particle id, or numeric Apple collection id. Take slugs from responses; a constructed slug returns 404. Example: `<id>`

Response schema example:
```json
{
  "podcast_id": "<podcast_id>",
  "podcast_slug": "<podcast_slug>",
  "total_ads": 0,
  "unique_sponsors": 0,
  "episodes_with_ads": 0,
  "avg_ads_per_episode": 0,
  "read_type_breakdown": {},
  "top_sponsors": []
}
```

### Sponsors of a show

- Capability: `advertising/show/sponsors`
- Description: Per-sponsor activity on the show, most ads first. Network promos are excluded.
- Instructions: Use for every advertiser on one show with counts and recency, or one company's brands on it. Set since and until on shows with extensive ad history to keep the query bounded.
- Cost: 25 credits per call
- Capability file: [Sponsors of a show](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/show/sponsors)

Accepted options:
- `id` (string, required): Podcast slug (for example all-in), Particle id, or numeric Apple collection id. Take slugs from responses; a constructed slug returns 404. Example: `<id>`
- `company_id` (string): Only sponsors linked to this company: a multi-brand advertiser's footprint on one show. Example: `<company_id>`
- `since` (string): Only episodes published on or after this ISO 8601 date or date-time. Example: `<since>`
- `until` (string): Only episodes published before this ISO 8601 date or date-time. A bare date covers that whole UTC day. Example: `<until>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "sponsor": {},
      "ad_count": 0,
      "episode_count": 0,
      "last_seen_at": "<last_seen_at>"
    }
  ]
}
```

### Sponsors a show could pitch

- Capability: `advertising/show/prospects`
- Description: Advertisers that run on the show's related shows but not on it, ranked by venue relatedness, spend there and recency. Empty when the show's related set is not computed yet.
- Instructions: Use as a prospecting list for a show selling its own inventory: who buys shows like mine and has not bought me.
- Cost: 25 credits per call
- Capability file: [Sponsors a show could pitch](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/show/prospects)

Accepted options:
- `id` (string, required): Podcast slug (for example all-in), Particle id, or numeric Apple collection id. Take slugs from responses; a constructed slug returns 404. Example: `<id>`
- `include` (string): Optional sections, comma-separated: via for the related shows that run each sponsor; contacts for up to three people at the sponsor's company likely to own the decision. Example: `<include>`
- `min_score` (number): Only recommendations at or above this score; band is the recommended filter. Example: `1`
- `active_since` (string): Only sponsors whose most recent ad across the related shows is on or after this date. Example: `<active_since>`
- `exclude_top_advertisers` (number): Drop the N most active advertisers corpus-wide, which every list already names. Example: `10`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "sponsor": {},
      "score": 0,
      "band": "<band>",
      "shared_show_count": 0,
      "total_ads": 0,
      "last_ad_at": "<last_ad_at>",
      "company_contested": false,
      "via": [],
      "contacts": []
    }
  ]
}
```

### Publisher advertising profile

- Capability: `advertising/publisher`
- Description: Advertising across a publisher's whole catalogue, returned directly: totals, coverage, read-type split, top sponsors and network buyers.
- Instructions: Use for how a network is monetised and who buys across it. For its shows ranked by ad volume use advertising/publisher/shows.
- Cost: 25 credits per call
- Capability file: [Publisher advertising profile](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/publisher)

Accepted options:
- `id` (string, required): Publisher slug (for example iheartpodcasts, bbc-radio-4) or id, as carried on a podcast record's publisher. Example: `<id>`

Response schema example:
```json
{
  "publisher": {},
  "total_ads": 0,
  "unique_sponsors": 0,
  "episode_reach": 0,
  "ads_per_active_podcast": 0,
  "coverage": {},
  "read_type_breakdown": {},
  "top_sponsors": [],
  "network_buyers_count": 0
}
```

### Shows of a publisher by ad volume

- Capability: `advertising/publisher/shows`
- Description: The publisher's shows ordered by ad count, with monetisation data rather than audience signals.
- Instructions: Use for which of a network's shows carry the advertising. For the same catalogue by popularity use podcasts/publisher/shows.
- Cost: 25 credits per call
- Capability file: [Shows of a publisher by ad volume](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/publisher/shows)

Accepted options:
- `id` (string, required): Publisher slug (for example iheartpodcasts, bbc-radio-4) or id, as carried on a podcast record's publisher. Example: `<id>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "podcast": {},
      "ad_count": 0,
      "unique_sponsors": 0,
      "episodes_with_ads": 0,
      "avg_ads_per_episode": 0,
      "read_type_breakdown": {}
    }
  ]
}
```

### Sponsors of a publisher

- Capability: `advertising/publisher/sponsors`
- Description: Sponsors active across the publisher's catalogue, each with its coverage of that catalogue.
- Instructions: Use for who buys a network, and which of them buy it as a bundle: sort by podcast_coverage with a minimum.
- Cost: 25 credits per call
- Capability file: [Sponsors of a publisher](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/publisher/sponsors)

Accepted options:
- `id` (string, required): Publisher slug (for example iheartpodcasts, bbc-radio-4) or id, as carried on a podcast record's publisher. Example: `<id>`
- `q` (string): Sponsor name, case-insensitive partial match. Example: `<q>`
- `sort` (string): ad_count for volume, podcast_coverage for network buyers, episode_reach for breadth. Example: `ad_count`
- `min_podcast_coverage` (number): Only sponsors on at least this many of the publisher's shows. Example: `10`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "name": "<name>",
      "company": {},
      "ad_count": 0,
      "episode_reach": 0,
      "first_seen_at": "<first_seen_at>",
      "last_seen_at": "<last_seen_at>",
      "podcast_coverage": 0,
      "coverage_share": 0
    }
  ]
}
```

### Ads in an episode

- Capability: `advertising/episode`
- Description: The ad spots detected in the episode: sponsor, linked company, offer, read type and placement. Network promos are excluded.
- Instructions: Use for exactly who advertised in one episode, with the offer and where in the episode the read sits.
- Cost: 25 credits per call
- Capability file: [Ads in an episode](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/episode)

Accepted options:
- `id` (string, required): Episode slug or id. Example: `<id>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "sponsor_name": "<sponsor_name>",
      "sponsor_url": "<sponsor_url>",
      "company": {},
      "product": "<product>",
      "offer_description": "<offer_description>",
      "read_type": "<read_type>",
      "placement_type": "<placement_type>",
      "start_seconds": 0,
      "end_seconds": 0,
      "duration_seconds": 0,
      "podcast": {},
      "created_at": "<created_at>"
    }
  ]
}
```

### Company advertising profile

- Capability: `advertising/company/overview`
- Description: A company's podcast advertising, returned directly: totals, reach, read-type split and recent placements, across every sponsor linked to it.
- Instructions: Use for a company's podcast advertising footprint in one call, across all its brands. For the show list use advertising/company/shows.
- Cost: 25 credits per call
- Capability file: [Company advertising profile](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/company/overview)

Accepted options:
- `id` (string, required): Company slug (for example nvidia), domain (nvidia.com), or id. Example: `<id>`
- `since` (string): Only episodes published on or after this ISO 8601 date or date-time. Example: `<since>`
- `until` (string): Only episodes published before this ISO 8601 date or date-time. A bare date covers that whole UTC day. Example: `<until>`

Response schema example:
```json
{
  "company_id": "<company_id>",
  "slug": "<slug>",
  "total_ads": 0,
  "podcast_reach": 0,
  "episode_reach": 0,
  "read_type_breakdown": {},
  "recent_ads": []
}
```

### Company ad placements

- Capability: `advertising/company/placements`
- Description: Physical ad placements attributed to the company, newest first, each with episode and show context and every company-scoped sponsor attribution.
- Instructions: Use for the feed of a company's actual ad reads, episode by episode, to read or audit them.
- Cost: 25 credits per call
- Capability file: [Company ad placements](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/company/placements)

Accepted options:
- `id` (string, required): Company slug (for example nvidia), domain (nvidia.com), or id. Example: `<id>`
- `sponsor_id` (string): Only placements attributed to this sponsor, keeping co-sponsors in the response. Example: `<sponsor_id>`
- `podcast_id` (string): Only placements on one show. Example: `<podcast_id>`
- `since` (string): Only episodes published on or after this ISO 8601 date or date-time. Example: `<since>`
- `until` (string): Only episodes published before this ISO 8601 date or date-time. A bare date covers that whole UTC day. Example: `<until>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "number": 0,
      "title": "<title>",
      "type": "<type>",
      "description": "<description>",
      "summary": "<summary>",
      "start_seconds": 0,
      "end_seconds": 0,
      "duration_seconds": 0,
      "start_line": 0,
      "end_line": 0,
      "read_type": "<read_type>",
      "audio_url": "<audio_url>",
      "episode": {},
      "placement_type": "<placement_type>",
      "sponsors": []
    }
  ]
}
```

### Shows carrying a company's ads

- Capability: `advertising/company/shows`
- Description: Shows ranked by the company's ad count on them, each with its sponsor breakdown and recent preview segments. Beside data: company-wide sponsors and, when asked, facets.
- Instructions: Use for where a company advertises, ranked by volume, with the reads to sample. Pages are at most 24 rows.
- Cost: 25 credits per call
- Capability file: [Shows carrying a company's ads](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/company/shows)

Accepted options:
- `id` (string, required): Company slug (for example nvidia), domain (nvidia.com), or id. Example: `<id>`
- `sponsor_id` (string): Narrow rows to this sponsor identity while keeping the company constraint. Example: `<sponsor_id>`
- `podcast_id` (string): Only one show. Example: `<podcast_id>`
- `publisher_id` (string): Only one publisher's shows. Example: `<publisher_id>`
- `include_facets` (boolean): Include exhaustive show and network filter metadata; honoured only without a cursor. Example: `false`
- `include_sponsors` (string): Include company-wide sponsor totals. Example: `true`
- `include_previews` (string): Include recent ad segment previews per show. Example: `true`
- `preview_limit` (number): Previews per show when previews are included. Example: `3`
- `since` (string): Only episodes published on or after this ISO 8601 date or date-time. Example: `<since>`
- `until` (string): Only episodes published before this ISO 8601 date or date-time. A bare date covers that whole UTC day. Example: `<until>`
- `limit` (number): Rows per page. This endpoint caps at 24. Example: `24`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "podcast": {},
      "ad_count": 0,
      "episode_count": 0,
      "last_seen_at": "<last_seen_at>",
      "sponsors": [],
      "preview_segments": []
    }
  ]
}
```

### Shows a company could advertise on

- Capability: `advertising/company/prospects`
- Description: Shows the company does not advertise on, ranked by relatedness to the shows it does, anchored on its main venues. Empty for a company with no podcast advertising.
- Instructions: Use as a buy-side prospect list: where an advertiser could go next, with the shows it already buys as the reason.
- Cost: 25 credits per call
- Capability file: [Shows a company could advertise on](https://firecrawl.dev/alexandria/agents/providers/particle/advertising/company/prospects)

Accepted options:
- `id` (string, required): Company slug (for example nvidia), domain (nvidia.com), or id. Example: `<id>`
- `include` (string): Pass via to attach, per recommendation, the company's own shows that led to it. Example: `<include>`
- `min_score` (number): Only recommendations at or above this score, within the 200 strongest. Example: `1`
- `language` (string): Only shows in this ISO 639-1 language. Example: `<language>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "podcast": {},
      "score": 0,
      "band": "<band>",
      "via": []
    }
  ]
}
```

### Chart entries

- Capability: `rankings/charts`
- Description: Entries of the live snapshot for one chart slot, rank ascending; charts run to 200. With podcast_id, that show's current appearances instead.
- Instructions: Use for today's chart: the US Apple overall top podcasts with no arguments, or a country and category. Use rankings/categories and rankings/countries for the valid slugs.
- Cost: 25 credits per call
- Capability file: [Chart entries](https://firecrawl.dev/alexandria/agents/providers/particle/rankings/charts)

Accepted options:
- `source` (string): Ranking source platform. Example: `apple`
- `chart_type` (string): Chart variant within the source. Only top_podcasts exists today. Example: `top_podcasts`
- `country` (string): ISO 3166-1 alpha-2 country code, for example us, gb, jp. Case-insensitive. Example: `us`
- `category_slug` (string): Category slug, for example comedy or business. Omit for the overall chart. Example: `<category_slug>`
- `podcast_id` (string): Only this show's current chart appearances across the matching slots. Example: `<podcast_id>`
- `min_rank` (number): Lowest-numbered rank to include. Example: `10`
- `max_rank` (number): Highest-numbered rank to include. Example: `10`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "rank": 0,
      "previous_rank": 0,
      "source": "<source>",
      "chart_type": "<chart_type>",
      "country": "<country>",
      "category": {},
      "show": {},
      "podcast": {},
      "external_id": "<external_id>",
      "external_url": "<external_url>",
      "captured_at": "<captured_at>",
      "is_current": false,
      "chart_total": 0,
      "reach_pct": 0,
      "growth_indicator": "<growth_indicator>",
      "weekly_avg_downloads": 0,
      "view_count": 0,
      "channel_subscriber_count": 0,
      "source_updated_at": "<source_updated_at>"
    }
  ]
}
```

### Ranking categories

- Capability: `rankings/categories`
- Description: Every category with current chart data, with the parent for Apple sub-categories. All of them when limit is omitted.
- Instructions: Use to find the category_slug the chart capabilities take.
- Cost: 15 credits per call
- Capability file: [Ranking categories](https://firecrawl.dev/alexandria/agents/providers/particle/rankings/categories)

Accepted options:
- `source` (string): Ranking source platform. Example: `apple`
- `limit` (number): Maximum records to return. Omit for all of them. Example: `10`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "slug": "<slug>",
      "name": "<name>",
      "parent_slug": "<parent_slug>",
      "external_id": "<external_id>",
      "current_chart_count": 0,
      "sources": []
    }
  ]
}
```

### Ranking countries

- Capability: `rankings/countries`
- Description: Every country with current chart data. All of them when limit is omitted.
- Instructions: Use to find the country codes the chart capabilities take.
- Cost: 15 credits per call
- Capability file: [Ranking countries](https://firecrawl.dev/alexandria/agents/providers/particle/rankings/countries)

Accepted options:
- `source` (string): Ranking source platform. Example: `apple`
- `limit` (number): Maximum records to return. Omit for all of them. Example: `10`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "code": "<code>",
      "name": "<name>",
      "current_chart_count": 0,
      "sources": []
    }
  ]
}
```

### Ranking sources

- Capability: `rankings/sources`
- Description: Each source and chart type pair available, with row counts and freshness of the live snapshot.
- Instructions: Use to check which chart sources exist and how fresh the snapshot is.
- Cost: 15 credits per call
- Capability file: [Ranking sources](https://firecrawl.dev/alexandria/agents/providers/particle/rankings/sources)

Accepted options:
- `limit` (number): Maximum records to return. Omit for all of them. Example: `10`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "source": "<source>",
      "chart_type": "<chart_type>",
      "current_row_count": 0,
      "latest_captured_at": "<latest_captured_at>"
    }
  ]
}
```

### Chart slot history

- Capability: `rankings/history`
- Description: Historical snapshots of one chart slot, most recent first.
- Instructions: Use for how a chart looked on past days, or how one show moved within it. For one show across every chart use rankings/show/history.
- Cost: 25 credits per call
- Capability file: [Chart slot history](https://firecrawl.dev/alexandria/agents/providers/particle/rankings/history)

Accepted options:
- `source` (string): Ranking source platform. Example: `apple`
- `chart_type` (string): Chart variant within the source. Only top_podcasts exists today. Example: `top_podcasts`
- `country` (string): ISO 3166-1 alpha-2 country code, for example us, gb, jp. Case-insensitive. Example: `us`
- `category_slug` (string): Category slug, for example comedy or business. Omit for the overall chart. Example: `<category_slug>`
- `podcast_id` (string): Only one show within the slot. Example: `<podcast_id>`
- `since` (string): Lower bound on captured_at, ISO 8601. Example: `<since>`
- `until` (string): Upper bound on captured_at, ISO 8601. Example: `<until>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "rank": 0,
      "previous_rank": 0,
      "source": "<source>",
      "chart_type": "<chart_type>",
      "country": "<country>",
      "category": {},
      "show": {},
      "podcast": {},
      "external_id": "<external_id>",
      "external_url": "<external_url>",
      "captured_at": "<captured_at>",
      "is_current": false,
      "chart_total": 0,
      "reach_pct": 0,
      "growth_indicator": "<growth_indicator>",
      "weekly_avg_downloads": 0,
      "view_count": 0,
      "channel_subscriber_count": 0,
      "source_updated_at": "<source_updated_at>"
    }
  ]
}
```

### Chart movers

- Capability: `rankings/movers`
- Description: Entries whose rank changed between the live snapshot and the comparison snapshot. Stable rows are excluded.
- Instructions: Use for what debuted, climbed, fell or dropped off a chart since yesterday or over a window.
- Cost: 25 credits per call
- Capability file: [Chart movers](https://firecrawl.dev/alexandria/agents/providers/particle/rankings/movers)

Accepted options:
- `source` (string): Ranking source platform. Example: `apple`
- `chart_type` (string): Chart variant within the source. Only top_podcasts exists today. Example: `top_podcasts`
- `country` (string): ISO 3166-1 alpha-2 country code, for example us, gb, jp. Case-insensitive. Example: `us`
- `category_slug` (string): Category slug, for example comedy or business. Omit for the overall chart. Example: `<category_slug>`
- `window_days` (number): Compare against the snapshot this many days ago. Example: `1`
- `change` (string): Which changes: up, down, new debuts, exits, or all. Example: `all`
- `limit` (number): Maximum records to return. Example: `25`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "rank": 0,
      "previous_rank": 0,
      "source": "<source>",
      "chart_type": "<chart_type>",
      "country": "<country>",
      "category": {},
      "show": {},
      "podcast": {},
      "external_id": "<external_id>",
      "external_url": "<external_url>",
      "captured_at": "<captured_at>",
      "is_current": false,
      "chart_total": 0,
      "reach_pct": 0,
      "growth_indicator": "<growth_indicator>",
      "weekly_avg_downloads": 0,
      "view_count": 0,
      "channel_subscriber_count": 0,
      "source_updated_at": "<source_updated_at>",
      "change": "<change>",
      "delta": 0,
      "previous_snapshot": {}
    }
  ]
}
```

### Current rankings of a show

- Capability: `rankings/show`
- Description: Every live chart appearance of the show across sources, countries and categories. All of them when limit is omitted.
- Instructions: Use for where a show charts today, everywhere it charts. For a one-number summary use rankings/show/summary.
- Cost: 25 credits per call
- Capability file: [Current rankings of a show](https://firecrawl.dev/alexandria/agents/providers/particle/rankings/show)

Accepted options:
- `id` (string, required): Podcast slug (for example all-in), Particle id, or numeric Apple collection id. Take slugs from responses; a constructed slug returns 404. Example: `<id>`
- `limit` (number): Maximum records to return. Omit for all of them. Example: `10`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "rank": 0,
      "previous_rank": 0,
      "source": "<source>",
      "chart_type": "<chart_type>",
      "country": "<country>",
      "category": {},
      "show": {},
      "podcast": {},
      "external_id": "<external_id>",
      "external_url": "<external_url>",
      "captured_at": "<captured_at>",
      "is_current": false,
      "chart_total": 0,
      "reach_pct": 0,
      "growth_indicator": "<growth_indicator>",
      "weekly_avg_downloads": 0,
      "view_count": 0,
      "channel_subscriber_count": 0,
      "source_updated_at": "<source_updated_at>"
    }
  ]
}
```

### Ranking history of a show

- Capability: `rankings/show/history`
- Description: The show's historical rank entries across chart slots, optionally narrowed to one source, country, category or date range.
- Instructions: Use for a show's chart trajectory over time.
- Cost: 25 credits per call
- Capability file: [Ranking history of a show](https://firecrawl.dev/alexandria/agents/providers/particle/rankings/show/history)

Accepted options:
- `id` (string, required): Podcast slug (for example all-in), Particle id, or numeric Apple collection id. Take slugs from responses; a constructed slug returns 404. Example: `<id>`
- `source` (string): Ranking source platform. Example: `apple`
- `chart_type` (string): Chart variant within the source. Only top_podcasts exists today. Example: `top_podcasts`
- `country` (string): ISO 3166-1 alpha-2 country code, for example us, gb, jp. Case-insensitive. Example: `<country>`
- `category_slug` (string): Category slug, for example comedy or business. Omit for the overall chart. Example: `<category_slug>`
- `since` (string): Lower bound on captured_at, ISO 8601. Example: `<since>`
- `until` (string): Upper bound on captured_at, ISO 8601. Example: `<until>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "rank": 0,
      "previous_rank": 0,
      "source": "<source>",
      "chart_type": "<chart_type>",
      "country": "<country>",
      "category": {},
      "show": {},
      "podcast": {},
      "external_id": "<external_id>",
      "external_url": "<external_url>",
      "captured_at": "<captured_at>",
      "is_current": false,
      "chart_total": 0,
      "reach_pct": 0,
      "growth_indicator": "<growth_indicator>",
      "weekly_avg_downloads": 0,
      "view_count": 0,
      "channel_subscriber_count": 0,
      "source_updated_at": "<source_updated_at>"
    }
  ]
}
```

### Chart presence summary

- Capability: `rankings/show/summary`
- Description: The show's chart presence in one record: counts of slots, sources, countries and categories it appears on, its single best rank, and a per-source breakdown.
- Instructions: Use for how big a show is on the charts in one call: its best rank and how widely it charts.
- Cost: 25 credits per call
- Capability file: [Chart presence summary](https://firecrawl.dev/alexandria/agents/providers/particle/rankings/show/summary)

Accepted options:
- `id` (string, required): Podcast slug (for example all-in), Particle id, or numeric Apple collection id. Take slugs from responses; a constructed slug returns 404. Example: `<id>`

Response schema example:
```json
{
  "podcast": {},
  "chart_count": 0,
  "source_count": 0,
  "country_count": 0,
  "category_count": 0,
  "best_rank": {},
  "appearances_by_source": []
}
```

### Show bias analysis

- Capability: `bias/show`
- Description: The show's most recent political bias analysis, returned directly: the result bucket, confidence, the political framework, the reasoning, the transcript and web evidence, and the sample episodes. 404 when not yet analysed.
- Instructions: Use for where a show sits politically and why, with the evidence to quote. The bucket alone rides on every show record as bias.
- Cost: 25 credits per call
- Capability file: [Show bias analysis](https://firecrawl.dev/alexandria/agents/providers/particle/bias/show)

Accepted options:
- `id` (string, required): Podcast slug (for example all-in), Particle id, or numeric Apple collection id. Take slugs from responses; a constructed slug returns 404. Example: `<id>`

Response schema example:
```json
{
  "result": "<result>",
  "confidence": "<confidence>",
  "political_context": "<political_context>",
  "political_context_detail": "<political_context_detail>",
  "reasoning": "<reasoning>",
  "transcript_evidence": "<transcript_evidence>",
  "web_research_evidence": "<web_research_evidence>",
  "sample_episode_ids": [],
  "episodes_analyzed": 0,
  "evaluated_at": "<evaluated_at>"
}
```

### Publisher bias profile

- Capability: `bias/publisher`
- Description: Bias rolled up across a publisher's analysed shows, returned directly: coverage, political share, average lean on a -3 to +3 scale, lean diversity, and the bucket and regional distributions.
- Instructions: Use for a network's political profile as a whole: how political its catalogue is and which way it leans.
- Cost: 25 credits per call
- Capability file: [Publisher bias profile](https://firecrawl.dev/alexandria/agents/providers/particle/bias/publisher)

Accepted options:
- `id` (string, required): Publisher slug (for example iheartpodcasts, bbc-radio-4) or id, as carried on a podcast record's publisher. Example: `<id>`

Response schema example:
```json
{
  "publisher": {},
  "coverage": {},
  "political_content": {},
  "lean": {},
  "distributions": {},
  "last_evaluated_at": "<last_evaluated_at>"
}
```

### Analysed shows of a publisher

- Capability: `bias/publisher/shows`
- Description: The publisher's analysed shows with their latest bias analysis attached.
- Instructions: Use to list a network's shows by political lean, or only the ones in a bucket.
- Cost: 25 credits per call
- Capability file: [Analysed shows of a publisher](https://firecrawl.dev/alexandria/agents/providers/particle/bias/publisher/shows)

Accepted options:
- `id` (string, required): Publisher slug (for example iheartpodcasts, bbc-radio-4) or id, as carried on a podcast record's publisher. Example: `<id>`
- `bias` (string): Only these buckets, comma-separated to match any, for example LEFT,LEANS_LEFT. Example: `<bias>`
- `political_context` (string): Restrict the corpus to one political framework before aggregating. Example: `US`
- `include_non_political` (string): Include shows rated NOT_POLITICAL. Set false for political shows only. Example: `true`
- `sort` (string): lean_score on the -3 to +3 scale, evaluated_at by recency, or name. Example: `lean_score`
- `order` (string): Sort direction. Example: `desc`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "podcast": {},
      "bias": {}
    }
  ]
}
```

### Publisher bias leaderboard

- Capability: `bias/publishers/leaderboard`
- Description: Publishers ranked by the chosen bias metric, each with its coverage, political share and lean.
- Instructions: Use for which networks lean furthest left or right, are most political, or most ideologically diverse.
- Cost: 25 credits per call
- Capability file: [Publisher bias leaderboard](https://firecrawl.dev/alexandria/agents/providers/particle/bias/publishers/leaderboard)

Accepted options:
- `metric` (string, required): most_left_leaning and most_right_leaning rank by average lean; most_political by share of political shows; most_diverse and most_monolithic by spread of lean; most_analyzed by coverage. Example: `most_left_leaning`
- `political_context` (string): Restrict the corpus to one political framework before aggregating. Example: `US`
- `min_analyzed_podcasts` (number): Only publishers with at least this many analysed shows. Example: `5`
- `min_political_podcasts` (number): Only publishers with at least this many political shows; applies to score and diversity metrics. Example: `5`
- `since` (string): Only analyses evaluated on or after this RFC 3339 timestamp. Example: `<since>`
- `until` (string): Only analyses evaluated before this RFC 3339 timestamp. Example: `<until>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "rank": 0,
      "publisher": {},
      "coverage": {},
      "political_content": {},
      "lean": {},
      "last_evaluated_at": "<last_evaluated_at>"
    }
  ]
}
```

### Publishers with shows in a bias bucket

- Capability: `bias/publishers-by-bucket`
- Description: Publishers whose analysed catalogue has shows in the bucket, ranked by count or share.
- Instructions: Use for which publishers carry the most shows of one lean: the flip of a publisher's own bias profile.
- Cost: 25 credits per call
- Capability file: [Publishers with shows in a bias bucket](https://firecrawl.dev/alexandria/agents/providers/particle/bias/publishers-by-bucket)

Accepted options:
- `result` (string, required): The bias bucket: one of NOT_POLITICAL, EXTREME_LEFT, LEFT, LEANS_LEFT, CENTER, LEANS_RIGHT, RIGHT, EXTREME_RIGHT. Example: `NOT_POLITICAL`
- `political_context` (string): Restrict the corpus to one political framework before aggregating. Example: `US`
- `min_count` (number): Only publishers with at least this many shows in the bucket. Example: `1`
- `sort` (string): count ranks by shows in the bucket; share by their fraction of the analysed catalogue. Example: `count`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "publisher": {},
      "podcasts_in_bucket": 0,
      "analyzed_podcasts": 0,
      "podcast_count": 0,
      "bucket_share": 0,
      "sample_podcast_ids": []
    }
  ]
}
```

### Show suitability assessment

- Capability: `suitability/show`
- Description: The show's latest brand-suitability assessment, returned directly: overall tier, per-category prevalence and treatment across the 12 categories, evidence excerpts and methodology. 404 when not yet analysed.
- Instructions: Use for whether a show is safe to advertise on and in which categories it is exposed, with the evidence. The tier alone rides on every show record as suitability_tier.
- Cost: 25 credits per call
- Capability file: [Show suitability assessment](https://firecrawl.dev/alexandria/agents/providers/particle/suitability/show)

Accepted options:
- `id` (string, required): Podcast slug (for example all-in), Particle id, or numeric Apple collection id. Take slugs from responses; a constructed slug returns 404. Example: `<id>`
- `include` (string): Optional sections, comma-separated: trend for the comparison against the prior assessment, history for the list of prior assessments. Example: `<include>`

Response schema example:
```json
{
  "overall_tier": "<overall_tier>",
  "confidence": "<confidence>",
  "summary": "<summary>",
  "categories": [],
  "methodology": "<methodology>",
  "episodes_analyzed": 0,
  "sample_episode_ids": [],
  "sample_window_start_at": "<sample_window_start_at>",
  "sample_window_end_at": "<sample_window_end_at>",
  "evaluated_at": "<evaluated_at>",
  "trend": {},
  "history": []
}
```

### Guest suitability exposure

- Capability: `suitability/guest`
- Description: The distribution of suitability tiers across the shows a guest has appeared on, lifetime and in the last 90 days, plus the categories most often flagged there. A measure of exposure, not a verdict on the person.
- Instructions: Use for what kind of shows a guest tends to appear on, in brand-safety terms.
- Cost: 25 credits per call
- Capability file: [Guest suitability exposure](https://firecrawl.dev/alexandria/agents/providers/particle/suitability/guest)

Accepted options:
- `id` (string, required): Person slug (recommended), the person's knowledge-graph entity slug, or the encoded person id. Example: `<id>`

Response schema example:
```json
{
  "lifetime": {},
  "recent_90d": {},
  "top_categories": [],
  "notes": "<notes>"
}
```

### Publisher suitability profile

- Capability: `suitability/publisher`
- Description: Suitability rolled up across a publisher's analysed shows, returned directly: tier composition, confidence distribution, exposure per category and the top concerns, with a coverage block saying how representative it is.
- Instructions: Use for how brand-safe a network's catalogue is as a whole and where its exposure sits.
- Cost: 25 credits per call
- Capability file: [Publisher suitability profile](https://firecrawl.dev/alexandria/agents/providers/particle/suitability/publisher)

Accepted options:
- `id` (string, required): Publisher slug (for example iheartpodcasts, bbc-radio-4) or id, as carried on a podcast record's publisher. Example: `<id>`

Response schema example:
```json
{
  "publisher": {},
  "tier_breakdown": {},
  "confidence_breakdown": {},
  "category_breakdown": [],
  "top_concerns": [],
  "coverage": {},
  "last_evaluated_at": "<last_evaluated_at>"
}
```

### Assessed shows of a publisher

- Capability: `suitability/publisher/shows`
- Description: The publisher's assessed shows with their latest tier, confidence and flagged categories. Per-category reasoning is left to suitability/show.
- Instructions: Use to build an inclusion or exclusion list inside one network: its shows by tier, or the ones exposed in a category.
- Cost: 25 credits per call
- Capability file: [Assessed shows of a publisher](https://firecrawl.dev/alexandria/agents/providers/particle/suitability/publisher/shows)

Accepted options:
- `id` (string, required): Publisher slug (for example iheartpodcasts, bbc-radio-4) or id, as carried on a podcast record's publisher. Example: `<id>`
- `tier` (string): Only these tiers, comma-separated to match any, for example UNSAFE,SENSITIVE. Example: `<tier>`
- `category` (string): Only shows exposed in this category. Example: `adult_sexual`
- `min_prevalence` (string): With category: only count exposure at or above this prevalence. INCIDENTAL is any non-NONE prevalence. Example: `INCIDENTAL`
- `treatment` (string): With category: only count exposure whose treatment equals this value. Example: `DOCUMENTARY`
- `sort` (string): risk_desc puts the riskiest first, risk_asc the safest, recently_evaluated the newest assessment. Example: `risk_desc`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "podcast": {},
      "overall_tier": "<overall_tier>",
      "confidence": "<confidence>",
      "flagged_categories": [],
      "evaluated_at": "<evaluated_at>"
    }
  ]
}
```

### Publisher suitability leaderboard

- Capability: `suitability/publishers/leaderboard`
- Description: Publishers ranked by suitability composition, each with its full tier breakdown and the value it was ranked by.
- Instructions: Use for the safest or riskiest networks to buy, or the most broadly placeable.
- Cost: 25 credits per call
- Capability file: [Publisher suitability leaderboard](https://firecrawl.dev/alexandria/agents/providers/particle/suitability/publishers/leaderboard)

Accepted options:
- `metric` (string): safest by SAFE share, riskiest by UNSAFE share, most_placeable by SAFE plus LIMITED share, most_analyzed by analysed count. Example: `safest`
- `min_analyzed_podcasts` (number): Only publishers with at least this many analysed shows. Example: `5`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "rank": 0,
      "publisher": {},
      "metric_value": 0,
      "tier_breakdown": {},
      "coverage": {}
    }
  ]
}
```

### Publishers by exposure to a category

- Capability: `suitability/category-publishers`
- Description: Publishers ranked by catalogue exposure to one category, each with prevalence and treatment breakdowns and up to three example shows.
- Instructions: Use to pivot on one category for a regulated or family brand: which networks carry the most, or least, alcohol, weapons, adult or hate-speech exposure.
- Cost: 25 credits per call
- Capability file: [Publishers by exposure to a category](https://firecrawl.dev/alexandria/agents/providers/particle/suitability/category-publishers)

Accepted options:
- `code` (string, required): The brand-safety category to pivot on. Example: `adult_sexual`
- `direction` (string): most_exposed ranks by exposure share descending; least_exposed inverts it. Example: `most_exposed`
- `min_prevalence` (string): With category: only count exposure at or above this prevalence. INCIDENTAL is any non-NONE prevalence. Example: `INCIDENTAL`
- `treatment` (string): With category: only count exposure whose treatment equals this value. Example: `DOCUMENTARY`
- `min_analyzed_podcasts` (number): Exclude publishers with fewer analysed shows than this. Example: `5`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "rank": 0,
      "publisher": {},
      "category_code": "<category_code>",
      "description": "<description>",
      "exposed_count": 0,
      "high_risk_count": 0,
      "exposure_share": 0,
      "prevalence_breakdown": {},
      "treatment_breakdown": {},
      "coverage": {},
      "example_podcasts": []
    }
  ]
}
```

### Entity charts

- Capability: `charts/list`
- Description: Every entity chart with the headline state of its current edition: date, whether narratives are written, what sits at rank 1, and the windows it publishes.
- Instructions: Use to see which charts exist (all, tv-series, movies, video-games, nfl, nba, guests and so on) and who leads each, before fetching one with charts/chart.
- Cost: 50 credits per call
- Capability file: [Entity charts](https://firecrawl.dev/alexandria/agents/providers/particle/charts/list)

Accepted options:
- `window` (string): Measurement window of the edition. Composite charts (all, all-entertainment, all-sports) publish 7d only. Example: `7d`

Response schema example:
```json
{
  "data": [
    {
      "category_slug": "<category_slug>",
      "category_name": "<category_name>",
      "group": "<group>",
      "source": "<source>",
      "window": "<window>",
      "windows": [],
      "edition_date": "<edition_date>",
      "status": "<status>",
      "leader": {},
      "computed_at": "<computed_at>",
      "enriched_at": "<enriched_at>",
      "caveats": []
    }
  ]
}
```

### Entity chart edition

- Capability: `charts/chart`
- Description: The current edition of one chart under entries, each with its movement since the previous edition. Beside entries: category, edition date, window, source, status, methodology version and caveats. Mention charts rank by distinct podcasts mentioning the subject; the all chart blends reach with acceleration.
- Instructions: Use for what podcasts are talking about most this week in one domain: the most-mentioned shows, films, games, teams or players, or the most-booked guests, with movement since last edition.
- Cost: 50 credits per call
- Capability file: [Entity chart edition](https://firecrawl.dev/alexandria/agents/providers/particle/charts/chart)

Accepted options:
- `category` (string, required): Chart identifier from charts/list, for example all, tv-series, movies, video-games, guests. Example: `<category>`
- `window` (string): Measurement window of the edition. Composite charts (all, all-entertainment, all-sports) publish 7d only. Example: `7d`
- `limit` (number): Ranked entries to return from rank 1 down. Example: `10`
- `sort` (string): rank as published, or acceleration to reorder by each entry's growth multiple, fastest first. Example: `rank`
- `include` (string): Optional sections, comma-separated: timeseries for each entry's daily history, driven_by for the entry whose coverage drives a derivative one. Example: `<include>`

Response schema example:
```json
{
  "entries": [
    {
      "rank": 0,
      "previous_rank": 0,
      "rank_change": 0,
      "movement": "<movement>",
      "subject": {},
      "podcast_count": 0,
      "episode_count": 0,
      "mention_count": 0,
      "previous_podcast_count": 0,
      "previous_episode_count": 0,
      "previous_mention_count": 0,
      "accel_multiple": 0,
      "breaking": false,
      "why": {},
      "signals": {},
      "appearances": [],
      "highlight_clip": {},
      "driven_by": {},
      "timeseries": {},
      "tombstone": false,
      "caveats": []
    }
  ]
}
```

### Entity search

- Capability: `entities/search`
- Description: Best matches by relevance, each with a match_quality telling an exact identification from a fuzzy guess and counts of podcast episodes and news articles naming it. The matched record sits under person, company or knowledge_graph_entity according to type.
- Instructions: Use to turn what someone typed into a specific person, company or entity and its slug, before asking what was said about it with podcasts/mentions or filtering episodes by it. Searching episodes directly is better when the topic, not a name, is the question.
- Cost: 5 credits per call
- Capability file: [Entity search](https://firecrawl.dev/alexandria/agents/providers/particle/entities/search)

Accepted options:
- `q` (string, required): A name, partial name, nickname, stock ticker, @handle or website domain: sam altman, coca cola, AAPL, @sama, apple.com. Example: `<q>`
- `type` (string): Restrict to one kind. Omit to search people, companies and knowledge-graph entities together. Example: `person`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "type": "<type>",
      "match_quality": "<match_quality>",
      "mentions": {},
      "person": {},
      "company": {},
      "knowledge_graph_entity": {},
      "social_links": []
    }
  ]
}
```

### Entity record

- Capability: `entities/mentions`
- Description: One knowledge-graph entity, returned directly: name, slug, type, description, and the linked company or person record.
- Instructions: Use to resolve an entity slug to its record and its linked company or person. For where it was mentioned use podcasts/mentions (dialogue lines) or podcasts/episodes/list with entity_id (episodes).
- Cost: 5 credits per call
- Capability file: [Entity record](https://firecrawl.dev/alexandria/agents/providers/particle/entities/mentions)

Accepted options:
- `id` (string, required): Entity slug (sam-altman, apple) or id. A person slug also resolves, to that person's linked entity. Example: `<id>`

Response schema example:
```json
{
  "id": "<id>",
  "slug": "<slug>",
  "name": "<name>",
  "description": "<description>",
  "type": {},
  "company": {},
  "person": {},
  "image_url": "<image_url>",
  "wikipedia_url": "<wikipedia_url>"
}
```

### Entity directory

- Capability: `entities/list`
- Description: Entities ranked by the number of distinct episodes featuring them, filtered by show or type, or exactly the ids asked for.
- Instructions: Use for the most-discussed entities overall, in one show, or of one kind, or to fetch several entities by slug at once. Takes no free text; for a name use entities/search.
- Cost: 5 credits per call
- Capability file: [Entity directory](https://firecrawl.dev/alexandria/agents/providers/particle/entities/list)

Accepted options:
- `ids` (string): Bulk get: comma-separated entity slugs or ids, up to 100. Other filters and paging are ignored when set; unresolved refs are omitted. Example: `<ids>`
- `podcast_id` (string): Only entities appearing in this show, by slug, id or Apple collection id. Example: `<podcast_id>`
- `type` (string): Only this entity category slug, from entities/types: person, company, movie, sports-team. Example: `<type>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "slug": "<slug>",
      "name": "<name>",
      "description": "<description>",
      "type": {},
      "company": {},
      "person": {},
      "image_url": "<image_url>",
      "wikipedia_url": "<wikipedia_url>"
    }
  ]
}
```

### Entity lookup by external identifier

- Capability: `entities/lookup`
- Description: One result per identifier passed, echoing it with the people and companies that carry it. An identifier is not unique, so matches is a list and match_count its size; unresolved identifiers have an empty matches.
- Instructions: Use when you hold a LinkedIn slug, a handle, a domain, a ticker or a CIK and need the Particle person or company: the reverse of the external-links capabilities.
- Cost: 5 credits per call
- Capability file: [Entity lookup by external identifier](https://firecrawl.dev/alexandria/agents/providers/particle/entities/lookup)

Accepted options:
- `identifier` (string, required): One or more external identifiers, comma-separated, up to 100: LinkedIn slugs, social handles, domains, tickers, SEC CIKs, Wikidata QIDs. A profile URL works in place of a bare handle. Example: `<identifier>`
- `platform` (string): Restrict to one platform: any slug the external-links capabilities report, or the company namespaces domain, ticker, sec and wikidata. Omit to match on any platform. Example: `<platform>`
- `type` (string): Restrict to people or companies. Example: `person`

Response schema example:
```json
{
  "results": [
    {
      "identifier": "<identifier>",
      "match_count": 0,
      "matches": [],
      "platforms": []
    }
  ]
}
```

### Types

- Capability: `entities/types`
- Description: Every entity category, as the slugs entities/list and the entity_type filter on episode search accept. All of them when limit is omitted.
- Instructions: Use to see what the type filter on entities/list can take. Skip it when listing without a filter.
- Cost: 15 credits per call
- Capability file: [Types](https://firecrawl.dev/alexandria/agents/providers/particle/entities/types)

Accepted options:
- `limit` (number): Maximum records to return. Omit for all of them. Example: `10`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "slug": "<slug>",
      "name": "<name>"
    }
  ]
}
```

### Topic profile

- Capability: `entities/topic`
- Description: One topic, returned directly, with its breadcrumb ancestors and its top direct children by prominence. Children are capped; entities/topics with parent_id pages beyond the cap.
- Instructions: Use to place a topic in the taxonomy and see its neighbours. For the shows in it use podcasts/list with topic_id; for episodes, podcasts/episodes/list. This returns classification, not passages.
- Cost: 5 credits per call
- Capability file: [Topic profile](https://firecrawl.dev/alexandria/agents/providers/particle/entities/topic)

Accepted options:
- `id` (string, required): Topic id, ancestry slug (technology/artificial-intelligence) or path hash. Example: `<id>`

Response schema example:
```json
{
  "id": "<id>",
  "slug": "<slug>",
  "name": "<name>",
  "ancestry": "<ancestry>",
  "ancestry_path": "<ancestry_path>",
  "episode_count": 0,
  "ancestors": [],
  "children": [],
  "total_children": 0
}
```

### Topics

- Capability: `entities/topics`
- Description: The topic tree one level at a time, as the ids the topic_id filters accept.
- Instructions: Use to find the topic_id that podcasts/search, podcasts/list and the guest capabilities filter on. Walk down from the roots by passing parent_id.
- Cost: 15 credits per call
- Capability file: [Topics](https://firecrawl.dev/alexandria/agents/providers/particle/entities/topics)

Accepted options:
- `parent_id` (string): Only children of this topic, by id, ancestry slug or path hash. Omit for the top-level roots. Example: `<parent_id>`
- `ancestry_path` (string): Only the topic with exactly this path hash. Example: `<ancestry_path>`
- `ancestry_path_prefix` (string): Only descendants under this path prefix. Example: `<ancestry_path_prefix>`
- `limit` (number): Maximum records to return. Example: `25`
- `cursor` (string): Opaque cursor from a previous page. Omit for the first page; send the same filters with it. Example: `<cursor>`

Response schema example:
```json
{
  "data": [
    {
      "id": "<id>",
      "slug": "<slug>",
      "name": "<name>",
      "ancestry": "<ancestry>",
      "ancestry_path": "<ancestry_path>",
      "episode_count": 0
    }
  ]
}
```