GET /v1/items returns one page of the items an account published. The account selector names the platform, so one endpoint covers YouTube channels, Instagram profiles, TikTok accounts, and Meta Ad Library advertisers. It returns summaries inside the request. For full item data, see Look up an item.
account is required when cursor is absent. A cursor excludes account and every filter; pass the cursor alone, optionally with maxAge. until must not be earlier than since.
Naming the account
The selector carries the platform, in one of three forms.
A natural key’s id has to match the platform’s own shape:
UC and 22 more characters on YouTube, 1 to 32 digits on Instagram, TikTok, and the Ad Library. A Meta page has no handle, so meta_ad_library:@dotandkey is refused; name the page id or the Ad Library link instead.
A handle always carries its @. youtube:mrbeast is refused with 400 invalid_input, because without the @ a handle cannot be told apart from an id. A bare number or handle that names no platform — 528817151, nasa, @nasa — is refused for the same reason: nothing in it says which platform to read.
Instagram and TikTok list an account by handle, so instagram:<id> and tiktok:<id> are served from the handle last observed for that id. When no observation has named the id yet, the answer is 400 invalid_input with details.reason: "handle_required", asking for the handle or the profile URL. not_found means something else: the platform says the account is gone.
What each platform offers
A parameter the selected platform does not read, and a value outside the enum it does read, are both refused with
400 invalid_input, never silently ignored:
The page
totalApproximate sits next to total and says what the number is: false for an exact count, true for a platform’s own estimate, and null whenever total is null. On this endpoint only the Ad Library states a total, and it is exact.
A row’s id is the same natural key Look up an item gives that item, so a row and a looked-up item are the same object.
What you get and what you do not
Rows are summaries. Use Look up an item for the full item response.YouTube
Views can be rounded, which is marked byviewsApproximate. Channel lists provide relative publishedText; publishedAt is null on these rows.
stats.shares and stats.saves are null on both tabs. When the author turned off like and view counts, a reel row reports null views and likes and still counts comments. publishedText is null: the tabs carry no relative date, so publishedAt is decoded from the media id instead.
TikTok
Rows carry the description, the cover image, and the view count.stats.likes, stats.comments, stats.shares, and stats.saves are null: the public page this endpoint reads states none of them. durationMs is null, and publishedText is null because the page carries no relative date; publishedAt is derived from the video id. A video the author marked private is left out of the page.
Meta Ad Library
One row stands for one variant group, not one ad:ad.collationId names the group and ad.collationCount says how many near-identical ads it holds. total counts the ads that match your filters, so a page of 30 rows under a total of 882 is the expected shape, not a truncated answer.
An ad has a run start, not a publication date. ad.startedAt is when it began running and ad.endedAt is when it stopped, null while it is still running. publishedAt, durationMs, and every field in stats are null: the Ad Library publishes no public engagement counts for an ad.
ad.spend, ad.impressions, ad.reach, and ad.currency appear only where the Ad Library publishes them, which is political and issue ads and EU transparency. Everywhere else they are null. spend and impressions are the bands the library writes, such as $200K - $250K and >1M; a banded reach is not a count and reads as null.
The thumbnail is the ad’s video poster, else its first image, else the first card of its carousel. ad.mediaKind is video, image, carousel, or text, and ad.platforms lists where the ad runs. author.handle is null, because a Meta page has no handle.
Find an advertiser’s page id by name with Search.
Paging
Passpage.nextCursor back as cursor, alone, 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.
Instagram serves twelve rows per page; asking for more returns twelve.
TikTok and the Ad Library have no cursor. The public TikTok page publishes the ten newest videos and nothing behind them, and the Ad Library will not page its own ad list for a visitor who is not signed in, so page.nextCursor is always null and page.hasMore is always false. To follow a TikTok account over time, call the endpoint again later with maxAge=0 and keep the rows you have not seen; the ids are stable. On the Ad Library, narrow instead: since and until cut the list into date ranges, mediaType splits video from image creatives, country limits it to one market, status picks running or stopped ads, and sort=impressions puts the most-seen ads first. When a way to continue either list appears, the endpoint gains a cursor and nothing else changes.
Freshness
maxAge defaults to 15m and accepts up to 1d. A stored page confirmed within the window can be served without contacting the platform. Observations are immutable.
Credits
Each distinct set of filters is its own page and its own charge.
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.
Naming a YouTube account by handle (or an @handle URL) and by its channel id creates two different pages for freshness and credits, so pick one form and use it consistently.
Headers
Rate limits
If no platform request can start, the endpoint returns429 rate_limited with details.retryAfterSeconds. Wait that many seconds before trying again. Errors are free.
Errors
An account with no matching items is an empty page, not an error, and costs nothing.
From an agent
Uselist_items with account for the first page. Pass page.nextCursor as cursor alone for the next page. The tool returns one page synchronously, and refuses a parameter the selected platform does not read rather than ignoring it.
Not in this endpoint
This endpoint does not return full item fields, comments, transcripts, stories, highlights, tagged posts, every creative of an ad, or media bytes. Call Look up an item on a row’surl for the full item, and Import a URL to keep its media.