Twitter Video Creators API | Find X Video Creators

Commentary Video Creators finds who is posting native video about a topic on X and returns them as a ranked creator list. Pass a query (X search operators work); the endpoint searches one page of native-video posts, groups them by author and ranks each creator by video post count, then median views. Each creator carries their profile, view and reply medians and their top post ids. $0.0008 per call.

curl -X GET "https://example.com/creator/commentary_video?query=ai+agents+lang%3Aen&min_views=10000&product=Top&count=20&fields=id%2Ctext%2Ccreated_at%2Cauthor.username&compact=1"

{  "query": "ai agents lang:en",  "search_query": "ai agents lang:en filter:native_video",  "product": "Top",  "min_views": 10000,  "requested_count": 20,  "effective_count": 20,  "count": 1,  "tweets_scanned": 19,  "tweets_matched": 2,  "skipped": {    "retweet": 1,    "no_video": 0,    "no_author": 0,    "below_min_views": 16  },  "next_cursor": "DAADDAABCgABF...",  "has_more": true,  "ranking": "Creators are ordered by: 1) video_post_count, highest first; 2) median_views, highest first, creators with no reported views last; 3) total_views, highest first; 4) median_reply_count, highest first; 5) user id, numerically ascending, so equal creators always come back in the same order.",  "creators": [    {      "rank": 1,      "user": {        "id": "1281109705495130113",        "username": "agentbuilder",        "name": "Agent Builder",        "followers_count": 48210      },      "video_post_count": 2,      "quote_post_count": 1,      "total_views": 184300,      "views_known": 2,      "median_views": 92150,      "median_reply_count": 41,      "median_quote_count": 6.5,      "top_post_ids": [        "1980112233445566778",        "1979887766554433221"      ]    }  ]}

{  "error": "bad_request",  "message": "Missing or malformed parameter. Fix the request before retrying."}

{  "error": "unauthorized",  "message": "The API key is missing, malformed, or revoked. Check the Authorization header."}

{  "error": "insufficient_credits",  "message": "Your balance is exhausted. Top up your credits to continue."}

{  "error": "forbidden",  "message": "X refused this resource for the acting account: on a read, the account is not a participant in the DM thread, the target is protected or has blocked it, or the session was attestation-blocked for calling from a datacenter or rotating IP; on a write, the account is not authorized for the action or has no logged-in session. The credentials are still valid, so do not re-register."}

{  "error": "not_found",  "message": "The resource does not exist, for example a deleted tweet or a private account."}

{  "error": "rate_limited",  "message": "Too many requests. Back off and retry with exponential backoff."}

{  "error": "server_error",  "message": "Something failed on our side. Retry with backoff; if it persists, contact support."}

Pricing

One $0.0008 read per page, however many creators the page yields. A page whose creators all fall below min_views is still a served page and is billed; skipped.below_min_views says why the list is short.

When to use

Use it to shortlist video creators for a launch or a sponsorship, for example everyone posting native video about AI agents this week with at least 10,000 views. To read the posts themselves rather than the creators, use Advanced Tweet Search with filter:native_video.

Notes

• ONE PAGE PER CALL. A page is usually 13 to 20 posts, so the creator list describes that page, not the whole topic. Walk next_cursor for more.
• The topic is matched by the search itself. After that, only structured fields decide which posts count: has_video, retweet status, the author id and view_count.
• A query over 500 bytes, with filter:native_video added, is refused with a 400 rather than sent, because X answers an over-long search with an empty page that reads like no results.
• An empty creators list is a 200, not a 404: nobody on that page cleared the filters. Read skipped to see why.

Pagination

Each call ranks the creators on ONE search page. Pass next_cursor back as cursor for the next page of the same search and stop when has_more is false. has_more follows the posts on the page, not the creators kept, so keep going on a page that returned zero creators while has_more is true. When merging pages, video_post_count, total_views and views_known add up; the medians do not, so recompute them from the posts if you need them across pages.

Related endpoints

• Advanced Tweet Search: Search tweets with Twitter's full query-operator syntax, paginated with cursors.
• User Search: Find users by keyword across display names and handles.
• User Info by Username: Fetch a full profile by @handle.
• User Media: Page through a profile's media tweets (images and video).

FAQ

How are creators ranked?

By video_post_count, highest first, then median_views (creators with no reported views last), then total_views, then median_reply_count, then user id ascending so ties always come back in the same order. The rule is echoed in every response as ranking.

Does one call cover every post on the topic?

No. Each call ranks the creators on ONE search page, usually 13 to 20 posts. Walk next_cursor to read further pages and merge them yourself: counts and totals add up across pages, medians do not, which is why each creator also carries top_post_ids.

Which posts count toward a creator?

Posts with native video, by an author with an id, that are not retweets, and, when you set min_views, whose reported view count is at least min_views. Every post left out is counted by reason in skipped, so a short list can be told apart from a thin page.

Can I use search operators in query?

Yes. The query passes through as written, so operators such as lang:, since:, min_faves: and from: work as they do on Advanced Tweet Search. filter:native_video is added for you unless you wrote it; -filter:native_video is refused with a 400.