> ## Documentation Index
> Fetch the complete documentation index at: https://docs.particle.pro/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Trace one person across podcasts, dialogue, and companies in five minutes.
export const DashboardLink = ({children}) => {
return {children};
};
In the next five minutes you'll find a person in the knowledge graph, read every line of dialogue where they're discussed across the podcast catalog, find the episodes where they were actually a guest, pull the highlight clips, search the catalog by topic, then pivot to the companies they're connected to and the podcasts those companies sponsor — all with real, current data.
Every example below was run against `https://api.particle.pro` while writing this page. Paste them with your own key and you'll see the same kind of results.
## Get an API key
1. Sign up or log in at the API Dashboard
2. Create an organization and project
3. Open the project's **API Keys** section
4. Click **Create API Key** and copy the key — it won't be shown again
Set it as an environment variable so the rest of this guide reads cleanly:
```bash theme={"dark"}
export PARTICLE_API_KEY="pk_…"
```
All endpoints accept the key in the `X-API-Key` header. See [API reference → Introduction](/api-reference/introduction) for the alternate `Authorization: Bearer` form.
## 1. Find a person
Start with a name search. `/v1/entities?q=…` matches against the knowledge graph and returns ranked results with a slug for each — the slug is the handle you'll pass to every other entity-aware endpoint.
```bash curl theme={"dark"}
curl "https://api.particle.pro/v1/entities?q=altman&limit=3" \
-H "X-API-Key: $PARTICLE_API_KEY"
```
```js JavaScript theme={"dark"}
const res = await fetch(
"https://api.particle.pro/v1/entities?q=altman&limit=3",
{ headers: { "X-API-Key": process.env.PARTICLE_API_KEY } },
);
const { data } = await res.json();
```
```python Python theme={"dark"}
import os, httpx
res = httpx.get(
"https://api.particle.pro/v1/entities",
params={"q": "altman", "limit": 3},
headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]},
)
data = res.json()["data"]
```
```jsonc Response theme={"dark"}
{
"data": [
{
"id": "17PzxG1t12xzno",
"slug": "sam-altman",
"name": "Sam Altman",
"description": "CEO of OpenAI",
"wikipedia_url": "https://en.wikipedia.org/wiki/Sam_Altman",
"image_url": "https://cdn.particle.pro/url/media/kge/m/02kx06l/…"
},
{
"id": "44RuOByIGYS",
"slug": "robert-altman",
"name": "Robert Altman",
"description": "American filmmaker",
"wikipedia_url": "https://en.wikipedia.org/wiki/Robert_Altman"
}
// …
],
"has_more": true,
"cursor": "…"
}
```
The first result is the one we want — `sam-altman`. Once you know an entity's slug, you can also fetch it directly with `GET /v1/entities/sam-altman` to get the full record. Every endpoint that takes an `{id}` accepts the canonical ID *or* the slug — pick whichever you have. We'll use `sam-altman` for the rest of the tutorial.
## 2. Read every line said about them
Jump straight from "this is the entity" to "here is every line of dialogue across the podcast catalog where they're mentioned" — grouped by episode, recency-ordered, with the surrounding lines for context and the matched line flagged.
```bash curl theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/mentions?entity_id=sam-altman&limit=2" \
-H "X-API-Key: $PARTICLE_API_KEY"
```
```js JavaScript theme={"dark"}
const res = await fetch(
"https://api.particle.pro/v1/podcasts/mentions?entity_id=sam-altman&limit=2",
{ headers: { "X-API-Key": process.env.PARTICLE_API_KEY } },
);
const { data } = await res.json();
```
```python Python theme={"dark"}
res = httpx.get(
"https://api.particle.pro/v1/podcasts/mentions",
params={"entity_id": "sam-altman", "limit": 2},
headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]},
)
data = res.json()["data"]
```
```jsonc Response (truncated) theme={"dark"}
{
"data": [
{
"episode": {
"id": "1Se2PVIwRNIhRIcv5FgAPX",
"title": "Evening Wire: Comey Indicted Again & Fauci Advisor Charged in COVID Cover-Up | 4.28.26",
"published_at": "2026-04-28T21:30:00Z",
"podcast": { "title": "Morning Wire", "slug": "morning-wire" }
},
"mention_count": 1,
"mention_variants": ["Sam Altman"],
"windows": [
{
"segment": { "type": "TOPIC_DISCUSSION", "title": "OpenAI Growth Miss and IPO Concerns" },
"start_seconds": 436.05,
"end_seconds": 470.41,
"lines": [
{
"speaker": "Andy Valdez",
"role": "CORRESPONDENT",
"start_seconds": 452.77,
"end_seconds": 460.21,
"text": "As CEO Sam Altman continues to seek an IPO at an aggressive pace, slowing growth may turn away potential investors.",
"is_mention": true
}
// …surrounding lines for context
]
}
]
}
// …
],
"has_more": true,
"cursor": "s.…",
"entity": { "slug": "sam-altman", "name": "Sam Altman", "description": "CEO of OpenAI" }
}
```
Each episode group returns one or more `windows` — contiguous ranges of dialogue where the entity is mentioned, with `context_lines` of surrounding speech (default `2`, configurable up to `20`). Every line that actually names the entity has `is_mention: true`. The `start_seconds` and `end_seconds` deep-link into the audio.
Use `/v1/podcasts/mentions` for "every line about an entity." Use [`/v1/podcasts/episodes/search`](/podcasts/episode-search) for "every segment that *talks about* a topic" (paraphrase-tolerant) or contains a specific phrase (BM25). They're complementary — see [Episode search](/podcasts/episode-search) for when to reach for which.
The same endpoint answers "what has *one show* been saying about *one entity*?" Stack `entity_id` with `podcast_id` to scope dialogue to a single podcast — for example, every line the All-In podcast has aired about OpenAI:
```bash curl theme={"dark"}
curl --get "https://api.particle.pro/v1/podcasts/mentions" \
--data-urlencode "entity_id=openai" \
--data-urlencode "podcast_id=all-in" \
--data-urlencode "limit=2" \
-H "X-API-Key: $PARTICLE_API_KEY"
```
```js JavaScript theme={"dark"}
const url = new URL("https://api.particle.pro/v1/podcasts/mentions");
url.searchParams.set("entity_id", "openai");
url.searchParams.set("podcast_id", "all-in");
url.searchParams.set("limit", "2");
const res = await fetch(url, {
headers: { "X-API-Key": process.env.PARTICLE_API_KEY },
});
const { data } = await res.json();
```
```python Python theme={"dark"}
res = httpx.get(
"https://api.particle.pro/v1/podcasts/mentions",
params={"entity_id": "openai", "podcast_id": "all-in", "limit": 2},
headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]},
)
data = res.json()["data"]
```
```jsonc Response (truncated) theme={"dark"}
{
"data": [
{
"episode": {
"id": "4KnhQ9DsSIxBhDN3BP5iFN",
"title": "OpenAI Misses Targets, Codex vs Claude, Elon vs Sam Trial, Big Hyperscaler Beats, Peptide Craze",
"published_at": "2026-05-01T21:37:00Z",
"podcast": { "title": "All-In with Chamath, Jason, Sacks & Friedberg", "slug": "all-in" }
},
"mention_count": 35,
"mention_variants": ["OpenAI"],
"windows": [
{
"segment": { "type": "TOPIC_DISCUSSION", "title": "OpenAI misses targets and IPO debate" },
"start_seconds": 222.42,
"end_seconds": 275.7,
"lines": [
{
"speaker": "Jason Calacanis",
"role": "HOST",
"start_seconds": 229.76,
"end_seconds": 234.92,
"text": "OpenAI has $600 billion in spending commitments for compute.",
"is_mention": true
}
// …surrounding lines for context
]
}
// …more windows in this episode
]
}
// …more All-In episodes
],
"has_more": true,
"cursor": "s.1hwwoMp2ojPqMXPMC40Qn5lyYu2z9jHwDAbO",
"entity": { "slug": "openai", "name": "OpenAI", "description": "Artificial intelligence company" }
}
```
Same shape as the Sam Altman call — episodes, windows, mention-flagged lines — just narrowed to one show. Swap `podcast_id` for any other slug (`acquired`, `lex-fridman`, `the-tim-ferriss-show`) to ask the same question of a different audience.
## 3. Find episodes where they were actually a guest
Mentions tells you where someone was *discussed*. Episodes tells you where they were *featured*. Filter by `entity_id` plus a `role` to get just the episodes where Sam Altman was on the show as a guest — not the hundreds of episodes where his name comes up in passing.
```bash curl theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/episodes?entity_id=sam-altman&role=guest&limit=3" \
-H "X-API-Key: $PARTICLE_API_KEY"
```
```js JavaScript theme={"dark"}
const res = await fetch(
"https://api.particle.pro/v1/podcasts/episodes?entity_id=sam-altman&role=guest&limit=3",
{ headers: { "X-API-Key": process.env.PARTICLE_API_KEY } },
);
const { data } = await res.json();
```
```python Python theme={"dark"}
res = httpx.get(
"https://api.particle.pro/v1/podcasts/episodes",
params={"entity_id": "sam-altman", "role": "guest", "limit": 3},
headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]},
)
data = res.json()["data"]
```
```jsonc Response (truncated) theme={"dark"}
{
"data": [
{
"id": "2cgrh56ehQYBlXwqecmZ9P",
"title": "OpenAI CEO Sam Altman & Amazon CEO Andy Jassy 2/27/26",
"podcast": { "title": "Squawk Pod", "slug": "squawk-pod" },
"published_at": "2026-02-27T17:08:52Z",
"duration_seconds": 2916,
"speakers": [
{ "name": "Joe Kernen", "role": "HOST" },
{ "name": "Sam Altman", "role": "GUEST", "entity": { "slug": "sam-altman" } },
{ "name": "Andy Jassy", "role": "GUEST", "entity": { "slug": "andy-jassy" } }
// …
],
"segment_count": 17,
"clip_count": 6,
"has_transcript": true
}
// …
],
"has_more": true,
"cursor": "…"
}
```
`role` accepts `guest`, `host`, `panelist`, `correspondent`, or `mention`. Drop the filter and you'll get every episode that touches the entity in any way — useful for broad recall, but for "where was Sam Altman actually interviewed" you want `role=guest`.
Hold onto the first result's `id` (`2cgrh56ehQYBlXwqecmZ9P` above) for the next call.
## 4. Surface the highlight clips
Episode highlights are AI-extracted clips — typically a handful per episode — scored for engagement and classified by type (`INSIGHTFUL`, `FUNNY`, `CONTROVERSIAL`, `AHA_MOMENT`, `NOTABLE_LINE`, and more). Pull the clips from the episode you just found.
```bash curl theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/episodes/2cgrh56ehQYBlXwqecmZ9P/clips?limit=3" \
-H "X-API-Key: $PARTICLE_API_KEY"
```
```js JavaScript theme={"dark"}
const episodeId = "2cgrh56ehQYBlXwqecmZ9P";
const res = await fetch(
`https://api.particle.pro/v1/podcasts/episodes/${episodeId}/clips?limit=3`,
{ headers: { "X-API-Key": process.env.PARTICLE_API_KEY } },
);
const { data } = await res.json();
```
```python Python theme={"dark"}
episode_id = "2cgrh56ehQYBlXwqecmZ9P"
res = httpx.get(
f"https://api.particle.pro/v1/podcasts/episodes/{episode_id}/clips",
params={"limit": 3},
headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]},
)
data = res.json()["data"]
```
```jsonc Response (truncated) theme={"dark"}
{
"data": [
{
"id": "53Fl0WgYU8H45pwOtkKHc2",
"type": "INSIGHTFUL",
"title": "AGI Sooner Than Expected",
"description": "Sam Altman says AI progress is moving faster than even he predicted and hints that AGI could arrive sooner than people imagine.",
"intro_statement": "Sam Altman evaluates how fast AGI approaches.",
"engagement_score": 85,
"duration_seconds": 37.62,
"speaker": {
"name": "Sam Altman",
"role": "GUEST",
"entity": { "slug": "sam-altman" }
},
"audio_url": "https://cdn.particle.pro/podcast/episode/…/clip/audio/….mp3"
}
// …
],
"has_more": true,
"cursor": "…"
}
```
`audio_url` is a direct MP3 of the clip — embed it, drop it into a player, or attach it to a social post. `intro_statement` is a ready-to-use lead-in for show notes or share copy.
## 5. Search dialogue by topic
Mentions and episode filtering both pivot off *who* is being talked about. Search pivots off *what is being said*. Use `semantic_search` for paraphrase-tolerant retrieval — describe the topic in your own words and the engine finds segments that discuss the same idea, even when they use different vocabulary.
```bash curl theme={"dark"}
curl --get "https://api.particle.pro/v1/podcasts/episodes/search" \
--data-urlencode "semantic_search=labor market disruption due to artificial intelligence" \
--data-urlencode "limit=2" \
-H "X-API-Key: $PARTICLE_API_KEY"
```
```js JavaScript theme={"dark"}
const url = new URL("https://api.particle.pro/v1/podcasts/episodes/search");
url.searchParams.set(
"semantic_search",
"labor market disruption due to artificial intelligence",
);
url.searchParams.set("limit", "2");
const res = await fetch(url, {
headers: { "X-API-Key": process.env.PARTICLE_API_KEY },
});
const { data } = await res.json();
```
```python Python theme={"dark"}
res = httpx.get(
"https://api.particle.pro/v1/podcasts/episodes/search",
params={
"semantic_search": "labor market disruption due to artificial intelligence",
"limit": 2,
},
headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]},
)
data = res.json()["data"]
```
```jsonc Response (truncated) theme={"dark"}
{
"data": [
{
"episode": {
"id": "371bZsGWsJYikBxoCej3GS",
"title": "Where Investment Themes Intersect and Beat Markets",
"podcast": { "title": "Thoughts on the Market", "slug": "thoughts-on-the-market" }
},
"segment": {
"type": "TOPIC_DISCUSSION",
"title": "Labor Market Transformation from AI",
"summary": "90% of occupations impacted\nSector analysis of employment effects\nNet 4% job loss with offsets from new hires\nShift toward role transformation over replacement",
"start_seconds": 107.98,
"end_seconds": 150.36
},
"windows": [
{
"lines": [
{
"speaker": "Stephen Byrd",
"role": "HOST",
"text": "Now, at the same time, AI is reshaping the labor market.",
"is_match": true
},
{
"speaker": "Stephen Byrd",
"role": "HOST",
"text": "We estimate that automation or augmentation will impact ninety percent of occupations, so almost every job will be affected, but the effect is not binary.",
"is_match": true
}
// …context lines around the matches
]
}
],
"match": { "source": "semantic", "relevance_score": 0.61 }
}
// …
],
"has_more": true,
"cursor": "…"
}
```
Each result is one *segment* of one episode. The query never used the words "automation," "occupations," or "employment" — `semantic_search` matched on meaning. Lines whose text drove the match are flagged `is_match: true`. The response also returns any highlight clips that overlap the segment in the same payload.
For exact-phrase matches (tickers, drug names, model numbers), pass `keyword_search` instead — or both, for hybrid retrieval. Add `entity_id` or `company_id` to scope a topical search to episodes featuring a specific person or company. The full surface is documented in [Episode search](/podcasts/episode-search).
## 6. Pivot to companies
Companies in Particle API are cross-referenced across every identifier system you might already have — SEC CIK, Wikidata QID, stock ticker, domain, and knowledge-graph slug. Look up Shopify by ticker:
```bash curl theme={"dark"}
curl "https://api.particle.pro/v1/companies?ticker=SHOP&limit=1" \
-H "X-API-Key: $PARTICLE_API_KEY"
```
```js JavaScript theme={"dark"}
const res = await fetch(
"https://api.particle.pro/v1/companies?ticker=SHOP&limit=1",
{ headers: { "X-API-Key": process.env.PARTICLE_API_KEY } },
);
const { data } = await res.json();
```
```python Python theme={"dark"}
res = httpx.get(
"https://api.particle.pro/v1/companies",
params={"ticker": "SHOP", "limit": 1},
headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]},
)
data = res.json()["data"]
```
```json Response theme={"dark"}
{
"data": [
{
"id": "21IMlzahxqyE3wPovDXXM9",
"name": "Shopify",
"description": "Shopify offers an e-commerce platform mainly to small and medium-sized businesses…",
"identifiers": {
"cik": "0001594805",
"qid": "Q7501150",
"entity": {
"id": "17PzxG1tF2dy48",
"slug": "shopify",
"name": "Shopify"
},
"ticker": "SHOP",
"domain": "shopify.com"
}
}
],
"has_more": false
}
```
Path-style lookups accept the slug, the domain, or the canonical ID — these all return the same Shopify record (`id: 21IMlzahxqyE3wPovDXXM9`):
```bash theme={"dark"}
curl "https://api.particle.pro/v1/companies/shopify" -H "X-API-Key: $PARTICLE_API_KEY" # by slug
curl "https://api.particle.pro/v1/companies/shopify.com" -H "X-API-Key: $PARTICLE_API_KEY" # by domain
```
For ticker, CIK, or QID lookups use the list endpoint (`/v1/companies?ticker=SHOP`, `?cik=…`, `?qid=…`). The nested `entity.slug` (`shopify`) is the same kind of handle you used for Sam Altman in step 1 — feed it to any entity-aware endpoint to surface Shopify's mentions, episodes, and clips across the catalog.
## 7. Get sponsor analytics in one call
Companies show up in podcasts in two ways: as topics of conversation *and* as advertisers. The per-company advertising endpoint gives you the sponsor view in a single request.
```bash curl theme={"dark"}
curl "https://api.particle.pro/v1/companies/shopify/podcast/advertising" \
-H "X-API-Key: $PARTICLE_API_KEY"
```
```js JavaScript theme={"dark"}
const res = await fetch(
"https://api.particle.pro/v1/companies/shopify/podcast/advertising",
{ headers: { "X-API-Key": process.env.PARTICLE_API_KEY } },
);
const summary = await res.json();
```
```python Python theme={"dark"}
res = httpx.get(
"https://api.particle.pro/v1/companies/shopify/podcast/advertising",
headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]},
)
summary = res.json()
```
```jsonc Response (truncated) theme={"dark"}
{
"company_id": "shopify.com",
"total_ads": 9349,
"podcast_reach": 578,
"episode_reach": 8277,
"read_type_breakdown": { "host_read": 7003, "pre_recorded": 2346 },
"recent_ads": [
{
"sponsor_name": "Shopify",
"product": "Shopify checkout",
"offer_description": "Get a $1 trial when you switch to Shopify today",
"sponsor_url": "shopify.com/setup",
"read_type": "PRE_RECORDED",
"placement_type": "PRE_ROLL",
"start_seconds": 9.4,
"end_seconds": 38.1,
"duration_seconds": 28.7,
"podcast": { "title": "The John Batchelor Show", "slug": "the-john-batchelor-show" },
"created_at": "2026-04-29T01:42:01.520819Z"
}
// …
]
}
```
You get host-read vs pre-recorded breakdowns, recent placements with podcast attribution, and product-level tagging where available — plus the in-episode timing of each read. Enough to power competitive intelligence dashboards or category-spend analysis without scraping audio yourself.
## What's next
IDs and slugs, pagination, errors, pricing weight, and choosing the right endpoint for the job.
Episodes, transcripts, segments, clips, advertising, and bias.
Every endpoint with request and response schemas.