> ## Documentation Index
> Fetch the complete documentation index at: https://docs.refmatter.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Look up an account
> One YouTube, Instagram, or TikTok account, returned inside the request.
`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](/guides/look-up-an-item).
```bash curl theme={null}
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"
```
```ts TypeScript theme={null}
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
```json theme={null}
{
"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
```json theme={null}
{
"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](/guides/list-items) fails with `unavailable_private` for it.
### TikTok
```json theme={null}
{
"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](/guides/search) instead.
## Naming the same account in a list
This endpoint takes `url`, or `platform` with `handle` or `id`. [List an account's items](/guides/list-items) takes one `account` selector instead, in three forms: a natural key such as `youtube:UCLA_DiR1FfKNvjuUpBHmylQ` or `instagram:528817151`, `:@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](/guides/list-items#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.
## Next steps
* [Look up an item](/guides/look-up-an-item)
* [List an account's items](/guides/list-items)
* [Search](/guides/search)
* [List comments](/guides/list-comments)
* [Resolve a URL](/guides/resolve-a-url)
* [Scan a competitor's content](/guides/competitor-scan)