# Company mentions API: overview

Source: https://subalytics.com/docs/entity-overview/

> How the Subalytics entity mentions API works: stable IDs, freshness, typical workflow, daily sync and withdrawn mentions.

Entity mentions finds references to public companies in Substack posts, Bluesky posts and podcast episodes. It is a separate product from the other endpoints, with its own access, and every endpoint name starts with `entity-`.

**Only content that mentions a company is returned.** A post or episode appears only if it has at least one company mention. Podcast endpoints return only the transcript passages that contain a mention, never the full transcript.

## IDs

Resources are linked by stable public IDs that never change for the same item, so they are safe to store as foreign keys:

| ID | Identifies | Notes |
|---|---|---|
| `symbol` | Company | Stock ticker, e.g. META |
| `mention_id` | Mention | One mention of one company in one piece of content |
| `content_id` | Content | The post or episode: post_id (Substack), post_uri (Bluesky) or episode_sub_id (podcasts) |
| `sub_id` | Creator / podcast | The same Subalytics ID used by the creator and podcast endpoints, so mentions join to data you already have |

To fetch one item, filter by its ID, e.g. `/api/v1/entity-mentions/?mention_id=9f2c41d07ab35e18`.

## Freshness

- **Bluesky:** posts usually appear within minutes.
- **Substack:** posts appear after each collection run.
- **Podcasts:** episodes appear once they have been transcribed and matched, usually within a few hours of the daily 05:00 UTC run.

## Typical workflow

- **List monitored companies:** `GET /api/v1/entity-companies/`. This is the only endpoint with CIK, exchange, sector and industry; the others identify a company by `symbol` and `company_name`.
- **Get mentions of a company:** `GET /api/v1/entity-mentions/?symbol=META&published_from=2026-09-01`. One row per mention from every source, each with a snippet and a link to the content.
- **Get the content:** `GET /api/v1/entity-bluesky-posts/?symbol=META`, or the Substack or podcast equivalent. Each post or episode lists every company it mentions in `entities[]`.
- **Track volume:** `GET /api/v1/entity-mention-stats/?symbol=META&interval=day` for a time series, or `GET /api/v1/entity-trending/?sort=change` for the companies whose mention volume moved most.

## Daily sync

Ask only for what was added or changed since your last sync:

```
GET /api/v1/entity-mentions/?updated_from=2026-09-28T05:00:00
GET /api/v1/entity-bluesky-posts/?updated_from=2026-09-28T05:00:00
```

`updated_from` filters on when a record last changed, not when the content was published: a podcast episode published three days ago but matched today is included. Start each `updated_from` a few minutes before your previous sync; receiving the same record twice is harmless.

## Mentions can be withdrawn

Matching improves over time and past content is re-checked. That can add mentions, change their confidence, or remove a mention that turned out to be wrong. A post whose last mention is removed disappears from the content endpoints. Removals don't show up in an `updated_from` sync, so re-pull a recent window (e.g. the last 30 days) periodically if you need an exact match with the API.