Entities

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

Search across people, companies, and knowledge graph entities in one ranked call. Pass a name, partial name, nickname, stock ticker, @handle, or website domain. Each result carries a type (person, company, or knowledge_graph_entity) telling you which collection it belongs to, and a match_quality so you can tell an exact identification from a fuzzy guess.

curl "https://api.particle.pro/v1/entities/search?q=Sam+Altman&limit=3" \
  -H "X-API-Key: $PARTICLE_API_KEY"

const res = await fetch(
  "https://api.particle.pro/v1/entities/search?q=Sam+Altman&limit=3",
  { headers: { "X-API-Key": process.env.PARTICLE_API_KEY } },
);
const { data } = await res.json();

res = httpx.get(
    "https://api.particle.pro/v1/entities/search",
    params={"q": "Sam Altman", "limit": 3},
    headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]},
)
data = res.json()["data"]

Each result is a discriminated union: type says which kind it is, and exactly one of person, company, or knowledge_graph_entity holds the matched record — the same compact object shape those resources return elsewhere, so you can reuse your existing rendering. match_quality and mentions (where the entity shows up) sit alongside it.

Response (truncated)

{
  "data": [
    {
      "type": "person",
      "match_quality": "exact",
      "mentions": { "podcast_episodes": 6254, "news_articles": 18230 },
      "person": {
        "id": "17PzxG1t12xzno",
        "slug": "sam-altman",
        "name": "Sam Altman",
        "description": "CEO of OpenAI"
      }
    },
    {
      "type": "company",
      "match_quality": "exact",
      "mentions": { "podcast_episodes": 12718, "news_articles": 8400 },
      "company": {
        "id": "1aB2c…",
        "slug": "nvidia",
        "name": "Nvidia",
        "domain": "nvidia.com",
        "ticker": "NVDA"
      }
    }
  ],
  "has_more": false
}

Take the embedded record’s id (or slug) to the matching resource endpoint (/v1/people, /v1/companies, /v1/entities), or its id to alert creation.

Search parameters

Parameter	Description
`q`	Free-text query: name, partial name, nickname, ticker, `@handle`, or domain (required)
`type`	Restrict to one kind: `person`, `company`, or `knowledge_graph_entity`
`limit`	Results per page (default 25, max 100)
`cursor`	Pagination cursor from the previous response’s `cursor`, to fetch the next page

List entities

GET /v1/entities returns the most-mentioned knowledge graph entities, or a filtered slice. (To search by name, use /v1/entities/search above.)

Parameter	Description
`type`	Restrict to an entity category (e.g. `person`, `company`); see `GET /v1/entities/types` for the slugs
`podcast_id`	Restrict to entities appearing in a specific podcast
`ids`	Bulk 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

Resolve the entity

Look up by name with /v1/entities/search or use a slug you already have.

curl ".../v1/entities/sam-altman"

Find episodes

Use the slug as entity_id on episodes or clips.

curl ".../v1/podcasts/episodes?entity_id=sam-altman&limit=10"

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"

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.

Topics — taxonomy companion to entities
Companies → Overview — entities linked to company records
Transcripts → Mentions — dialogue around entity mentions
Concepts → IDs and slugs — slug resolution rules

Getting started

Podcasts

Companies

Knowledge graph

Alerts

Errors

Search entities

Search parameters

List entities

Get a single entity

Fetch many at once

Podcast appearances

A typical cross-referencing flow

​Search entities

​Search parameters

​List entities

​Get a single entity

​Fetch many at once

​Podcast appearances

​A typical cross-referencing flow

​Related

Search entities

Search parameters

List entities

Get a single entity

Fetch many at once

Podcast appearances

A typical cross-referencing flow

Related