Concepts

Cross-cutting conventions: IDs, moment links, pagination, errors, pricing weight, and choosing the right endpoint.

This page is the cheat sheet every other guide refers back to. Skim it once, then look up specifics as needed.

IDs and slugs

Most endpoints with an {id} path parameter accept either:

• The canonical opaque ID (e.g. 17PzxG1t12xzno for Sam Altman, 3CensCwu5G2oKCFgPrNf89 for Nvidia), or
• A human-readable slug (e.g. sam-altman, nvidia, pivot, the-joe-rogan-experience).

Use whichever you have. If you receive an entity slug from one response (entity_slug: "nvidia"), you can pass it directly to any other endpoint without first looking up the canonical ID.

Slugs are short handles Particle assigns, not names slugified: 20VC is the-twenty-minute-vc, Lenny’s Podcast is lennys, All-In is all-in. Take them from responses; a constructed slug returns 404, and trying other spellings never resolves it. A podcast slug is not an episode id: list the show’s episodes to get one. To turn a name into a slug, use the search endpoints below; each returns the slug alongside the match.

curl

# Both of these resolve to the same entity:
curl ".../v1/entities/sam-altman"        -H "X-API-Key: $PARTICLE_API_KEY"
curl ".../v1/entities/17PzxG1t12xzno"    -H "X-API-Key: $PARTICLE_API_KEY"

Companies are richer: /v1/companies/{id} resolves slug, domain, and canonical ID directly. To look up by ticker, CIK, or QID, use the corresponding query filter on GET /v1/companies (?ticker=…, ?cik=…, ?qid=…) and pass the returned slug, domain, or ID through the singular endpoint. See Companies → Identifiers.

Podcasts accept one extra form: every podcast {id} slot (and the podcast_id filter on list endpoints) also resolves a numeric Apple/iTunes collection ID directly (e.g. 1535809341) — so a client that already holds an iTunes ID can call any podcast endpoint without a prior lookup. To resolve a Spotify show ID, YouTube channel ID, RSS feed URL, or other platform identifier, use GET /v1/podcasts/lookup.

The podcast_id filter also accepts a particle.pro or Radar show link (https://particle.pro/podcast/<show>, https://radar.particle.pro/podcasts/<show>), and a Radar episode link resolves to its show. The episode_id filter accepts a particle.pro or Radar episode link (https://particle.pro/episode/<episode>, https://radar.particle.pro/podcasts/<show>/episodes/<episode>). Links to other sites are not parsed; use the lookup endpoints for those.

Podcast and episode {id} slots also take a raw UUID (a759e894-51e2-4ae9-94f9-883b6d146cfb), the form a web_url uses for a record without a slug.

Moment links

Every hit that points into an episode carries a link that plays that moment on Radar, Particle’s podcast reader. Cite it, post it, or put it in a digest, and the reader lands on the exact quote:

https://radar.particle.pro/podcasts/<podcast>/episodes/<episode>?t=<seconds>

• t is the offset in seconds from the start of the episode audio, rounded up to a tenth of a second (?t=87.2, ?t=2702), so the link never lands before the moment it names.
• <podcast> and <episode> are slugs, or the raw UUID for the rare record without one. Either form round-trips: pass the link back as a podcast or episode {id} and it resolves to the same record.
• Radar starts playback at t, scrolls to the line and highlights it. A signed-out visitor reads the whole segment containing t.

Response	Field	Moment
Search match	url	the first window’s start, or the segment’s start with format=compact
Search window	windows[].url	the window’s start
Mentions window	windows[].url	the window’s start
Clip	url	the clip’s start
Ad placement (recent_ads, episode ads, episode ad listings)	url	the ad’s start
Segment that embeds its episode (segment listings, company ad placements, sponsor segments)	url	the segment’s start
Entity chart clip	highlight_clip.url, narrative.clip.url	the clip’s start
Entity chart narrative	narrative.quote_url	quote_start_seconds, when verifiable

The embedded episode on those responses carries web_url, the episode’s page without t. Append ?t=<seconds> to it for any other offset, such as a transcript line’s start_seconds. web_url is omitted for back-catalogue episodes we have not ingested, which have no page yet.

Cursor pagination

List endpoints share a single response envelope:

{
  "data": [ /* … */ ],
  "has_more": true,
  "cursor": "r.4gfFC7"
}

To fetch the next page, pass the cursor value back as a query parameter:

curl

curl ".../v1/podcasts?cursor=r.4gfFC7" \
  -H "X-API-Key: $PARTICLE_API_KEY"

Cursors are opaque — treat them as strings, do not parse or construct them, and do not assume any ordering of values across versions. A malformed cursor (truncated, re-encoded, or not a cursor at all) is rejected with 422 validation_error rather than read as the first page. data is always an array: an empty result is [], never null. Send the same filters and limit with the cursor: it continues the request that produced it, and changing a filter starts a new walk without one. The default page size is endpoint-specific (often 25); use limit to override (typically up to 100).

Authentication

Two header forms are accepted; X-API-Key is recommended.

# Recommended
curl -H "X-API-Key: $PARTICLE_API_KEY" "https://api.particle.pro/v1/podcasts"

# Equivalent
curl -H "Authorization: Bearer $PARTICLE_API_KEY" "https://api.particle.pro/v1/podcasts"

Embed endpoints (/v1/embed/*) intentionally do not require authentication so the responses can be used as public iframe payloads, and GET /v1/podcasts/stats is open so anyone can read the catalog size.

A missing, mistyped, revoked, or expired key all return the same 401 with error_code: "api_key_required", so on a 401 check the header name (X-API-Key) and the key itself at platform.particle.pro/tokens rather than looking for a more specific code. GET /v1/me is free and confirms a key works, naming the organization and project it belongs to.

GET /v1/me/usage, also free, reports what the key used: requests this billing period (or today) by endpoint and MCP tool, and how many requests they billed. On a plan billed in requests, billable_requests counts what each call draws from your included requests (or, past them, as overage): most calls draw 1, and a transcription request that queues an episode draws 100. On a plan billed in dollars each billed call counts once; billable_basis says which applies. A refunded transcription request no longer counts. Free endpoints never count as billable, and neither do endpoints billed through plan features and add-ons rather than per call (alerts, the episode archive and stream), or a retried write answered from its first response under an Idempotency-Key. Counts come from the request log, which keeps 90 days: an annual billing period reports counts_since, the date its counts begin. MCP calls made through an OAuth grant carry no API key and appear under none.

Pricing weight

Every endpoint is available on every account — there is no tier lock. Endpoints are priced differently, though: heavier endpoints (full transcripts, transcript mentions, advertising analytics, cross-podcast clip search, competitor lookups) consume more credits per call than lighter ones (entity, topic, and podcast metadata; episode lookups and sub-resources; clip listings; embed).

The OpenAPI tag on every operation declares the pricing class — tier:standard or tier:premium. Treat it as a hint about cost, not a hint about access. Your usage dashboard breaks down spend by endpoint so you can see where credits are going.

Choosing the right endpoint

The API exposes overlapping ways to find content. Pick by what you actually need.

You want…	Use	Notes
A podcast (show) by name	GET /v1/podcasts/search?q=…	Forgiving ranked name search with a match_quality signal per result. For a known Apple/Spotify/YouTube ID, use /v1/podcasts/lookup instead.
A person, company, or other entity by name, ticker, handle, or domain	GET /v1/entities/search?q=…	Typed results, each with match_quality and mentions.podcast_episodes, the number of episodes naming it. This is the free-text search; GET /v1/entities lists and filters by type, podcast_id, or ids and takes no q.
Dialogue matching the meaning of a query, paraphrase-tolerant	GET /v1/podcasts/episodes/search?semantic_search=…	Vector similarity. Express the topic the way you’d describe it; speakers may use different vocabulary.
Dialogue containing exact tokens or phrases	GET /v1/podcasts/episodes/search?keyword_search=…	BM25. Use for proper nouns, tickers, drug names, product codes.
Every dialogue line where a person or company is mentioned	GET /v1/podcasts/mentions?entity_id=…	Episode-grouped mention windows with is_mention flags. Use for the read-everything-about-X workflow.
Combine ranked search with an entity scope	GET /v1/podcasts/episodes/search?semantic_search=…&entity_id=…	Ranked candidates filtered to episodes where the entity appears.
Episode-level filtering by entity, topic, language, or date	GET /v1/podcasts/episodes?entity_id=…	Standard list, supports rich filters. Use when you don’t need dialogue.
All entities mentioned in one episode	GET /v1/podcasts/episodes/{id}/transcript/mentions	Per-episode rollup with surrounding-context windows.
Salience rollup of an entity across one podcast’s episodes	GET /v1/podcasts/{id}/mentions	Episode-level aggregate within one podcast.
AI-segmented structural sections of an episode	GET /v1/podcasts/episodes/{id}/segments	Intros, ads, topic discussions, interviews.
Browse highlight clips ranked by engagement	GET /v1/podcasts/clips	Curated highlights. Clips matching dialogue content come back inside /v1/podcasts/episodes/search results.
Who advertises on which podcasts	GET /v1/companies/{id}/podcast/advertising and /v1/podcasts/advertising/leaderboard	Sponsor-side analytics.

Quickstart walks through several of these patterns end-to-end.

Time windows

An endpoint that bounds its results in time takes since and until. Each accepts an ISO 8601 date (2026-09-01) or date-time (2026-09-01T12:00:00Z); a value without a timezone is read as UTC. Where an endpoint’s until takes a bare date, it covers that whole day.

Which side is inclusive is not uniform: some bounds read “on or after”, others “after”. Each parameter’s description says which, and what timestamp it bounds. That is usually publication, but publisher bias bounds when an analysis was evaluated, rankings bound when a chart was captured, and alert matches bound when a match was detected.

Some endpoints took other spellings before they converged on since/until. They still work, are marked deprecated in the API reference, and are rejected with a 422 only when they disagree with since/until in the same request:

Deprecated spelling	Use instead	Where
published_after, published_before	since, until	episode lists and timeseries, podcast episodes and mentions, mention timeseries and share of voice, advertising timeseries, guest appearances
after, before	since, until	alert matches

A few parameters look like windows but bound something else, so they keep their names:

Parameter	What it bounds
updated_since, updated_after	When a record last changed, for incremental sync; independent of since
appeared_since, first_appearance_since, active_since	A named attribute of each result (a guest’s latest or earliest appearance, a sponsor’s latest ad), not the window the results are counted in
window_days	The length of a comparison window, in whole days
window	Which published chart edition to read (7d, 24h)
period	A calendar month or day of the episode archive
published_within_days	Distance in days from a given episode, on either side

Errors

Errors follow RFC 9457 (Problem Details for HTTP APIs). Every error response is application/problem+json with at minimum status, title, and detail, plus a stable error_code for programmatic branching and an optional resolve object pointing at how to fix the issue.

See Errors → Overview for the full envelope, the catalog of error codes, and patterns for handling them in UI clients and agents.

Rate limits

Every organization may make 10,000 requests per minute across all of its API keys and projects, on every plan. Rate-limited responses carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (seconds until the window resets). A request over the limit returns HTTP 429 with error_code: "rate_limit_exceeded" and a Retry-After header; wait that long and retry. See rate_limit_exceeded.