Search a platform

GET /v1/search returns one page of search results inside the request. platform says where to search, and type chooses item rows or account rows.

curl -G https://api.refmatter.com/v1/search \
  -H "Authorization: Bearer $REFMATTER_API_KEY" \
  --data-urlencode "platform=youtube" \
  --data-urlencode "q=solar eclipse" \
  --data-urlencode "type=items" \
  --data-urlencode "sort=relevance" \
  --data-urlencode "maxAge=15m"

const items = await refmatter.search.items({
  platform: 'youtube',
  q: 'solar eclipse',
});
const advertisers = await refmatter.search.accounts({
  platform: 'meta_ad_library',
  q: 'Dot & Key',
  country: 'IN',
});
const ads = await refmatter.items.list({ account: advertisers.data[0]!.id });

The SDK sets type itself: search.items asks for item rows and search.accounts for account rows.

Parameter	Required	Values
`platform`	yes	`youtube`, `meta_ad_library`
`q`	no*	Search phrase, 1 to 200 characters
`type`	no	`items`, `accounts`. Default `items` on YouTube
`uploadDate`	no	`today`, `week`, `month`, `year`; YouTube item searches only
`duration`	no	`short`, `medium`, `long`; YouTube item searches only
`sort`	no	`relevance`, `popular`; YouTube only. Default `relevance`
`country`	no	`ALL`, or a two-letter country code; Ad Library only
`cursor`	no	Opaque cursor from a previous page
`maxAge`	no	`0`, or whole minutes, hours, or days up to `1d`. Default `15m`

platform is always required, on a first page and on a cursor page alike. q is required when cursor is absent. A cursor excludes q, type, and every filter; pass it with platform and nothing else, optionally with maxAge. A cursor that continues another platform’s search is refused with 400 invalid_input and details.reason: "platform_mismatch".

What each platform offers

Platform	`type`	Filters it reads	Rows per page	Paging	`total`	Rows carry	Rows lack
`youtube`	`items`, `accounts` (`items`)	`uploadDate`, `duration`, `sort`	YouTube’s own page	Cursor	An estimate, `totalApproximate: true`	Items: title, `publishedText`, duration, views. Accounts: handle, name, description, avatar, followers	`publishedAt`, likes and comments on items; banner, links, country on accounts
`meta_ad_library`	`accounts` only	`country`	Up to 15	None	The number of rows, `totalApproximate: false`	Page id, page alias, name, picture, like count, page category, the Instagram profile Meta shows, `pageDeleted`	Page description, ad counts, spend
`instagram`	Not available	—	—	—	—	—	—
`tiktok`	Not available	—	—	—	—	—	—

Instagram and TikTok answer 422 unsupported_object: neither publishes a search to a visitor who is not signed in. The Ad Library answers about advertisers only, so type=items on it is refused, and uploadDate, duration, and sort are refused there as well. country on YouTube is refused the same way. Every one of those refusals is 400 invalid_input with details.reason: "not_available_for_platform", details.platform, and a plain details.hint such as sort=popular is not available for meta_ad_library. — never a silently ignored parameter.

Item results

When type=items, the response is an ItemSummaryList.

{
  "object": "list",
  "data": [
    {
      "object": "item_summary",
      "id": "youtube:nA9UZF-SZoQ",
      "platform": "youtube",
      "kind": "video",
      "url": "https://www.youtube.com/watch?v=nA9UZF-SZoQ",
      "author": {
        "object": "account",
        "id": "youtube:UCLA_DiR1FfKNvjuUpBHmylQ",
        "platform": "youtube",
        "handle": "nasa",
        "name": "NASA",
        "url": "https://www.youtube.com/channel/UCLA_DiR1FfKNvjuUpBHmylQ"
      },
      "title": "What is a solar eclipse?",
      "text": null,
      "publishedAt": null,
      "publishedText": "1 day ago",
      "durationMs": 845000,
      "stats": {
        "views": 8881337,
        "likes": null,
        "comments": null,
        "shares": null,
        "saves": null
      },
      "viewsApproximate": false,
      "thumbnails": [],
      "live": false,
      "ad": null
    }
  ],
  "page": { "nextCursor": null, "hasMore": false },
  "total": 2436237,
  "totalApproximate": true,
  "account": null,
  "observedAt": "2026-09-17T12:00:03.120Z",
  "cached": false,
  "usage": { "creditsCharged": 1, "lines": [{ "part": "fetch", "credits": 1 }] }
}

Account results

When type=accounts, the response is an AccountList. A YouTube search answers with channels.

{
  "object": "list",
  "data": [
    {
      "object": "account",
      "id": "youtube:UCLA_DiR1FfKNvjuUpBHmylQ",
      "platform": "youtube",
      "handle": "nasa",
      "name": "NASA",
      "url": "https://www.youtube.com/channel/UCLA_DiR1FfKNvjuUpBHmylQ",
      "description": "NASA's official YouTube channel: live mission coverage, spacewalks, and educational videos about space exploration.",
      "avatar": [
        {
          "url": "https://yt3.ggpht.com/nasa-avatar=s88",
          "width": 88,
          "height": 88,
          "expiresAt": null
        }
      ],
      "verified": true,
      "stats": { "followers": 13400000 },
      "meta_ad_library": null
    }
  ],
  "page": { "nextCursor": null, "hasMore": false },
  "total": 24909,
  "totalApproximate": true,
  "account": null,
  "observedAt": "2026-09-17T12:00:03.120Z",
  "cached": false,
  "usage": { "creditsCharged": 1, "lines": [{ "part": "fetch", "credits": 1 }] }
}

An Ad Library search answers with advertisers, and fills the meta_ad_library block.

{
  "object": "list",
  "data": [
    {
      "object": "account",
      "id": "meta_ad_library:100200300400500",
      "platform": "meta_ad_library",
      "handle": "dotandkey",
      "name": "Dot & Key",
      "url": "https://www.facebook.com/ads/library/?view_all_page_id=100200300400500",
      "description": null,
      "avatar": [
        {
          "url": "https://scontent.xx.fbcdn.net/v/t39.30808-1/100200300400500.jpg",
          "width": null,
          "height": null,
          "expiresAt": null
        }
      ],
      "verified": true,
      "stats": { "followers": 412903 },
      "meta_ad_library": {
        "category": "Beauty, cosmetic & personal care",
        "likes": 412903,
        "instagramHandle": "dotandkey.skincare",
        "instagramFollowers": 688400,
        "instagramVerified": true,
        "pageDeleted": false
      }
    }
  ],
  "page": { "nextCursor": null, "hasMore": false },
  "total": 1,
  "totalApproximate": false,
  "account": null,
  "observedAt": "2026-09-17T12:00:03.120Z",
  "cached": false,
  "usage": { "creditsCharged": 1, "lines": [{ "part": "fetch", "credits": 1 }] }
}

Pass a row’s id straight to List an account’s items as account.

What you get and what you do not

totalApproximate sits next to total and says what the number is. A YouTube search reports true, because YouTube states an estimate that can change between pages. An Ad Library search reports false: the total is the number of rows in the answer. totalApproximate is null whenever total is null. Item search rows include viewsApproximate. The example reports false, so that value is typically exact for that result. The contract still allows true or null, so read the flag instead of assuming precision. Search rows provide relative publishedText; publishedAt is null in the normal search projection. YouTube account rows include id, platform, handle, name, url, description, avatar, verified, and stats.followers. They do not include stats.following or the full account response fields such as banners, links, country, or joined date, and their meta_ad_library is null. An Ad Library row names one advertiser page: its id, the page alias as handle, its name, its Ad Library link, its picture, and its like count as stats.followers. The meta_ad_library block adds the page category, the same like count, the Instagram profile Meta shows beside the page, and pageDeleted for a page that no longer exists but whose ads are still archived. description is null: the suggestion list carries no page description. handle is null for a page that has set no alias. A picture the Ad Library serves from an address we do not read costs that row its avatar, never the page.

Paging

Pass page.nextCursor back as cursor, with the same platform and nothing else, optionally with maxAge. Cursors expire after 24 hours. A cursor is not tied to your workspace, but each workspace pays for the pages it is served. The Ad Library has no cursor. Its own search box offers a short list of suggestions — up to fifteen — and no way to ask for more, so page.nextCursor is always null and page.hasMore is always false. Narrow q, or set country, to see different advertisers.

Freshness

maxAge defaults to 15m and accepts up to 1d. A stored search page confirmed within the window can be served without contacting the platform. Observations are immutable.

`maxAge`	Behavior
`0`	Always search live
`15m`	Default freshness window
`1d`	Maximum accepted freshness window

Credits

Situation	Credits	`cached`
Live page with at least one row	1	`false`
First serving of a stored page with at least one row	1	`false`
Repeat within `maxAge`, served from a stored page	0	`true`
Empty page	0	—
`maxAge=0`: a fresh page every time	1	`false`
Every error	0	—
A successful read whose result could not be written	0	`false`

usage.creditsCharged is the number charged in this response. Errors are always free. At a zero balance a live page answers 402 insufficient_credits before the platform is contacted; a repeat within your maxAge and an empty page are free and keep answering.

Headers

Header	On	Value
`Refmatter-Credits-Charged`	Every response	Integer, `0` whenever nothing was charged
`Refmatter-Credits-Remaining`	Every response	The workspace balance after this response
`Server-Timing`	Successful responses	Durations for phases that ran
`Cache-Control`	Successful responses	`no-store`
`Retry-After`	`429`	Whole seconds

Rate limits

If no platform request can start, the endpoint returns 429 rate_limited with details.retryAfterSeconds. Wait that many seconds before trying again. Errors are free.

Errors

Code	HTTP	Means
`invalid_input`	400	Missing `platform` or `q`, bad `maxAge`, conflicting cursor fields
`invalid_input` with `details.reason=not_available_for_platform`	400	The platform does not read that parameter or that value
`invalid_input` with `details.reason=platform_mismatch`	400	The cursor continues another platform’s search
`invalid_input` with `details.reason=expired_cursor`	400	Cursor expired or its page is no longer available
`invalid_input` with `details.reason=malformed_cursor`	400	Cursor format is invalid
`invalid_input` with `details.reason=invalid_signature`	400	Cursor signature is invalid
`invalid_input` with `details.reason=unsupported_version`	400	Cursor version is not supported
`invalid_input` with `details.reason=no_next_page`	400	The cursor has no next page
`unauthenticated` / `invalid_credential`	401	Missing or invalid credential
`not_found` / `unavailable_removed`	404 / 410	The search page is unavailable
`unsupported_object`	422	That platform publishes no search to a visitor who is not signed in
`unavailable_restricted`	422	The platform will not serve the result publicly
`rate_limited`	429	Try again after `details.retryAfterSeconds`
`source_changed` / `network_transport`	502	The source or upstream connection failed
`route_disabled` / `route_degraded`	503	The route is unavailable
`network_timeout`	504	The search took too long

A phrase that matches nothing is an empty page, not an error, and costs nothing.

From an agent

Use search_items for item rows and search_accounts for account rows; both take platform and q. Pass page.nextCursor as cursor with the same platform. Then pass an advertiser row’s id to list_items as account. All of them return one page synchronously.

Not in this endpoint

This endpoint does not return full item or account responses, an advertiser’s ads, comments, transcripts, or media bytes.

Get started

Item data

Lists, search and comments

Reference library

SDK and agents

Policies

What each platform offers

Item results

Account results

What you get and what you do not

Paging

Freshness

Credits

Headers

Rate limits

Errors

From an agent

Not in this endpoint

Next steps

​What each platform offers

​Item results

​Account results

​What you get and what you do not

​Paging

​Freshness

​Credits

​Headers

​Rate limits

​Errors

​From an agent

​Not in this endpoint

​Next steps

What each platform offers

Item results

Account results

What you get and what you do not

Paging

Freshness

Credits

Headers

Rate limits

Errors

From an agent

Not in this endpoint

Next steps