Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.arcmira.com/llms.txt

Use this file to discover all available pages before exploring further.

The channel sponsors endpoint rolls the recommendations pipeline up into a sponsor list per channel. It applies a minimum ad-read threshold to filter out one-offs and joins against known_advertisers to surface sponsor status (active / lapsed / ended / uncertain). 
GET /v1/channels/{channel_id}/sponsors
{channel_id} is a YouTube channel ID (e.g. UC-DRzaGnL_vtBUpCFH5M0tg), not an ent_*.
Channel sponsors are gated behind Pro+ and require the recommendations:read scope. See Scopes and Commercial intelligence.

​
Minimal request

cURL
curl 'https://api.arcmira.com/v1/channels/UC-DRzaGnL_vtBUpCFH5M0tg/sponsors?min_ad_reads=3' \
  -H "Authorization: Bearer $ARCMIRA_API_KEY"
Node 20+
const res = await fetch(
  'https://api.arcmira.com/v1/channels/UC-DRzaGnL_vtBUpCFH5M0tg/sponsors?min_ad_reads=3',
  { headers: { 'x-api-key': process.env.ARCMIRA_API_KEY } },
);
const { channel, sponsors, meta } = await res.json();

​
Parameters

ParameterDefaultDescription
min_ad_reads3Minimum number of ad_read rows for an entity to count as a recurring sponsor. Range 1–100.
status(any)Filter by known_advertisers.status: active, lapsed, ended, or uncertain.
limit1001–200. Sponsors are returned ordered by ad-read count, descending.
Lowering min_ad_reads to 1 surfaces every entity with a paid placement on the channel, including one-offs. Raise it to 5 or 10 to focus on long-running sponsor relationships.

​
Response shape

{
  "channel": {
    "id": "ent_6",
    "youtube_channel_id": "UC-DRzaGnL_vtBUpCFH5M0tg",
    "name": "TBPN"
  },
  "sponsors": [
    {
      "entity": {
        "id": "ent_14",
        "name": "Ramp",
        "type": "organization"
      },
      "ad_reads": 227,
      "videos": 197,
      "first_seen": "2025-02-01",
      "last_seen": "2026-04-24",
      "sponsor_status": {
        "status": "active",
        "ad_count": 80,
        "first_ad_date": "2025-02-01",
        "last_ad_date": "2026-04-24"
      }
    }
  ],
  "meta": {
    "min_ad_reads": 3,
    "count": 40
  }
}
A few notes:
  • channel.id is null when Arcmira doesn’t have a canonical entity for the YouTube channel ID; youtube_channel_id is always present.
  • ad_reads and videos come from the recommendations rollup. ad_reads is the total number of ad_read rows for the entity on this channel; videos is the count of distinct media those rows belong to.
  • sponsor_status is null when the entity isn’t in known_advertisers for this channel. When present, status is one of active, lapsed, ended, uncertain.
  • meta.count is the size of the returned page, not a total across all pages.

​
Pivoting to row-level evidence

Once you’ve identified a sponsor of interest, pull the underlying rows with /v1/recommendations: 
curl 'https://api.arcmira.com/v1/recommendations?entity_id=ent_14&channel_id=UC-DRzaGnL_vtBUpCFH5M0tg&mention_class=ad_read&limit=25' \
  -H "x-api-key: $ARCMIRA_API_KEY"
The com_* IDs in that response are what you submit to POST /v1/feedback if you want to reclassify individual rows.

​
Channel-page teaser

GET /v1/channels/{slug} includes a recommendations_summary block that summarizes the same data: 
{
  "recommendations_summary": {
    "sponsor_count": 40,
    "top_sponsors": ["Ramp", "Public", "Bezel"]
  }
}
sponsor_count is visible to every caller (no Pro+ required) — it’s a discoverability signal. top_sponsors only appears when the caller has Pro+ and recommendations:read. The full sponsor list still lives behind /v1/channels/{id}/sponsors.

​
Billing

Each sponsor in the response is a premium row — billed at a higher rate than appearance rows. A 40-sponsor list is 40 premium rows. Use limit to scope your page size. See Usage & billing.

​
Errors

CodeWhen
recommendations_not_enabledTier below Pro+.
insufficient_scopePro+ key missing recommendations:read.
channel_not_foundNo media in the index for this channel_id.
invalid_queryParam validation failed — see error.message.
See Errors for the full envelope.