Find which shows a brand sponsors
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.arcmira.com/v1/recommendations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.arcmira.com/v1/recommendations"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)curl --request GET \
--url https://api.arcmira.com/v1/recommendations \
--header 'Authorization: Bearer <token>'{
"recommendations": [
{
"id": "<string>",
"class": "sponsored",
"entity": {
"id": "<string>",
"name": "<string>",
"type": "<string>",
"slug": "<string>",
"page": "<string>"
},
"media": {
"video_id": "<string>",
"title": "<string>",
"published_at": "<string>",
"channel_id": "<string>",
"source_channel": {
"id": "<string>",
"name": "<string>"
}
},
"start_seconds": 123,
"end_seconds": 123,
"verbatim_quote": "<string>",
"promo_code": "<string>",
"offer": "<string>",
"sentiment": 123,
"sentiment_score": 123,
"confidence": 123,
"speaker_role": "<string>",
"conflict_status": "<string>",
"resolution": "<string>"
}
],
"has_more": true,
"next_cursor": "<string>",
"entity": {
"id": "<string>",
"canonical_id": "<string>",
"name": "<string>",
"type": "<string>",
"platform": "<string>",
"url": "<string>",
"image_url": "<string>",
"image_checked_at": "<string>",
"owner_entity_id": "<string>",
"is_canonical": true,
"merged_from_id": "<string>",
"slug": "<string>",
"route": "<string>",
"page": "<string>",
"appearances_page": "<string>",
"mentions_page": "<string>",
"appearance_count": 0
},
"window": {
"after": "<string>",
"before": "<string>"
},
"shows": [
{
"channel": {
"id": "<string>",
"youtube_channel_id": "<string>",
"name": "<string>",
"page": "<string>"
},
"ad_reads": 123,
"receipt": {
"video_id": "<string>",
"title": "<string>",
"published_at": "<string>",
"start_seconds": 123,
"verbatim_quote": "<string>",
"watch_url": "<string>"
}
}
],
"meta": {
"count": 123,
"total": 123,
"ad_reads": 123
},
"access": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"reason": "no_credential",
"param": "<string>",
"gate": "rows",
"resource": {
"kind": "media_rows",
"beyond_row": 123
},
"unlock": {
"tier": "<string>",
"url": "<string>",
"offer": null,
"action": {
"kind": "<string>",
"method": "<string>",
"url": "<string>"
}
},
"retry_after_seconds": 123,
"details": {
"quote": {
"quarters": 123,
"rows": 123,
"charge": {
"unit": "rows",
"amount": 123,
"from": "included"
},
"max_on_demand_cents": 123
},
"limit": {
"kind": "plan_credits",
"unit": "credits",
"amount": 123,
"used": 123,
"resets_at": "<string>"
},
"url": "<string>"
}
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"reason": "no_credential",
"param": "<string>",
"gate": "rows",
"resource": {
"kind": "media_rows",
"beyond_row": 123
},
"unlock": {
"tier": "<string>",
"url": "<string>",
"offer": null,
"action": {
"kind": "<string>",
"method": "<string>",
"url": "<string>"
}
},
"retry_after_seconds": 123,
"details": {
"quote": {
"quarters": 123,
"rows": 123,
"charge": {
"unit": "rows",
"amount": 123,
"from": "included"
},
"max_on_demand_cents": 123
},
"limit": {
"kind": "plan_credits",
"unit": "credits",
"amount": 123,
"used": 123,
"resets_at": "<string>"
},
"url": "<string>"
}
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"reason": "no_credential",
"param": "<string>",
"gate": "rows",
"resource": {
"kind": "media_rows",
"beyond_row": 123
},
"unlock": {
"tier": "<string>",
"url": "<string>",
"offer": null,
"action": {
"kind": "<string>",
"method": "<string>",
"url": "<string>"
}
},
"retry_after_seconds": 123,
"details": {
"quote": {
"quarters": 123,
"rows": 123,
"charge": {
"unit": "rows",
"amount": 123,
"from": "included"
},
"max_on_demand_cents": 123
},
"limit": {
"kind": "plan_credits",
"unit": "credits",
"amount": 123,
"used": 123,
"resets_at": "<string>"
},
"url": "<string>"
}
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"reason": "no_credential",
"param": "<string>",
"gate": "rows",
"resource": {
"kind": "media_rows",
"beyond_row": 123
},
"unlock": {
"tier": "<string>",
"url": "<string>",
"offer": null,
"action": {
"kind": "<string>",
"method": "<string>",
"url": "<string>"
}
},
"retry_after_seconds": 123,
"details": {
"quote": {
"quarters": 123,
"rows": 123,
"charge": {
"unit": "rows",
"amount": 123,
"from": "included"
},
"max_on_demand_cents": 123
},
"limit": {
"kind": "plan_credits",
"unit": "credits",
"amount": 123,
"used": 123,
"resets_at": "<string>"
},
"url": "<string>"
}
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"reason": "no_credential",
"param": "<string>",
"gate": "rows",
"resource": {
"kind": "media_rows",
"beyond_row": 123
},
"unlock": {
"tier": "<string>",
"url": "<string>",
"offer": null,
"action": {
"kind": "<string>",
"method": "<string>",
"url": "<string>"
}
},
"retry_after_seconds": 123,
"details": {
"quote": {
"quarters": 123,
"rows": 123,
"charge": {
"unit": "rows",
"amount": 123,
"from": "included"
},
"max_on_demand_cents": 123
},
"limit": {
"kind": "plan_credits",
"unit": "credits",
"amount": 123,
"used": 123,
"resets_at": "<string>"
},
"url": "<string>"
}
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"reason": "no_credential",
"param": "<string>",
"gate": "rows",
"resource": {
"kind": "media_rows",
"beyond_row": 123
},
"unlock": {
"tier": "<string>",
"url": "<string>",
"offer": null,
"action": {
"kind": "<string>",
"method": "<string>",
"url": "<string>"
}
},
"retry_after_seconds": 123,
"details": {
"quote": {
"quarters": 123,
"rows": 123,
"charge": {
"unit": "rows",
"amount": 123,
"from": "included"
},
"max_on_demand_cents": 123
},
"limit": {
"kind": "plan_credits",
"unit": "credits",
"amount": 123,
"used": 123,
"resets_at": "<string>"
},
"url": "<string>"
}
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"reason": "no_credential",
"param": "<string>",
"gate": "rows",
"resource": {
"kind": "media_rows",
"beyond_row": 123
},
"unlock": {
"tier": "<string>",
"url": "<string>",
"offer": null,
"action": {
"kind": "<string>",
"method": "<string>",
"url": "<string>"
}
},
"retry_after_seconds": 123,
"details": {
"quote": {
"quarters": 123,
"rows": 123,
"charge": {
"unit": "rows",
"amount": 123,
"from": "included"
},
"max_on_demand_cents": 123
},
"limit": {
"kind": "plan_credits",
"unit": "credits",
"amount": 123,
"used": 123,
"resets_at": "<string>"
},
"url": "<string>"
}
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"reason": "no_credential",
"param": "<string>",
"gate": "rows",
"resource": {
"kind": "media_rows",
"beyond_row": 123
},
"unlock": {
"tier": "<string>",
"url": "<string>",
"offer": null,
"action": {
"kind": "<string>",
"method": "<string>",
"url": "<string>"
}
},
"retry_after_seconds": 123,
"details": {
"quote": {
"quarters": 123,
"rows": 123,
"charge": {
"unit": "rows",
"amount": 123,
"from": "included"
},
"max_on_demand_cents": 123
},
"limit": {
"kind": "plan_credits",
"unit": "credits",
"amount": 123,
"used": 123,
"resets_at": "<string>"
},
"url": "<string>"
}
}
}Sponsors
Find which shows a brand sponsors
Which shows a brand sponsors, and which recommend or mention it. entity_id is required; resolve a name first with GET /v1/entities/resolve, or the call answers 400 id_required naming the parameter. On a plan below Pro+, it returns the brand’s total shows and ad reads and up to 3 of its top shows by ad-read count in shows, each with one receipt: the newest ad read the plan can open, with start_seconds and a timestamped watch_url. Over MCP this is arcmira.recommendations(entityId) through arcmira_execute_read. On Pro+, cursor-paginated commercial mentions (sponsored, organic and neutral mentions) filtered by entity, channel (channel_id), class, confidence, and publication window [after, before). The signed continuation binds the route, filters, caller and visibility; invalid or old cursors return invalid_cursor. A first-page ID fence excludes later insertions, including old-date backfills. Edits and deletions to existing recommendations remain live. Positions are start_seconds and end_seconds (integer seconds). Below Pro+, recommendations is empty, meta.total and meta.ad_reads are the full counts, ties order by show name in code order, then channel id, and access says how many shows and ad reads the slice left out. Below Pro+, a brand can also return its totals with fewer than three shows, or none: shows is shorter or empty, and access says how many shows and ad reads Pro+ lists. On such a plan cursor, after, before, channel_id, class other than sponsored, min_confidence and include_disputed are refused, and the unlock names Pro+.
GET
/
v1
/
recommendations
Find which shows a brand sponsors
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.arcmira.com/v1/recommendations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.arcmira.com/v1/recommendations"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)curl --request GET \
--url https://api.arcmira.com/v1/recommendations \
--header 'Authorization: Bearer <token>'{
"recommendations": [
{
"id": "<string>",
"class": "sponsored",
"entity": {
"id": "<string>",
"name": "<string>",
"type": "<string>",
"slug": "<string>",
"page": "<string>"
},
"media": {
"video_id": "<string>",
"title": "<string>",
"published_at": "<string>",
"channel_id": "<string>",
"source_channel": {
"id": "<string>",
"name": "<string>"
}
},
"start_seconds": 123,
"end_seconds": 123,
"verbatim_quote": "<string>",
"promo_code": "<string>",
"offer": "<string>",
"sentiment": 123,
"sentiment_score": 123,
"confidence": 123,
"speaker_role": "<string>",
"conflict_status": "<string>",
"resolution": "<string>"
}
],
"has_more": true,
"next_cursor": "<string>",
"entity": {
"id": "<string>",
"canonical_id": "<string>",
"name": "<string>",
"type": "<string>",
"platform": "<string>",
"url": "<string>",
"image_url": "<string>",
"image_checked_at": "<string>",
"owner_entity_id": "<string>",
"is_canonical": true,
"merged_from_id": "<string>",
"slug": "<string>",
"route": "<string>",
"page": "<string>",
"appearances_page": "<string>",
"mentions_page": "<string>",
"appearance_count": 0
},
"window": {
"after": "<string>",
"before": "<string>"
},
"shows": [
{
"channel": {
"id": "<string>",
"youtube_channel_id": "<string>",
"name": "<string>",
"page": "<string>"
},
"ad_reads": 123,
"receipt": {
"video_id": "<string>",
"title": "<string>",
"published_at": "<string>",
"start_seconds": 123,
"verbatim_quote": "<string>",
"watch_url": "<string>"
}
}
],
"meta": {
"count": 123,
"total": 123,
"ad_reads": 123
},
"access": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"reason": "no_credential",
"param": "<string>",
"gate": "rows",
"resource": {
"kind": "media_rows",
"beyond_row": 123
},
"unlock": {
"tier": "<string>",
"url": "<string>",
"offer": null,
"action": {
"kind": "<string>",
"method": "<string>",
"url": "<string>"
}
},
"retry_after_seconds": 123,
"details": {
"quote": {
"quarters": 123,
"rows": 123,
"charge": {
"unit": "rows",
"amount": 123,
"from": "included"
},
"max_on_demand_cents": 123
},
"limit": {
"kind": "plan_credits",
"unit": "credits",
"amount": 123,
"used": 123,
"resets_at": "<string>"
},
"url": "<string>"
}
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"reason": "no_credential",
"param": "<string>",
"gate": "rows",
"resource": {
"kind": "media_rows",
"beyond_row": 123
},
"unlock": {
"tier": "<string>",
"url": "<string>",
"offer": null,
"action": {
"kind": "<string>",
"method": "<string>",
"url": "<string>"
}
},
"retry_after_seconds": 123,
"details": {
"quote": {
"quarters": 123,
"rows": 123,
"charge": {
"unit": "rows",
"amount": 123,
"from": "included"
},
"max_on_demand_cents": 123
},
"limit": {
"kind": "plan_credits",
"unit": "credits",
"amount": 123,
"used": 123,
"resets_at": "<string>"
},
"url": "<string>"
}
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"reason": "no_credential",
"param": "<string>",
"gate": "rows",
"resource": {
"kind": "media_rows",
"beyond_row": 123
},
"unlock": {
"tier": "<string>",
"url": "<string>",
"offer": null,
"action": {
"kind": "<string>",
"method": "<string>",
"url": "<string>"
}
},
"retry_after_seconds": 123,
"details": {
"quote": {
"quarters": 123,
"rows": 123,
"charge": {
"unit": "rows",
"amount": 123,
"from": "included"
},
"max_on_demand_cents": 123
},
"limit": {
"kind": "plan_credits",
"unit": "credits",
"amount": 123,
"used": 123,
"resets_at": "<string>"
},
"url": "<string>"
}
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"reason": "no_credential",
"param": "<string>",
"gate": "rows",
"resource": {
"kind": "media_rows",
"beyond_row": 123
},
"unlock": {
"tier": "<string>",
"url": "<string>",
"offer": null,
"action": {
"kind": "<string>",
"method": "<string>",
"url": "<string>"
}
},
"retry_after_seconds": 123,
"details": {
"quote": {
"quarters": 123,
"rows": 123,
"charge": {
"unit": "rows",
"amount": 123,
"from": "included"
},
"max_on_demand_cents": 123
},
"limit": {
"kind": "plan_credits",
"unit": "credits",
"amount": 123,
"used": 123,
"resets_at": "<string>"
},
"url": "<string>"
}
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"reason": "no_credential",
"param": "<string>",
"gate": "rows",
"resource": {
"kind": "media_rows",
"beyond_row": 123
},
"unlock": {
"tier": "<string>",
"url": "<string>",
"offer": null,
"action": {
"kind": "<string>",
"method": "<string>",
"url": "<string>"
}
},
"retry_after_seconds": 123,
"details": {
"quote": {
"quarters": 123,
"rows": 123,
"charge": {
"unit": "rows",
"amount": 123,
"from": "included"
},
"max_on_demand_cents": 123
},
"limit": {
"kind": "plan_credits",
"unit": "credits",
"amount": 123,
"used": 123,
"resets_at": "<string>"
},
"url": "<string>"
}
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"reason": "no_credential",
"param": "<string>",
"gate": "rows",
"resource": {
"kind": "media_rows",
"beyond_row": 123
},
"unlock": {
"tier": "<string>",
"url": "<string>",
"offer": null,
"action": {
"kind": "<string>",
"method": "<string>",
"url": "<string>"
}
},
"retry_after_seconds": 123,
"details": {
"quote": {
"quarters": 123,
"rows": 123,
"charge": {
"unit": "rows",
"amount": 123,
"from": "included"
},
"max_on_demand_cents": 123
},
"limit": {
"kind": "plan_credits",
"unit": "credits",
"amount": 123,
"used": 123,
"resets_at": "<string>"
},
"url": "<string>"
}
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"reason": "no_credential",
"param": "<string>",
"gate": "rows",
"resource": {
"kind": "media_rows",
"beyond_row": 123
},
"unlock": {
"tier": "<string>",
"url": "<string>",
"offer": null,
"action": {
"kind": "<string>",
"method": "<string>",
"url": "<string>"
}
},
"retry_after_seconds": 123,
"details": {
"quote": {
"quarters": 123,
"rows": 123,
"charge": {
"unit": "rows",
"amount": 123,
"from": "included"
},
"max_on_demand_cents": 123
},
"limit": {
"kind": "plan_credits",
"unit": "credits",
"amount": 123,
"used": 123,
"resets_at": "<string>"
},
"url": "<string>"
}
}
}{
"error": {
"type": "invalid_request_error",
"code": "<string>",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"reason": "no_credential",
"param": "<string>",
"gate": "rows",
"resource": {
"kind": "media_rows",
"beyond_row": 123
},
"unlock": {
"tier": "<string>",
"url": "<string>",
"offer": null,
"action": {
"kind": "<string>",
"method": "<string>",
"url": "<string>"
}
},
"retry_after_seconds": 123,
"details": {
"quote": {
"quarters": 123,
"rows": 123,
"charge": {
"unit": "rows",
"amount": 123,
"from": "included"
},
"max_on_demand_cents": 123
},
"limit": {
"kind": "plan_credits",
"unit": "credits",
"amount": 123,
"used": 123,
"resets_at": "<string>"
},
"url": "<string>"
}
}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Query Parameters
Required range:
1 <= x <= 100Signed continuation from next_cursor. Bound to this route, normalized query, caller and visibility; invalid or old tokens return invalid_cursor.
The entity, as an id like ent_14. Required. Ids only: a name answers 400 id_required. Resolve names first with GET /v1/entities/resolve.
Minimum string length:
1Only media from this YouTube channel id (UC plus 22 characters). Ids only: a name answers 400 id_required. Resolve names first with GET /v1/entities/resolve.
The commercial class to return. Omit for all three. Values: sponsored (an ad-style promotion heard at that moment: a paid sponsor read, promo code, affiliate plug, thanks for supplied goods or venue, or a show promoting its own product as an ad), organic (an unpaid personal recommendation), mention (a neutral commercial mention).
Available options:
sponsored, organic, mention Required range:
0 <= x <= 1Only media published at or after this instant. 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.
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.
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
Newest first. Empty below Pro+, where shows carries the free slice.
Show child attributes
Show child attributes
True when more results exist past this page.
Opaque cursor for the next page. Null on the last page.
The resolved entity the recommendations belong to.
Show child attributes
Show child attributes
The publication window the answer covers, [after, before) in UTC, normalized from after and before.
Show child attributes
Show child attributes
Present below Pro+: up to 3 of the entity's top shows by ad-read count, most first (a tie goes to the show name, then the channel id), each with one receipt.
Show child attributes
Show child attributes
Present with shows: the full counts behind the free slice.
Show child attributes
Show child attributes
The gate that reduced this response. Present only when something was withheld; carries the same code, gate, and unlock an outright refusal would.
Show child attributes
Show child attributes