Retrieve spoken transcript slices for one topic

Search indexed YouTube and podcast transcripts for short spoken slices. Each result includes spoken text, a watch URL, and a publish date. Scope with channel_ids (or channel) and entity_ids (a person id filters to that person's appearances); narrow to passages about entities with about, to a speaker with by, and to sponsored, organic or mention passages with kind. Every filter takes ids, never names: resolve a name first with GET /v1/entities/resolve, or the call answers 400 id_required naming the parameter. Results carry names beside ids (filters.about, filters.by, chunk about and speakers_by). Use one topic per call. Search results include text on every plan within the plan's publication-date window. Explicitly requesting source=arcmira_premium on a plan without Premium transcripts is refused with filter_requires_paid. An after later than the plan's freshness gate is refused with freshness_requires_paid rather than widened. Uses 4 credits per chunk 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/search

Request

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

Query parameters

qstring required

One topic or phrase. Do not concatenate unrelated names; make one call per topic.

channel_idsstring

Comma-separated YouTube channel ids (UC...), at most 8. Pass every show in scope unless drilling into one. Ids only: a name answers 400 id_required. Resolve names first with GET /v1/entities/resolve.

channelstring

Alias of channel_ids for code-mode clients; the union of both is the scope.

entity_idsstring

Comma-separated entity ids (ent_{n}), at most 8. A person id filters to that person's appearances; a channel id widens channel_ids. Ids only: a name answers 400 id_required. Resolve names first with GET /v1/entities/resolve.

aboutstring

Comma-separated entity ids (ent_{n}), at most 8. Only passages about these entities: excerpt pins, exact-name mentions and ad verdicts. Ids only: a name answers 400 id_required. Resolve names first with GET /v1/entities/resolve.

bystring

Comma-separated person ids (ent_{n}), at most 8. Only passages where one of these people says the query words (each line of a chunk is labeled with its speaker); a non-person id is refused with invalid_query naming its type. Speaker labels cover a minority of shows; an empty result carries a note saying whether the person is labeled anywhere. Ids only: a name answers 400 id_required. Resolve names first with GET /v1/entities/resolve.

kindstring

Comma-separated passage classes: sponsored, organic, mention. Combine with about to read what was said about a brand in ad reads or in organic talk.

afterstring

Only media published at or after this instant. 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.

source'arcmira_premium' | 'creator_captions' | 'third_party_quick'

Restrict to one transcript source class. arcmira_premium on a plan without Premium transcripts is refused with filter_requires_paid.

limitinteger

Chunks to return, 1 to 20. Default 5.

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

querystring required

The q parameter echoed back.

limitinteger required

The limit applied.

returnedinteger required

Chunks returned.

as_ofstring nullable required

Newest published_at among the chunks. Null when there are none.

notestring required

One steering sentence for the agent reading this.

Example response

{
  "query": "Ramp corporate cards",
  "limit": 5,
  "returned": 1,
  "filters": {
    "channel_ids": [
      "UC-DRzaGnL_vtBUpCFH5M0tg"
    ],
    "entity_ids": [],
    "about": [
      {
        "id": "ent_14",
        "name": "Ramp",
        "type": "organization"
      }
    ],
    "by": [],
    "kind": [
      "sponsored"
    ]
  },
  "window": {
    "after": "2026-08-01T00:00:00Z",
    "before": null
  },
  "chunks": [
    {
      "id": "UC-DRzaGnL_vtBUpCFH5M0tg/2026-08-04/dQw4w9WgXcQ.md#12",
      "video_id": "dQw4w9WgXcQ",
      "channel_id": "UC-DRzaGnL_vtBUpCFH5M0tg",
      "channel_name": "TBPN",
      "video_title": "TBPN | Tuesday, August 4",
      "speakers": [
        "John Coogan"
      ],
      "source": "creator_captions",
      "source_label": "Creator captions",
      "published_at": "2026-08-04T17:00:00.000Z",
      "text": "Ramp has been on the show for a while now and the pitch is still the same, spend less time on expenses.",
      "start_seconds": 4787,
      "watch_url": "/watch?v=dQw4w9WgXcQ&t=4787",
      "cite_line": "[TBPN | Tuesday, August 4](/watch?v=dQw4w9WgXcQ&t=4787) · @1:19:47 · TBPN · Aug 4, 2026",
      "score": 0.71,
      "about": [
        {
          "id": "ent_14",
          "name": "Ramp",
          "type": "organization"
        }
      ],
      "speakers_by": [
        {
          "id": "ent_27",
          "name": "John Coogan",
          "type": "person"
        }
      ]
    }
  ],
  "as_of": "2026-08-04T17:00:00.000Z",
  "search_index": {
    "state": "live",
    "missing_before": null
  },
  "note": "Quote text as a spoken beat of a few sentences and cite watch_url with published_at. State the window from window.after when you passed one."
}

Changes

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