Skip to main content
GET
Ranked catalog counts of who a set of channels mention

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

channel_ids
string

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

entity_ids
string

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

video_ids
string

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_types
string

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
enum<string>
default:mentions

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

Available options:
mentions,
appearances,
both
after
string

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.

before
string

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.

limit
integer
default:20

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

Required range: 1 <= x <= 40
src
enum<string>

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.

Available options:
mcp-tool

Response

Success

mode
enum<string>
required

The mode applied.

Available options:
mentions,
appearances,
both
window
object
required

The publication window the answer covers, [after, before) in UTC, normalized from after and before.

channel_ids
string[]
required

The channel ids counted.

video_ids
string[]
required

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

rows
object[]
required

One row per entity and channel, ranked by count.

returned
integer
required
has_more
boolean
required

True when more entity and channel pairs exist past limit.

shared
object[]
required

Entities on two or more of the requested channels, ranked by the smallest per-channel count. Empty for one channel.

as_of
string | null
required

Newest media across rows. Null when there are none.

note
string
required

One steering sentence for the agent reading this.

freshness
object

Present when your plan's freshness gate cut the window: where results on this plan stop. unlock names the plan that reads past it.

unlock
object

Present with freshness when your plan's freshness gate cut the window; note says so.