Mentions

Ranked catalog counts of who a set of channels mention

A small ranked table of entity and channel counts, all-time unless after is set. Pass channel_ids for what shows talk about and entity_types to match the question (topic for subjects, person for guests, organization,product for brands). Pass video_ids with one id from GET /v1/channels/{channel_id}/videos for what a single episode mentions. Two or more channel_ids also return shared, the entities on more than one of them ranked by the smallest per-channel count, which is true overlap. An after later than the plan's freshness gate is refused with freshness_requires_paid rather than widened. Uses 4 credits per ranked entry returned past the first 5. Every gate is a typed error whose error.unlock.url names the plan that lifts it; pass src=mcp-tool only from the Arcmira MCP server.

get/v1/mentions/counts

Request

Base URL: https://api.arcmira.com
URL: https://api.arcmira.com/v1/mentions/counts
Auth: HTTP bearer

Query parameters

channel_idsstring

Comma-separated YouTube channel ids (UC...), at most 8. Two or more also return shared, the entities on more than one of them.

entity_idsstring

Comma-separated entity ids (ent_{n}), at most 20. Counts only these entities.

video_idsstring

Comma-separated 11-character YouTube video ids, at most 20. Counts only these episodes; take the ids from GET /v1/channels/{channel_id}/videos.

entity_typesstring

Comma-separated entity types to count: person, organization, product, topic, channel. Subjects are topic; guests are person; brands are organization,product. Omit and organizations dominate.

mode'mentions' | 'appearances' | 'both'

mentions counts talk about an entity; appearances counts a person being present; both counts either. Default mentions.

afterstring

Only media published at or after this instant. Counts are all-time without it. An after later than your plan's freshness gate is refused with freshness_requires_paid rather than widened. An ISO 8601 date (2026-09-01) or datetime with offset (2026-09-01T00:00:00Z), read in UTC. The window is half-open: after is inclusive, before is exclusive.

beforestring

Only media published before this instant, so before=2026-09-02 includes all of 2026-09-01. An ISO 8601 date (2026-09-01) or datetime with offset (2026-09-01T00:00:00Z), read in UTC. The window is half-open: after is inclusive, before is exclusive.

limitinteger

Rows in the ranked table, 1 to 40. Default 20.

src'mcp-tool'

The surface making this call. The Arcmira MCP server sends mcp-tool so every unlock link in a gate attributes to the directory install. Omit from your own client.

Response

Success

mode'mentions' | 'appearances' | 'both' required

The mode applied.

channel_idsstring[] required

The channel ids counted.

video_idsstring[] required

The video ids the count was scoped to. Empty when it was not.

returnedinteger required

has_moreboolean required

True when more entity and channel pairs exist past limit.

as_ofstring nullable required

Newest media across rows. Null when there are none.

notestring required

One steering sentence for the agent reading this.

Example response

{
  "mode": "mentions",
  "window": {
    "after": "2026-06-01T00:00:00Z",
    "before": null
  },
  "channel_ids": [
    "UC-DRzaGnL_vtBUpCFH5M0tg",
    "UClWkDGXEzsh77GAhs90wpXw"
  ],
  "video_ids": [],
  "rows": [
    {
      "entity_id": "ent_14",
      "name": "Ramp",
      "type": "organization",
      "page": "https://arcmira.com/org/ramp",
      "appearances_page": null,
      "mentions_page": null,
      "slug": "ramp",
      "channel_id": "UC-DRzaGnL_vtBUpCFH5M0tg",
      "channel_name": "TBPN",
      "channel_page": "https://arcmira.com/yt/@TBPNLive",
      "count": 23,
      "as_of": "2026-08-28T17:00:00.000Z"
    },
    {
      "entity_id": "ent_14",
      "name": "Ramp",
      "type": "organization",
      "page": "https://arcmira.com/org/ramp",
      "appearances_page": null,
      "mentions_page": null,
      "slug": "ramp",
      "channel_id": "UClWkDGXEzsh77GAhs90wpXw",
      "channel_name": "Moment of Truth",
      "channel_page": "https://arcmira.com/yt/@MomentofTruthShow",
      "count": 3,
      "occurrences": 7,
      "as_of": "2026-08-21T16:00:00.000Z"
    }
  ],
  "returned": 2,
  "has_more": false,
  "shared": [
    {
      "entity_id": "ent_14",
      "name": "Ramp",
      "type": "organization",
      "page": "https://arcmira.com/org/ramp",
      "appearances_page": null,
      "mentions_page": null,
      "slug": "ramp",
      "channel_count": 2,
      "by_channel": [
        {
          "channel_id": "UC-DRzaGnL_vtBUpCFH5M0tg",
          "channel_name": "TBPN",
          "channel_page": "https://arcmira.com/yt/@TBPNLive",
          "count": 23,
          "as_of": "2026-08-28T17:00:00.000Z"
        },
        {
          "channel_id": "UClWkDGXEzsh77GAhs90wpXw",
          "channel_name": "Moment of Truth",
          "channel_page": "https://arcmira.com/yt/@MomentofTruthShow",
          "count": 3,
          "occurrences": 7,
          "as_of": "2026-08-21T16:00:00.000Z"
        }
      ]
    }
  ],
  "as_of": "2026-08-28T17:00:00.000Z",
  "note": "Catalog counts, all-time unless you passed a window. shared ranks true overlap by the smallest per-channel count. Use search_transcripts afterwards only for quotes."
}

Changes

No recorded changes to this operation across all 1 revision of this API.