Look up an item

GET /v1/items/lookup answers with the item itself, not a job to poll. It is the light path next to import: metadata and captions only, no media bytes, no reference created in your library.

curl -G https://api.refmatter.com/v1/items/lookup \
  -H "Authorization: Bearer $REFMATTER_API_KEY" \
  --data-urlencode "url=https://www.tiktok.com/@creator/video/7437269251355921707" \
  --data-urlencode "include=transcript" \
  --data-urlencode "maxAge=1h"

const item = await refmatter.items.lookup(
  'https://www.tiktok.com/@creator/video/7437269251355921707',
  { include: 'transcript', maxAge: '1h' },
);

Parameter	Required	Values
`url`	yes	One absolute `http` or `https` link to a single post, video, short, or ad
`include`	no	`transcript`
`maxAge`	no	`0`, or whole minutes, hours, or days up to `365d`. Default `1h`

URL-encode the url value, as --data-urlencode does. An unencoded & in the link ends the value there, and the rest, such as &t=10s, arrives as a parameter of its own. Parameter names are case-sensitive. An unknown one, such as t or maxage, is refused with invalid_input, details.field naming it and details.reason set to unknown_parameter. A lookup takes 1–6 seconds live, under 0.2 seconds from the store, and never more than 20 seconds. YouTube is read from its watch page in about a second; on the rare page that cannot be read, a slower engine answers instead (about 12 seconds). include=transcript on an item with captions usually refetches them live even within maxAge (see Transcripts), so it takes live time and can come close to the 20-second limit. Call GET /v1/resolve first if you want to know for free whether a link is supported.

The item

{
  "object": "item",
  "id": "tiktok:7437269251355921707",
  "platform": "tiktok",
  "kind": "video",
  "url": "https://www.tiktok.com/@creator/video/7437269251355921707",
  "author": {
    "object": "account",
    "id": "tiktok:6812345678901234567",
    "platform": "tiktok",
    "handle": "creator",
    "name": "Display Name",
    "url": "https://www.tiktok.com/@creator"
  },
  "title": null,
  "text": "caption text #tag",
  "publishedAt": "2026-09-01T10:00:00.000Z",
  "durationMs": 15000,
  "stats": {
    "views": 120000,
    "likes": 5300,
    "comments": 210,
    "shares": 95,
    "saves": 400
  },
  "thumbnails": [
    {
      "url": "https://…",
      "width": 720,
      "height": 1280,
      "expiresAt": "2026-09-18T10:00:00.000Z"
    }
  ],
  "transcript": null,
  "unavailableFields": ["title", "transcript"],
  "ad": null,
  "tiktok": {
    "authorSecUid": "MS4w…",
    "authorVerified": false,
    "reposts": 12,
    "hashtags": ["tag"],
    "music": {
      "id": "7000000000000000003",
      "title": "original sound",
      "authorName": "creator",
      "original": true
    },
    "isAd": false,
    "aiGenerated": false,
    "width": 720,
    "height": 1280,
    "originalLanguage": "en-US",
    "captionLanguages": ["en-US"]
  },
  "instagram": null,
  "youtube": null,
  "observedAt": "2026-09-17T12:00:03.120Z",
  "cached": false,
  "usage": { "creditsCharged": 1, "lines": [{ "part": "fetch", "credits": 1 }] }
}

Two discriminators tell you what to read:

platform names the one platform block that is filled. For a tiktok item, tiktok is an object and instagram and youtube are null. For meta_ad_library all three are null.
ad is filled if and only if kind is ad.

kind is video, short, image, carousel, or ad.

Core and blocks

A field is in the common core only when at least two platforms publish it with the same meaning. Everything else lives in the platform block, so nothing is squeezed into a field it does not fit.

Block	What it adds
`tiktok`	`authorSecUid`, `authorVerified`, `reposts`, `hashtags`, `music`, `isAd`, `aiGenerated`, `width`, `height`, `originalLanguage`, `captionLanguages`
`instagram`	`mediaId`, `productType`, `carouselCount`, `likesHidden`, `hasAudio`, `captionEdited`, `authorVerified`, `width`, `height`, `accessibilityCaption`
`youtube`	`availability`, `liveState`, `captionTracks`, `categories`, `tags`, `channelFollowerCount`, `commentCountApproximate`
`ad`	`archiveId`, `deeplinkId`, `pageId`, `pageName`, `byline`, `active`, `startedAt`, `endedAt`, `platforms`, `displayFormat`, `collationId`, `collationCount`, `creatives`

An Ad Library ad reports publishedAt: null and every stats value null: the library publishes a run window, not a publication date or engagement. The run start is ad.startedAt, and ad.deeplinkId is the id carried by the URL you sent, so you can join the link you had to the item you got.

Unknown values

An unknown value is null, never 0 and never invented. unavailableFields lists, in a fixed order, every core field whose value in this response is unknown:

"stats": { "views": null, "likes": 12, "comments": 0, "shares": null, "saves": null },
"unavailableFields": ["stats.views", "stats.shares", "stats.saves"]

stats.comments is 0 because the source reported zero comments, so it is not listed. transcript is listed only when you asked for one and there is none.

Freshness and maxAge

Refmatter keeps a canonical record of every item it has seen, shared by everyone who asks for it. When it already holds an observation of the item confirmed no longer ago than maxAge, the lookup answers from that record without touching the platform, and observedAt is the time the observation was last confirmed.

`maxAge`	Behavior
`0`	Always fetches live
`30m`	Serves a stored observation confirmed in the last 30 minutes
`1h`	The default
`7d`	Up to `365d` is accepted

An import writes the same observation a lookup does, so a URL your workspace imported five minutes ago is served from the store. A live fetch that finds the item unchanged renews the confirmation time without rewriting history; observations are immutable, and a changed count records a new one. Thumbnail URLs on TikTok, Instagram, and Meta are signed and expire, so they are never stored. A store hit for those platforms returns thumbnails: [] and lists thumbnails in unavailableFields. YouTube thumbnail URLs are stable and are kept. When you need a thumbnail you can rely on, ask with maxAge=0.

Credits

One credit buys one item for your workspace for the length of your maxAge. usage.lines lists only charged parts, and usage.creditsCharged is their sum. At a zero balance a lookup that would charge answers 402 insufficient_credits before the platform is contacted; a repeat within your maxAge is free and keeps answering from the store.

Situation	Credits	`cached`
First lookup of an item by your workspace, live or from the store	1	`false`
Repeat within `maxAge` of your last charge for that item, served from the store	0	`true`
Repeat within `maxAge` of your last charge that needs a live fetch (transcript, stale)	0	`false`
`maxAge=0`: a fresh read every time	1	`false`
Every error: 400, 401, 403, 404, 410, 422, 429, 500, 502, 503, 504	0	—
A fetch that succeeded but could not be written	0	`false`

Consequences worth knowing:

The window is yours. Once your workspace paid for an item, nothing another workspace or an import does to it costs you again within your maxAge: if someone refreshed the item, you are served the newer counts free.
The window is measured from your last charge for the item, with the maxAge of the request you are making. A request with a shorter maxAge than the time since that charge pays again.
Five concurrent repeats of the same stored item charge at most once.
A lookup does not store transcripts, so include=transcript on an item with captions reads the platform again each time. When that read is free for you, it runs at most once a minute per item: a sooner repeat answers 429 rate_limited with retryAfterSeconds. A read you pay for is never refused this way.

Transcripts

include=transcript returns timed text built from the platform’s own captions. There is no speech recognition, and a transcript is never charged on its own: one that turns out to be empty adds nothing to the price of the item.

"transcript": {
  "language": "en",
  "source": "captions",
  "segments": [{ "startMs": 1200, "endMs": 3360, "text": "All right, so here we are" }],
  "text": "All right, so here we are …"
}

source is captions for a human-authored track or automatic_captions for the platform’s speech recognition. Instagram and Meta Ad Library publish no captions, so they always answer transcript: null. When the stored facts say the item has no caption track, the store answers null without a fetch. When the item has captions and none is stored, the lookup refetches them live, free for a workspace that already paid for that observation. A lookup does not keep the transcript. Use import when you want a transcript stored with a reference.

Headers

Header	On	Value
`Refmatter-Credits-Charged`	every response, errors and access refusals included	Integer, `0` whenever nothing was charged
`Refmatter-Credits-Remaining`	every response that named a workspace	The workspace balance after this response
`Server-Timing`	successful responses only	`fetch;dur=…, persist;dur=…, total;dur=…`
`Retry-After`	`429`	Whole seconds
`Cache-Control`	successful responses	`no-store`

Server-Timing omits a phase that did not run, so a store hit carries total alone. A fetch whose result could not be written carries persist;dur=…;desc="failed", and the item comes back with creditsCharged: 0.

Rate limits

Every platform request waits for source capacity first. A lookup waits up to 1.5 seconds for it; if none frees up it answers 429 rate_limited without contacting the platform, free, with an honest wait:

{
  "error": {
    "code": "rate_limited",
    "message": "The operation is temporarily rate limited.",
    "retryable": true,
    "requestId": "01a0b40c-c701-70a9-add2-3e584ed47951",
    "details": { "retryAfterSeconds": 3 }
  }
}

Retry-After carries the same number. Wait it out rather than retrying at once: it is computed from real slot, pace, and cooldown state, so after a platform challenge it can be minutes or hours rather than seconds.

Errors

Every one of these is free and carries Refmatter-Credits-Charged: 0.

Code	HTTP	Means
`invalid_input`	400	Missing or bad `url`, unknown `include` or parameter, invalid `maxAge`
`unauthenticated` / `invalid_credential`	401	No credential, or a key that is invalid, revoked, or expired
`policy_blocked`	403	Policy does not allow this object for the workspace
`not_found`	404	A method other than `GET`, or a workspace your credential cannot reach
`unavailable_removed`	410	The item is gone, or no longer in the Ad Library
`unsupported_object`	422	Not an item link: account, short link, unsupported object, unknown host
`unavailable_private` / `unavailable_restricted`	422	The platform will not serve it publicly
`rate_limited`	429	No source capacity; see `details.retryAfterSeconds`
`source_changed`	502	The platform no longer matches the supported contract
`network_transport`	502	Upstream transport failed
`route_disabled` / `route_degraded`	503	Route closed for the workspace, or a dependency is down
`network_timeout`	504	The 20 second budget ran out

unsupported_object names what you sent and what to do instead:

{
  "code": "unsupported_object",
  "message": "This source object type is not supported.",
  "details": {
    "platform": "instagram",
    "target": "account",
    "hint": "This link names an account. Pass a link to one post, video or ad."
  }
}

The full vocabulary is in Errors.

From an agent

The MCP server exposes the same two operations. lookup_item states its price and latency in its own description, and resolve_url is free, so an agent can check a link before spending anything.

resolve_url  { "url": "https://www.tiktok.com/@creator" }
→ target "account", supported false, reason "account_not_supported"

lookup_item  { "url": "https://www.tiktok.com/@creator/video/7437269251355921707",
               "include": "transcript", "maxAge": "1h" }
→ the item, 1 credit live or on a first store hit

See MCP server for setup.

Not in this endpoint

Media bytes. A lookup never downloads video or audio; use import for that, and for a reference you can annotate and keep.
Short share links (vm.tiktok.com, vt.tiktok.com, tiktok.com/t/…, instagram.com/share/…). Open them once and pass the URL they land on.
TikTok photo posts. The TikTok route serves videos; images and carousels are served through Instagram.
Accounts, lists, and search. Lookup answers one item at a time.

Get started

Item data

Lists, search and comments

Reference library

SDK and agents

Policies

The item

Core and blocks

Unknown values

Freshness and maxAge

Credits

Transcripts

Headers

Rate limits

Errors

From an agent

Not in this endpoint

​The item

​Core and blocks

​Unknown values

​Freshness and maxAge

​Credits

​Transcripts

​Headers

​Rate limits

​Errors

​From an agent

​Not in this endpoint

The item

Core and blocks

Unknown values

Freshness and maxAge

Credits

Transcripts

Headers

Rate limits

Errors

From an agent

Not in this endpoint