Commercial intelligence

Commercial intelligence is Arcmira’s paid-evidence layer: a second extraction pipeline that classifies on-camera commercial activity into paid ad reads, organic endorsements, and lower-signal commercial mentions, then rolls recurring relationships up into per-channel sponsor lists. In API terms it is two endpoint families: GET /v1/recommendations (row-level evidence) and GET /v1/channels/{channel_id}/sponsors (the rollup).

Commercial intelligence requires a Pro+ tier (pro_plus, ultra, teams, enterprise) AND the recommendations:read scope. Lower tiers get 403 recommendations_not_enabled regardless of scope; correctly tiered keys missing the scope get 403 insufficient_scope. Check /v1/me → recommendations_api_enabled before calling, and manage plans from Pricing.

When to use

You sell sponsorships or negotiate them. Pull a channel’s recurring advertisers before a negotiation: “who already sponsors TBPN, at what cadence, since when?” Never go into a sponsorship negotiation blind.
You model competitor spend. Row-level ad reads carry verbatim quotes, promo codes, and offers: “every Ramp ad read across business podcasts this year, with the codes they ran.”
You find organic champions. Endorsements are unpaid recommendations from hosts and guests: “which shows organically endorsed Figma after the IPO?”
You build advertiser dashboards. Re-expose the classification, confidence, and dispute machinery in your own product.

The two universes

Arcmira runs two independent extraction pipelines:

Universe	Endpoint	What it answers	Cost
Mentions	`/v1/mentions`	”Where was this entity talked about?“	1 row each
Commercial	`/v1/recommendations`	”Where was this entity paid for or endorsed?“	10 rows each

Different prompts, different quality rules, different false-positive profiles. They are deliberately not joined into one result set; /v1/mentions?details=full attaches matching commercial rows to mention rows, but the populations stay distinct.

Classification

Every commercial row carries a mention_class:

Class	Definition
`ad_read`	A paid sponsor read. Typically explicit (“this episode is brought to you by…”), often with a promo code.
`endorsement`	An organic recommendation from a host or guest. No money involved; the speaker vouches for it.
`mention`	A lower-signal commercial reference that didn’t meet the `ad_read`/`endorsement` bar. Surfaced for context.

Quality rules baked into the pipeline: entities with fewer than 3 ad reads on a channel are one-offs, not sponsors (tunable via min_ad_reads); a singleton ad_read with no sponsor language is downgraded to mention; canonical entity merges are followed automatically; rows with conflict_status: "disputed" are excluded unless you pass include_disputed=true.

Recommendations: row-level evidence

GET /v1/recommendations
GET /v1/entities/{id}/recommendations

Exactly one of entity_id or entity_name is required (the entity-scoped form takes it from the path).

const res = await fetch(
  'https://api.arcmira.com/v1/recommendations?entity_id=ent_14&mention_class=ad_read&limit=25',
  { headers: { Authorization: `Bearer ${process.env.ARCMIRA_API_KEY}` } },
);
const { data, has_more, next_cursor } = await res.json();

import os, httpx

r = httpx.get(
    'https://api.arcmira.com/v1/recommendations',
    params={'entity_id': 'ent_14', 'mention_class': 'ad_read', 'limit': 25},
    headers={'Authorization': f"Bearer {os.environ['ARCMIRA_API_KEY']}"},
)
body = r.json()

curl 'https://api.arcmira.com/v1/recommendations?entity_id=ent_14&mention_class=ad_read&limit=25' \
  -H "Authorization: Bearer $ARCMIRA_API_KEY"

Parameter	Default	Description
`entity_id` / `entity_name`	—	Canonical `ent_*` or a name (pair names with `entity_type`).
`channel_id` / `channel_name`	—	Restrict to one channel (YouTube `UC...` ID) or a name substring.
`mention_class`	`all`	`ad_read`, `endorsement`, `mention`, or `all`.
`min_confidence`	`0.7`	Float in `[0, 1]`.
`include_disputed`	`false`	Include rows whose classification is disputed.
`date_from` / `date_to`	—	Inclusive ISO-date bounds on `published_at`.
`limit` / `cursor`	20 / —	Standard cursor pagination.

Response row

{
  "id": "com_119682",
  "recommendation_id": 119682,
  "mention_class": "ad_read",
  "entity": { "id": "ent_124261", "name": "Bezel", "type": "organization" },
  "media": {
    "video_id": "DRZatti6mVM",
    "title": "...",
    "published_at": "2025-12-17",
    "channel_id": "UC-DRzaGnL_vtBUpCFH5M0tg",
    "source_channel": { "id": "ent_6", "name": "TBPN" }
  },
  "start_timestamp": "12:34",
  "end_timestamp": "13:02",
  "start_seconds": 754,
  "end_seconds": 782,
  "verbatim_quote": "...",
  "promo_code": "BEZEL20",
  "offer": null,
  "sentiment": 0.8,
  "sentiment_score": 0.8,
  "confidence": 0.95,
  "speaker_role": "host",
  "conflict_status": null,
  "resolution": null
}

id is the public com_* form: pass it to Community Review to dispute a row.
Read start_seconds/end_seconds (integer seconds; 0 means the full episode). The start_timestamp/end_timestamp MM:SS strings are deprecated and will be removed after a changelog-announced sunset.
sentiment_score is the raw [-1, 1] number, matching mention rows. The sentiment field carries the same number and is deprecated; read sentiment_score.
promo_code and offer are nullable, populated when the extractor found explicit codes or offers in the quote.
speaker_role distinguishes host reads from guest recommendations.
conflict_status/resolution surface cross-pass classification conflicts; disputed rows are excluded by default.

Channel sponsors: the rollup

GET /v1/channels/{channel_id}/sponsors

{channel_id} is a YouTube channel ID (UC-DRzaGnL_vtBUpCFH5M0tg), not an ent_*.

Parameter	Default	Description
`min_ad_reads`	`3`	Minimum `ad_read` rows for an entity to count as recurring. 1 surfaces every one-off; 5-10 focuses on long-running relationships. Range 1-100.
`status`	(any)	Filter by advertiser status: `active`, `lapsed`, `ended`, `uncertain`.
`limit`	`100`	1-200, ordered by ad-read count descending.

Response (truncated)

{
  "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 }
}

channel.id is null when there is no canonical entity for the channel; youtube_channel_id is always present.
sponsor_status is null for entities not in the known-advertiser registry; when present, status is active, lapsed, ended, or uncertain.
meta.count is the returned page size, not a global total.

Pivot from a sponsor of interest to its row-level evidence:

curl 'https://api.arcmira.com/v1/recommendations?entity_id=ent_14&channel_id=UC-DRzaGnL_vtBUpCFH5M0tg&mention_class=ad_read&limit=25' \
  -H "Authorization: Bearer $ARCMIRA_API_KEY"

Discovery and teasers

GET /v1/entities/search?has_recommendations_data=true restricts discovery to entities with commercial signal (free).
Entity reads on organization/product entities include a recommendations_summary aggregate for entitled callers (totals, unique shows, first/last seen, channels_as_sponsor). Zero rows.
Channel reads include a teaser under recommendations_summary: recommendations_summary.sponsor_count is visible to every caller (a discoverability signal); recommendations_summary.top_sponsors appears only with Pro+ and recommendations:read.

Billing

Every row returned by /v1/recommendations and every sponsor in /v1/channels/{id}/sponsors bills at 10 rows (versus 1 for a standard mention row). recommendations_summary blocks and teasers cost zero rows. details=full on mentions charges the mention row plus 10 rows per attached commercial item. See Usage, limits & billing.

Community Review

Commercial rows are exactly where you should push back: a false paid read hurts a brand, a missed one hurts a negotiation. Dispute rows by com_* ID, sponsors by ent_* + channel, for free:

curl -X POST 'https://api.arcmira.com/v1/feedback?type=recommendations' \
  -H "Authorization: Bearer $ARCMIRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "query": { "entity_id": "ent_124261", "mention_class": "ad_read" },
    "corrections": [{
      "id": "com_119682",
      "mention_class": "mention",
      "reason": "false_positive_ad_read",
      "notes": "Host was discussing the product organically. No sponsor language, no code."
    }]
  }'

Reason codes: false_positive_ad_read, false_positive_endorsement, missed_ad_read, missed_endorsement, wrong_classification, wrong_entity, other. Commercial review uses the same access as the data (Pro+ + recommendations:read); nothing auto-applies. Full catalog: Community Review.

Errors

Code	When
`recommendations_not_enabled`	Tier below Pro+ (independent of scope).
`insufficient_scope`	Pro+ key missing `recommendations:read`.
`entity_not_found`	`entity_id`/`entity_name` didn’t resolve.
`channel_not_found`	No indexed media for the channel ID (use the `UC...` form, not a slug).
`invalid_query`	Param validation failed; see `error.message`.

Try it in the playground
Search: the free evidence layer these rows enrich.
Community Review: the correction contract for every commercial surface.

API

Admin

Teams & Enterprise

Commercial intelligence

When to use

The two universes

Classification

Recommendations: row-level evidence

Channel sponsors: the rollup

Discovery and teasers

Billing

Community Review

Errors

Next

​When to use

​The two universes

​Classification

​Recommendations: row-level evidence

​Channel sponsors: the rollup

​Discovery and teasers

​Billing

​Community Review

​Errors

​Next

When to use

The two universes

Classification

Recommendations: row-level evidence

Channel sponsors: the rollup

Discovery and teasers

Billing

Community Review

Errors

Next