Skip to main content
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. 
# 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.

​
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 ".../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. 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.

​
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, entity appearances) 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…UseNotes
All episodes mentioning an entityGET /v1/entities/{id}/appearancesCross-podcast, episode-level metadata.
Episode-level filtering by entity, topic, language, or dateGET /v1/podcasts/episodes?entity_id=…Standard list, supports rich filters.
The actual dialogue around mentions in one episodeGET /v1/podcasts/episodes/{id}/transcript/mentionsReturns surrounding context lines and timestamps.
Mentions of an entity in a specific podcast across episodesGET /v1/podcasts/{id}/mentionsEpisode-level aggregate within one podcast.
Engagement-scored highlight momentsGET /v1/podcasts/clips/search?entity_id=…A handful of clips per episode; great for sharing, not corpus search.
AI-segmented structural sections of an episodeGET /v1/podcasts/episodes/{id}/segmentsIntros, ads, topic discussions, interviews.
Who advertises on which podcastsGET /v1/companies/{id}/podcast/advertising and /v1/podcasts/advertising/leaderboardSponsor-side analytics.
Quickstart maps directly onto the first three rows.

​
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

Rate-limited responses return HTTP 429 with error_code: "rate_limit_exceeded". Back off and retry — the response includes guidance in detail. See rate_limit_exceeded.