Skip to main content
Entities are the knowledge-graph layer that connects everything else. The same entity (Sam Altman, Nvidia, Federal Reserve) appears as a speaker on episodes, as a mention in transcripts, as a sponsor in advertising data, and as the linked identity on a company profile. Resolve once, then follow the entity across the platform. Each entity has a stable slug (e.g. sam-altman, nvidia, kara-swisher) and a canonical id. Either is accepted anywhere an entity reference is needed.
Available to MCP agents as particle_entity_resolve (the union resolver) and particle_person_resolve (people only).

​
Search entities

curl "https://api.particle.pro/v1/entities?q=Sam+Altman&limit=3" \
  -H "X-API-Key: $PARTICLE_API_KEY"
Response (truncated)
{
  "data": [
    {
      "id": "17PzxG1t12xzno",
      "slug": "sam-altman",
      "name": "Sam Altman",
      "description": "CEO of OpenAI",
      "wikipedia_url": "https://en.wikipedia.org/wiki/Sam_Altman"
    }
  ],
  "has_more": false
}

​
Filter parameters

ParameterDescription
qName search (case-insensitive)
typeRestrict to an entity category (e.g. person, company); see GET /v1/entities/types for the slugs
podcast_idRestrict to entities appearing in a specific podcast
idsBulk multi-get: fetch a known set of entities by slug or ID in one call (see below)

​
Get a single entity

# Either of these resolves to Sam Altman
curl "https://api.particle.pro/v1/entities/sam-altman" \
  -H "X-API-Key: $PARTICLE_API_KEY"
curl "https://api.particle.pro/v1/entities/17PzxG1t12xzno" \
  -H "X-API-Key: $PARTICLE_API_KEY"
Response
{
  "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/…"
}

​
Fetch many at once

When you already hold a set of entity slugs or IDs, pass them as a comma-separated ids list to fetch them all in a single request instead of one call per entity — up to 100 per call. Entities come back in the same shape as search and in the order you asked for them. A ref that doesn’t resolve is simply left out (no error, no placeholder), so compare the returned slug/id values against what you sent to find any that are missing. 
curl "https://api.particle.pro/v1/entities?ids=sam-altman,nvidia,17PzxG1t12xzno" \
  -H "X-API-Key: $PARTICLE_API_KEY"
Response (truncated)
{
  "data": [
    { "id": "17PzxG1t12xzno", "slug": "sam-altman", "name": "Sam Altman" },
    { "id": "2dFq…", "slug": "nvidia", "name": "Nvidia" }
  ],
  "has_more": false
}
When ids is present the other filters (q, type, podcast_id) and pagination are ignored — it is a direct multi-get of exactly the refs you supply.

​
Podcast appearances

To find every podcast episode where an entity has been featured or discussed across the catalog, use list-episodes with an entity_id filter. Add a role filter to narrow to guest, host, panelist, correspondent, or mention. 
curl "https://api.particle.pro/v1/podcasts/episodes?entity_id=sam-altman&limit=3" \
  -H "X-API-Key: $PARTICLE_API_KEY"
Response (truncated)
{
  "data": [
    {
      "id": "78cgekLUjCJBUZbj3s5K8Y",
      "title": "WHCD Shooting Aftermath, Musk and Altman Face-Off, Spirit Airlines Bailout",
      "podcast": { "id": "QpMz7GYKfSNuUa6zKXA4Q", "title": "Pivot" },
      "published_at": "2026-04-28T10:00:00Z",
      "duration_seconds": 4206,
      "has_transcript": true,
      "segment_count": 21,
      "clip_count": 8,
      "entity_count": 146,
      "speakers": [ /* … */ ]
    }
    // …
  ],
  "has_more": true,
  "cursor": "…"
}
Add role=guest to limit results to episodes where the entity was actually a guest, rather than every episode that happens to mention them.

​
A typical cross-referencing flow

1

Resolve the entity

Look up by name (?q=) or use a slug you already have.
curl ".../v1/entities/sam-altman"
2

Find episodes

Use the slug as entity_id on episodes or clips.
curl ".../v1/podcasts/episodes?entity_id=sam-altman&limit=10"
3

Drill into one episode

Pull the dialogue lines around mentions, or the highlight clips.
curl ".../v1/podcasts/episodes/{id}/transcript/mentions?entity_id=sam-altman"
curl ".../v1/podcasts/episodes/{id}/clips"
4

Cross to companies

Many entities are also linked to companies. Lookup by entity_id on the companies endpoint.
curl ".../v1/companies?entity_id=nvidia"
The Quickstart walks the full flow end-to-end.