Look up an account

GET /v1/accounts/lookup returns one YouTube, Instagram, or TikTok account in the same request. There is no job to poll. For one item, see Look up an item.

curl -G https://api.refmatter.com/v1/accounts/lookup \
  -H "Authorization: Bearer $REFMATTER_API_KEY" \
  --data-urlencode "platform=youtube" \
  --data-urlencode "handle=@NASA" \
  --data-urlencode "maxAge=1h"

const byUrl = await refmatter.accounts.lookup('https://www.youtube.com/@NASA');
const byHandle = await refmatter.accounts.lookup({
  platform: 'youtube',
  handle: '@NASA',
});
const instagram = await refmatter.accounts.lookup({
  platform: 'instagram',
  handle: 'nasa',
});
const tiktok = await refmatter.accounts.lookup({
  platform: 'tiktok',
  handle: '@nasa',
});

Parameter	Required	Values
`url`	no	Absolute HTTP(S) YouTube, Instagram, or TikTok account URL
`platform`	no	`youtube`, `instagram`, `tiktok`, when using `handle` or `id`
`handle`	no	Account handle, with or without `@`
`id`	no	24-character YouTube channel id; YouTube only
`maxAge`	no	`0`, or whole minutes, hours, or days up to `1d`. Default `1h`

Use url alone, or platform with exactly one of handle or id. Do not combine naming forms. id names a YouTube channel; Instagram and TikTok take handle. URL-encode query values, as --data-urlencode does.

The account

{
  "object": "account",
  "id": "youtube:UCLA_DiR1FfKNvjuUpBHmylQ",
  "platform": "youtube",
  "handle": "nasa",
  "name": "NASA",
  "description": "NASA's official YouTube channel: live mission coverage, spacewalks, and educational videos about space exploration.",
  "url": "https://www.youtube.com/channel/UCLA_DiR1FfKNvjuUpBHmylQ",
  "avatar": [
    {
      "url": "https://yt3.googleusercontent.com/ytc/nasa-avatar=s176",
      "width": 176,
      "height": 176,
      "expiresAt": null
    }
  ],
  "banner": [
    {
      "url": "https://yt3.googleusercontent.com/ytc/nasa-banner=w1060",
      "width": 1060,
      "height": 175,
      "expiresAt": null
    }
  ],
  "verified": true,
  "stats": {
    "followers": 13400000,
    "following": null,
    "items": 1003,
    "views": 140422111922
  },
  "links": [{ "title": "NASA website", "url": "https://www.nasa.gov" }],
  "country": "United States",
  "joinedAt": "2012-02-19",
  "unavailableFields": ["stats.following"],
  "youtube": { "followersApproximate": true },
  "tiktok": null,
  "instagram": null,
  "meta_ad_library": null,
  "observedAt": "2026-09-17T12:00:03.120Z",
  "cached": false,
  "usage": { "creditsCharged": 1, "lines": [{ "part": "fetch", "credits": 1 }] }
}

Every account carries the same shape. Exactly one of youtube, tiktok, instagram, and meta_ad_library is filled: the block named by platform. unavailableFields lists every core field the platform did not show, so you never have to guess whether a null means zero or means unknown.

What each platform shows

Field	YouTube	Instagram	TikTok
`stats.followers`	Subscribers, often rounded	Followers	Followers
`stats.following`	Not shown	Accounts followed	Accounts followed
`stats.items`	Videos	Posts, from the profile card	Not shown
`stats.views`	Channel views	Not shown	Not shown
`banner`	Channel banner	Not shown	Not shown
`links`	Channel links	Profile links	Not shown
`country`	Channel country	Not shown	Not shown
`joinedAt`	Channel join date	Not shown	Not shown

YouTube

youtube.followersApproximate is true when YouTube reports a rounded subscriber count. YouTube does not show following counts, so stats.following is null and listed in unavailableFields.

Instagram

{
  "object": "account",
  "id": "instagram:528817151",
  "platform": "instagram",
  "handle": "nasa",
  "name": "NASA",
  "description": "Explore the universe and discover our home planet.",
  "url": "https://www.instagram.com/nasa/",
  "avatar": [
    {
      "url": "https://scontent.cdninstagram.com/v/t51.2885-19/nasa-avatar.jpg",
      "width": 320,
      "height": 320,
      "expiresAt": null
    }
  ],
  "banner": [],
  "verified": true,
  "stats": { "followers": 99800000, "following": 79, "items": 4218, "views": null },
  "links": [{ "title": "nasa.gov", "url": "https://www.nasa.gov" }],
  "country": null,
  "joinedAt": null,
  "unavailableFields": ["banner", "stats.views", "country", "joinedAt"],
  "youtube": null,
  "tiktok": null,
  "instagram": { "private": false },
  "meta_ad_library": null,
  "observedAt": "2026-09-17T12:00:03.120Z",
  "cached": false,
  "usage": { "creditsCharged": 1, "lines": [{ "part": "fetch", "credits": 1 }] }
}

stats.items is the posts count the profile card states in words. A card that rounds the figure — “1.2M posts” — states no exact count, so stats.items is null and appears in unavailableFields. stats.views is never shown. Instagram publishes no country or joined date on a public profile, so country and joinedAt are always null. It publishes no category either, so the instagram block carries none. instagram.private says whether the profile is private. A private profile still has a page, and its counts are still shown; its posts are not, so listing its items fails with unavailable_private for it.

TikTok

{
  "object": "account",
  "id": "tiktok:6620168522134503430",
  "platform": "tiktok",
  "handle": "nasa",
  "name": "NASA",
  "description": "Exploring the universe and our home planet.",
  "url": "https://www.tiktok.com/@nasa",
  "avatar": [
    {
      "url": "https://p16-sign.tiktokcdn-us.com/tos-avt/nasa-avatar.jpeg",
      "width": 720,
      "height": 720,
      "expiresAt": null
    }
  ],
  "banner": [],
  "verified": true,
  "stats": { "followers": 4600000, "following": 12, "items": null, "views": null },
  "links": [],
  "country": null,
  "joinedAt": null,
  "unavailableFields": ["banner", "stats.items", "stats.views", "country", "joinedAt"],
  "youtube": null,
  "tiktok": { "likes": 71400000, "private": false },
  "instagram": null,
  "meta_ad_library": null,
  "observedAt": "2026-09-17T12:00:03.120Z",
  "cached": false,
  "usage": { "creditsCharged": 1, "lines": [{ "part": "fetch", "credits": 1 }] }
}

tiktok.likes is the total likes across the account’s videos. TikTok publishes that total in a counter that overflows on a very popular account; an overflowed value is not a count, so tiktok.likes is null rather than a negative number. TikTok shows neither a video count nor a view total, so stats.items and stats.views are null. There is no banner, no links list, no country, and no joined date.

Freshness

maxAge defaults to 1h and accepts up to 1d. A stored account observation confirmed within the window can be served without contacting the platform. Observations are immutable. A later observation records changed public values.

`maxAge`	Behavior
`0`	Always read the account live
`1h`	Default freshness window
`1d`	Maximum accepted freshness window

Credits

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

The charge is for the account page, not for each field. usage.creditsCharged is the number charged in this response. At a zero balance a live lookup answers 402 insufficient_credits before the platform is contacted; a repeat within your maxAge is free and keeps answering from the store.

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	Bad handle, channel id, URL, `maxAge`, unknown parameter, or incorrectly combined naming forms
`unauthenticated` / `invalid_credential`	401	Missing or invalid credential
`policy_blocked`	403	Policy does not allow the request
`not_found`	404	Account or workspace was not found
`unavailable_removed`	410	The account page is gone
`unsupported_object` / `unavailable_private`	422	The account cannot be read 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 public page took too long

Meta Ad Library advertisers are not accounts here. Find them with advertiser search instead.

Naming the same account in a list

This endpoint takes url, or platform with handle or id. List an account’s items takes one account selector instead, in three forms: a natural key such as youtube:UCLA_DiR1FfKNvjuUpBHmylQ or instagram:528817151, <platform>:@handle such as youtube:@NASA, or the account URL. A looked-up account’s own id is already a natural key, so it can be passed straight through as account. See Naming the account for the full grammar, including why a handle always carries its @.

From an agent

The MCP server exposes the same operation as lookup_account. Pass url, or pass platform with one of handle or id. The result is synchronous and includes the same credit fields.

Not in this endpoint

This endpoint returns account metadata. It does not list an account’s items, search results, comments, or media bytes.

Get started

Item data

Lists, search and comments

Reference library

SDK and agents

Policies

Look up an account

The account

What each platform shows

YouTube

Instagram

TikTok

Freshness

Credits

Headers

Rate limits

Errors

Naming the same account in a list

From an agent

Not in this endpoint

Next steps

​The account

​What each platform shows

​YouTube

​Instagram

​TikTok

​Freshness

​Credits

​Headers

​Rate limits

​Errors

​Naming the same account in a list

​From an agent

​Not in this endpoint

​Next steps

The account

What each platform shows

YouTube

Instagram

TikTok

Freshness

Credits

Headers

Rate limits

Errors

Naming the same account in a list

From an agent

Not in this endpoint

Next steps