Skip to main content

The TikTok Research API Will Not Give You an Ads Library

Official eligibility, field lists, and an offline Python request builder. No live TikTok calls.

Updated 12 min readMarkdown
The TikTok Research API Will Not Give You an Ads Library

A brand team that types "tiktok research api" into a search box is usually trying to pull competitor ads into a spreadsheet. That is a reasonable wish. It is also the wrong official product.

TikTok's Research API is part of Research Tools, a programme for qualifying researchers who work on a not-for-profit basis. Access is granted only after an application is approved for a specific project. A developer account is not enough. Creators, advertisers, and other commercial users are not eligible. I do not have approved Research API access, I did not apply, and I did not send a request to TikTok. Everything below is taken from official public documentation I read on 18 November 2026, plus a request builder I tested only against clearly labelled offline fixtures.

If you need competitor-ad fields, those live on a different official surface: the Commercial Content API, which queries the Commercial Content Library repository. That API also requires an approved application, and TikTok's current documentation still limits the data to EU countries. The two APIs do not return the same records, and they do not share the field names a media buyer usually wants.

Four official surfaces, not one

It is easy to flatten these names. The docs do not.

Research Tools, including the Research API, are for public TikTok content and accounts. The codebook, last updated 10 September 2026, describes the unit of analysis for videos as "a public TikTok video posted by a public creator (who is aged 18 and over)." The returned objects include descriptions, hashtags, like and view counts, and similar public metadata. They do not include advertiser payment fields or ad reach bands.

The Commercial Content API is a separate product. TikTok says it was built "towards enhancing transparency on advertisements presented on our platform" and that it lets "the public and researchers" search ads and other commercial content "stored in the Commercial Content Library repository." Those are paid-ad records: first shown date, last shown date, targeting information, and how many people have seen the ad, among other fields.

The Commercial Content Library itself is the repository behind that API. I read the Commercial Content API product page and the Query Ads specification. I did not load the public web library interface in this session, so that UI is outside the claims I can source here.

TikTok Creative Center is a third official web product, used for browsing creative examples. It does not appear in the Research API or Commercial Content API developer pages I read, and I did not find a documented public Creative Center API there. Treat it as a browsing tool until TikTok publishes one.

A fourth family, the Marketing API, manages your own ad accounts. It is not an ads-library API either, and it is outside the scope of this post.

Eligibility is the first constraint

The Research API product page is unambiguous about who may apply. Applicants must be affiliated with an eligible organisation in an eligible region:

  • "Academic institutions in the U.S., EEA, UK, Canada, or Switzerland; or"
  • "Not-for-profit and/or independent research institution, organization, association, or body in the EU," with a beta noted for selected researchers in the U.S., UK, Switzerland, Norway, Iceland, and Liechtenstein
  • "Academic institutions or not-for-profit organizations based in Brazil and looking to study online youth safety."

They must also have relevant expertise, "be independent of commercial interests and able to conduct research on a not-for-profit or non-commercial basis in pursuit of a public-interest mission," disclose funding, submit a defined proposal, show that the requested access is necessary and proportionate, meet security and confidentiality requirements, provide evidence of an ethical review, and agree to the Research Tools Terms of Service. Those terms, on the page I read, apply with effect from 22 January 2026.

The Research API FAQ, last updated 1 September 2026, is even more direct for the audience that usually finds this keyword. Question 6 asks, "I am a creator, advertiser, or commercial user. Am I eligible for access to the Research Tools?" The answer is "No." Question 8 adds, "Your developer account alone is not sufficient to grant you access to Research Tools." You have to meet the eligibility requirements, submit an application, and "be approved for a specific research project."

If an application is approved, TikTok says you can typically expect to hear back within four weeks, then receive a research client key and secret. Access tokens used with the Research API "are set to expire every two hours." None of that is a path I can demonstrate here, because I was not granted those credentials and I did not request them.

What the Research API can return, if you are approved

The Getting Started guide and the Query Videos specification, both last updated 1 September 2026, describe POST https://open.tiktokapis.com/v2/research/video/query/ with the scope research.data.basic. You pass a fields query parameter and a JSON body that looks like a filtered search.

The official field list for that endpoint includes id, video_description, create_time, region_code, share_count, view_count, like_count, comment_count, music_id, hashtag_names, username, effect_ids, playlist_id, voice_to_text, is_stem_verified, favorites_count, video_duration, plus structured lists for hashtags, stickers, effects, mentions, labels, and video_tag. Those are public-content fields. They are useful for academic questions about what was posted. They are a poor substitute for "who paid for this ad, when did it start, and how many unique users saw it."

Query conditions are also documented, and the two official pages do not fully agree. Getting Started lists condition field_name values as keyword, create_date, username, region_code, video_id, hashtag_name, music_id, effect_id, and video_length. Query Videos adds view_count and comment_count. I did not flatten that difference. The builder below accepts the Query Videos list and records a note when you use a field that Getting Started omits.

Two other official limits matter in practice. Query Videos says end_date "must be no more than 30 days after the start_date," with dates in YYYYMMDD. And max_count is documented twice: Query Videos prints "Default is 20, max is 100"; the Getting Started pagination table prints a default of 10 and a max of 100. I encoded the Query Videos default, and I left a note in the builder so the disagreement stays visible.

Quotas are in the FAQ: "Currently, the daily limit is set at 1000 requests per day, allowing you to obtain up to 100,000 records per day across our APIs. (Video and Comments API can return 100 records per request). The daily quota gets reset at 12 AM UTC." A separate higher cap is listed for followers and following lists. TikTok also says it cannot grant quota exceptions, though it will read use cases sent to Research-API@tiktok.com.

The same FAQ is honest about freshness. New videos "take up to 48 hours to be added to the search engine, and statistics such as view count and follower count can take up to 10 days to update." If you were hoping to rank today's live counts, even an approved client is not a live dashboard.

What the Commercial Content API returns instead

The Commercial Content API uses a different path and a different scope: POST https://open.tiktokapis.com/v2/research/adlib/ad/query/ with research.adlib.basic, according to Query Ads, last updated 1 September 2026.

The requested fields on that page are ad.id, ad.first_shown_date, ad.last_shown_date, ad.status, ad.status_statement, ad.videos, ad.image_urls, ad.reach, advertiser.business_id, advertiser.business_name, and advertiser.paid_for_by. Those are the durability and payer fields a brand team usually wants. They are not in the Research API video field list.

Access is not open-ended. The product page says you still create a TikTok for Developers account, complete an application, and wait for a response, "within 2 working days" if the application is complete. It also says, in this phase, "we are ONLY including data from EU countries, while a researcher/ professional who is requesting it can be located in any country." Advertisement-related data "will be accessible for the period when the advertisement is run and until one year since the advertisement was last shown to any user." Query Ads adds that the published-date range min "should be within one year."

Pagination and page size are also different. Research video queries page with cursor plus search_id. Ad queries page with search_id only. Query Ads prints a default max_count of 10 "and the maximum value is 10," which is a tight cap. I encoded that cap as written, rather than assuming it was a typo for 100.

The official pages also disagree with themselves in small ways I left intact. RequestFilters names country_code_list, but the Query Ads request example and the Commercial Content API Getting Started pagination examples use country_code. The Query Ads response example types has_more as the string "true", while the QueryAdData structure types it as a boolean. The example advertiser object uses paid_by and a misspelt buisness_id, while the field list uses advertiser.paid_for_by and advertiser.business_id. A client that pretends those pages are already consistent will hide problems you should see before you apply.

Two stacks of paper on a desk: a report of empty charts on the left, and printed stills of a woman with an unbranded cream tube on the right.

The fields do not overlap

I put the official field lists into a small comparison function and asked, for each name, which schema it belongs to. This is list membership, not a live data result.

like_count                research=True   adlib=False
view_count                research=True   adlib=False
video_description         research=True   adlib=False
ad.first_shown_date       research=False  adlib=True
ad.last_shown_date        research=False  adlib=True
ad.reach                  research=False  adlib=True
advertiser.paid_for_by    research=False  adlib=True

None of those names appears on both lists. If your brief is "give me the ads a brand has been paying to keep live," the Research API video endpoint cannot express that request, even after approval. If your brief is "give me public videos that mention this keyword in this region," the Commercial Content API is the wrong door.

That is the actual comparison worth making. It is a field-list comparison, not a performance benchmark.

An offline request builder

The useful code, given the access constraint, is a builder that refuses illegal requests before anyone is tempted to fire them at TikTok. The module lives next to this draft as tiktok_research_offline.py. It has no live HTTP transport. The Authorization header it emits is the literal placeholder Bearer <offline-placeholder-not-a-token>.

A research video query is assembled like this:

req = build_research_video_query(
    fields=["id", "like_count", "view_count", "username", "video_description"],
    query={
        "and": [
            {"operation": "IN", "field_name": "region_code",
             "field_values": ["US", "CA"]},
            {"operation": "EQ", "field_name": "keyword",
             "field_values": ["hello world"]},
        ]
    },
    start_date="20230101",
    end_date="20230115",
    max_count=2,
)

The builder checks that every requested field is in the Query Videos list, that the query has at least one non-empty and, or, or not list, that dates are YYYYMMDD, and that the window is no more than 30 days. max_count above 100 is rejected. A later page that sets cursor without the search_id from the previous response is rejected. A field such as ad.reach on this endpoint is rejected, because it does not belong there.

The Commercial Content query has a matching function, build_adlib_ad_query. It rejects like_count, rejects a search term longer than 50 characters, and rejects max_count above 10. If you pass country_code instead of country_code_list, it still emits the key you wrote, and it records the official naming split so you can decide which shape to send after approval.

Pagination is then a loop over fixtures, not over the network:

client = OfflineClient({
    "page1": "research_video_page1.json",
    "page2": "research_video_page2.json",
})
pages = paginate_research_offline(client, base_kwargs, ["page1", "page2"])

The second request in the offline walk reused search_id=OFFLINE-SEARCH-001 and cursor=2 from the first fixture. The second page had has_more=False, so the loop stopped. Both transport records were offline-fixture.

Error handling follows the official v2 error object (code, message, log_id). I included fixtures modelled on documented codes: scope_not_authorized (the FAQ says this is what you get if you have not applied and been approved), access_token_invalid, invalid_params, and rate_limit_exceeded. Those fixtures are also labelled offline. They are not responses I received from TikTok.

Three blank paginated sheets with colored tabs laid in a row on a desk, with a pencil and an empty notebook.

What the offline tests actually showed

I ran 18 unit tests on 18 November 2026, all of them local. The command printed this banner first: "OFFLINE TESTS: these results are not TikTok data and not live validation." The suite returned OK.

The tests confirm the documented constraints above, including the 30-day research window, the 100-item research page cap, the 10-item ads-query cap, and the field-list split. They also confirm that an unlabelled JSON file, one missing the required _offline: true marker, is refused by load_fixture. The counts and usernames in the fixtures (fixture_user_alpha, OFFLINE-SEARCH-001, and similar) are fabricated. Please do not treat them as platform measurements.

If you later receive approved access, you can keep the builder and replace the offline client with a transport of your own. That step is not in this repository, on purpose.

When a brand team should stop waiting on this API

If you are a commercial user, the FAQ has already answered the access question. Waiting for a Research API client will not produce Ads Library fields, and it will not make you eligible.

The commercial research job is then a different one: use the official Commercial Content API if you can get that application approved and if EU coverage is enough for the question you are asking, or work from the public Commercial Content Library surfaces TikTok documents for that repository. Brand teams who type tiktok research api into a search box are often trying to study competitor ads, and UGCfy AI, an AI UGC ad generator, publishes a separate guide to the Ads Library and Creative Center as browsing surfaces for that job, without treating either one as a Research API substitute.

Those browsing surfaces are not a complete spend database, and they are not the Research API either.

If you are an eligible academic or nonprofit researcher, the path is the official application, for a defined public-interest project, under the Research Tools terms. The builder above will help you assemble a video query that already respects the published 30-day window, page size, and field lists. It will not, and should not, bypass approval.

About the author

  • Indie developer building AI video and growth tools. I write about generative video models, SEO automation, MCP and shipping Next.js apps.

No comments yet. Be the first to comment.