POST /api/v1/tiktok/video — 1 credit per request
Submit a TikTok video for scraping. This returns the full result bundle — likes, views, comments, shares, saves, and keranjang kuning (basket) status/details — in one call and one credit.
Endpoint
Section titled “Endpoint”| Method | Path | Returns |
|---|---|---|
| POST | /api/v1/tiktok/video |
Everything below in one call |
Request & Response
Section titled “Request & Response”Request body
Section titled “Request body”| Name | Type | Required | Description |
|---|---|---|---|
videoUrl |
string | Yes | A TikTok video or photo post URL (https://www.tiktok.com/@<handle>/video/<id> or /photo/<id>), an embed link, a bare video id, or a share link (vt.tiktok.com, vm.tiktok.com, tiktok.com/t/). Up to 2048 characters, no port. A profile, sound, LIVE or hashtag URL is a 400 that names what it is |
Response body
Section titled “Response body”| Field | Type | Description |
|---|---|---|
requestId |
string | Opaque ID for this request (req_…). Keep it if you plan to resubmit later |
itemId |
string | Resolved TikTok item ID |
status |
string | "success" — the only value a 200 response carries |
coalesced |
boolean | true if this request attached to an already-in-flight job for the same video |
cached |
boolean | true if served from a fresh, previously-scraped result. Free if your key already paid for this target in the last 10 minutes; charged otherwise |
result |
object | likes, views, comments, shares, saves, hasBasket, basketProducts |
finishReason |
string | target-found on a freshly fetched answer; absent on a cached one |
The submit waits for its job to finish, up to 45 seconds, and answers as soon as a result is ready. Only a 200 is ever charged. Anything else — video not found, blocked by TikTok, or the wait ran out — is a 404/403/503 and costs nothing; see Getting Your Result for what to do next.
curl -X POST "https://api.megomi.my.id/api/v1/tiktok/video?url=https://www.tiktok.com/@creator/video/7123456789012345678" \ -H "x-api-key: YOUR_API_KEY"const params = new URLSearchParams({ url: "https://www.tiktok.com/@creator/video/7123456789012345678" });const res = await fetch(`https://api.megomi.my.id/api/v1/tiktok/video?${params}`, { method: "POST", headers: { "x-api-key": process.env.MEGOMI_API_KEY },});const data = await res.json();import requests
res = requests.post( "https://api.megomi.my.id/api/v1/tiktok/video", params={"url": "https://www.tiktok.com/@creator/video/7123456789012345678"}, headers={"x-api-key": "YOUR_API_KEY"},)print(res.json())<?php$url = "https://api.megomi.my.id/api/v1/tiktok/video?" . http_build_query(["url" => "https://www.tiktok.com/@creator/video/7123456789012345678"]);$ch = curl_init($url);curl_setopt($ch, CURLOPT_POST, true);curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: YOUR_API_KEY"]);curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);echo curl_exec($ch);q := url.Values{}q.Set("url", "https://www.tiktok.com/@creator/video/7123456789012345678")req, _ := http.NewRequest("POST", "https://api.megomi.my.id/api/v1/tiktok/video?"+q.Encode(), nil)req.Header.Set("x-api-key", "YOUR_API_KEY")resp, _ := http.DefaultClient.Do(req){ "requestId": "req_9f1kQ3zP7mLxA2dR", "itemId": "7123456789012345678", "status": "success", "coalesced": false, "cached": false, "result": { "likes": 44855, "views": 355687, "comments": 270, "shares": 3100, "saves": 980, "hasBasket": true, "basketProducts": [ { "productId": "1729494515984797858", "title": "Margherita pizza kit", "sellerId": "7000000000000000003", "currency": "USD", "productUrl": "https://www.tiktok.com/view/product/1729494515984797858" } ] }, "finishReason": "target-found", "success": true, "credits_charged": 1, "credits_remaining": 249, "aweme_detail": { "aweme_id": "7123456789012345678", "desc": "Stopped by the viral @Pizza Place #pizza", "desc_language": "en", "region": "US", "create_time": 1737673396, "create_time_utc": "2025-01-23T23:03:16.000Z", "statistics": { "aweme_id": "7123456789012345678", "play_count": 355687, "digg_count": 44855, "comment_count": 270, "share_count": 3100, "collect_count": 980, "repost_count": 0 }, "video": { "duration": 89000, "width": 576, "height": 1024, "ratio": "540p", "cover": { "url_list": [ "https://p16-sign.tiktokcdn-us.com/cover.image" ] }, "origin_cover": { "url_list": [ "https://p16-sign.tiktokcdn-us.com/origin.image" ] }, "play_addr": { "url_list": [ "https://v16-webapp-prime.tiktok.com/video/tos/play/" ] }, "download_addr": { "url_list": [ "https://v16-webapp-prime.tiktok.com/video/tos/download/" ] }, "bit_rate": [ { "bit_rate": 628217, "gear_name": "adapt_lower_720_2", "quality_type": 14, "is_bytevc1": 1, "play_addr": { "uri": "v12044gd0000example", "url_list": [ "https://v16-webapp-prime.tiktok.com/video/tos/720/" ], "width": 720, "height": 1280, "data_size": 7051192, "url_key": "v12044gd0000example_bytevc1_720p_628217", "file_hash": "0123456789abcdef0123456789abcdef", "file_cs": "c:0-75721-0b32" } }, { "bit_rate": 514600, "gear_name": "lower_540_0", "quality_type": 24, "is_bytevc1": 0, "play_addr": { "url_list": [ "https://v16-webapp-prime.tiktok.com/video/tos/540/" ], "width": 576, "height": 1024 } } ] }, "author": { "uid": "7000000000000000001", "unique_id": "creator", "nickname": "Example Creator", "sec_uid": "MS4wLjABAAAAexampleSecUid", "signature": "Example creator bio.", "avatar_thumb": { "url_list": [ "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/thumb.webp" ] }, "avatar_medium": { "url_list": [ "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/medium.webp" ] }, "verification_type": 1, "secret": 0, "follower_count": 4200000, "following_count": 12, "total_favorited": 250000000, "aweme_count": 1500, "favoriting_count": 312, "create_time": 1577836800, "unique_id_modify_time": 1737751061, "comment_setting": 0, "duet_setting": 0, "stitch_setting": 0, "download_setting": 0 }, "is_ad": false, "url": "https://www.tiktok.com/@creator/video/7123456789012345678", "shop_product_url": "https://www.tiktok.com/shop/pdp/1729494515984797858", "group_id": "7123456789012345678", "content_type": "video", "share_url": "https://www.tiktok.com/@creator/video/7123456789012345678", "music": { "id_str": "7123456789012345679", "mid": "7123456789012345679", "title": "original sound - creator", "author": "Example Creator", "duration": 89, "is_original_sound": true, "play_url": { "url_list": [ "https://sf77-ies-music-va.tiktokcdn.com/obj/ies-music-ttp-dup-us/7123456789012345679.mp3" ] }, "cover_large": { "url_list": [ "https://p16-sign-va.tiktokcdn.com/music/large.jpeg" ] }, "is_commerce_music": false, "is_unlimited_music": false, "is_copyrighted": false, "is_private": false, "shoot_duration": 89 }, "added_sound_music_info": { "id_str": "7123456789012345679", "mid": "7123456789012345679", "title": "original sound - creator", "author": "Example Creator", "duration": 89, "is_original_sound": true, "play_url": { "url_list": [ "https://sf77-ies-music-va.tiktokcdn.com/obj/ies-music-ttp-dup-us/7123456789012345679.mp3" ] }, "cover_large": { "url_list": [ "https://p16-sign-va.tiktokcdn.com/music/large.jpeg" ] }, "is_commerce_music": false, "is_unlimited_music": false, "is_copyrighted": false, "is_private": false, "shoot_duration": 89 }, "text_extra": [ { "start": 21, "end": 33, "type": 0, "user_id": "7000000000000000002", "sec_uid": "MS4wLjABAAAAexampleMention" }, { "start": 34, "end": 40, "type": 1, "hashtag_name": "pizza", "hashtag_id": "10087" } ], "cha_list": [ { "cid": "10087", "cha_name": "pizza" } ], "status": { "aweme_id": "7123456789012345678", "allow_share": true, "private_status": 0 }, "item_comment_settings": 0, "item_duet": 0, "item_stitch": 0, "aigc_info": { "created_by_ai": false }, "engagement_rate": 13.83, "shop_products": [ { "product_id": "1729494515984797858", "title": "Margherita pizza kit", "seller_id": "7000000000000000003", "currency": "USD", "source": "TikTok Shop", "cover_url": "https://p16-oec-sg.ibyteimg.com/tos-alisg-i-example-sg/cover~tplv-resize-jpeg:800:800.jpeg", "image_urls": [ "https://p16-oec-sg.ibyteimg.com/tos-alisg-i-example-sg/cover~tplv-resize-jpeg:800:800.jpeg" ], "categories": [ { "category_id": "600001", "name": "Food & Beverages", "level": 1 }, { "category_id": "600002", "name": "Meal Kits", "level": 2 } ], "sku_count": 3, "url": "https://www.tiktok.com/shop/pdp/1729494515984797858", "seo_url": "https://shop-id.tokopedia.com/pdp/margherita-pizza-kit/1729494515984797858" } ], "commerce_metrics_status": "unavailable", "content_desc": "[\"Stopped by the viral @Amici Pizza #pizza\"]", "content_desc_extra": [ { "line_idx": 0, "start": 34, "end": 40, "type": 1, "hashtag_id": "10087", "hashtag_name": "pizza", "is_commerce": false } ], "song": { "id": "7123456789012345679", "title": "original sound - creator", "artist": "Example Creator", "duration": 89, "is_original_sound": true, "cover_url": "https://p16-sign-va.tiktokcdn.com/music/large.jpeg" }, "hashtags": [ { "id": "10087", "name": "pizza", "start": 34, "end": 40 } ] }}{ "status": 400, "title": "Bad Request", "detail": "videoUrl is required" }{ "status": 401, "title": "Unauthorized", "detail": "invalid API key" }{ "status": 402, "title": "Payment Required", "detail": "insufficient credit balance", "required": 1, "balance": 0}{ "status": 403, "title": "Forbidden", "detail": "TikTok answered this video lookup with a captcha challenge; you were not charged. Retry in a few minutes", "requestId": "req_2wYh8LmN5vRtCx1s", "itemId": "7123456789012345678", "finishReason": "captcha-challenge"}{ "status": 404, "title": "Not Found", "detail": "TikTok reports this video does not exist or is not available (deleted, private, or never existed); you were not charged. This answer is cached for an hour", "requestId": "req_5mPq1XwK8jVcT4nR", "finishReason": "tiktok-status-10204"}{ "status": 503, "title": "Service Unavailable", "detail": "no data fetched within 45s; you were not charged. The lookup is still running: submitting the same request again shortly may return it from cache, and is never charged twice", "requestId": "req_1qLr6PxV8nWtE3sJ", "finishReason": "no-data-fetched"}Extended response (optional query parameters)
Section titled “Extended response (optional query parameters)”The request above returns the standard response. Add any query parameter to the same POST /api/v1/tiktok/video call and the response also carries an aweme_detail object: the video’s full detail (caption, language, region, time, statistics, video files, author, sound, hashtags and basket). It is the same one credit, charged only on a 200.
curl -X POST "https://api.megomi.my.id/api/v1/tiktok/video?include_creator=true&include_song=true&include_products=true" \ -H "x-api-key: YOUR_API_KEY" \ -H "content-type: application/json" \ -d '{"videoUrl": "https://www.tiktok.com/@creator/video/7123456789012345678"}'You can also send the video as the url query parameter and no body.
| Query parameter | Adds | Notes |
|---|---|---|
include_creator=true |
tt_seller, commerce_user and is_organization on aweme_detail.author |
Tells you whether the creator is a TikTok Shop seller, a business account or an organization. A creator seen in the last 24 hours is answered from memory |
include_song=true |
user_count on aweme_detail.song |
How many videos use the video’s sound |
include_products=true |
Price (price_min, price_max, in whole rupiah), skus, sold_count, rating, review_count, rating_counts, shop_name, details_fetched_at and gmv_estimate on the first three aweme_detail.shop_products, and a details_status on every product |
Ignored with trim=true |
trim=true |
A smaller aweme_detail |
Keeps the basics, song and hashtags; drops shop_products, engagement_rate and the other long fields |
get_transcript=true |
transcript |
The video’s own captions as WebVTT, or null if it has none |
Accepted values are true, false, 1 and 0; anything else is a 400.
When an option is missing
Section titled “When an option is missing”An answer can come from the cache, or from a fetch that was already under way for someone who did not ask for your option. So that an absent field is not mistaken for “TikTok has none”, the response lists what you asked for and did not get:
"options_unfulfilled": [ { "option": "include_creator", "reason": "not_fetched" }, { "option": "include_products", "reason": "unavailable" }]reason |
Meaning | What to do |
|---|---|---|
not_fetched |
Your answer was shared with a fetch that did not include the option. Never given for include_products |
Ask again after about 10 minutes, once the cached answer expires |
unavailable |
The fetch asked for the option and TikTok did not give it in time | Retry later |
disabled |
The service has switched the option off (include_products only) |
Nothing to do; it returns when switched back on |
The list is absent, not empty, when nothing is missing.
Other fields in the extended response
Section titled “Other fields in the extended response”songandhashtagsare in both the full and thetrim=trueform.hashtagslists the caption’s hashtags in order (id,name,start,end).shop_productslists the products in the video’s basket in the order the video shows them. On its own it has no price, units sold, rating or reviews; those come only withinclude_products=true.commerce_metrics_statusis"unavailable"on every video withshop_products: GPM and the add-to-cart funnel are not provided, nor a GMV reported by TikTok Shop.gmv_estimate(below) is an estimate from our own readings, not that figure.engagement_rateis this video’s(likes + comments + shares + saves) / views * 100, to two decimals. It is absent when views are zero or any count was not reported, and withtrim=true.- A price is the value seen at
details_fetched_at. Do not treat it as a fixed catalog price, and do not multiply it bysold_count, an all-time total, to estimate revenue. cached_atalways has three fractional digits (2026-10-02T09:15:42.381Z).
Product details with include_products
Section titled “Product details with include_products”Only the first three products of a basket are read. Each product in shop_products carries a details_status that says why it does or does not have the numbers:
details_status |
Meaning |
|---|---|
ok |
The numbers are there |
walled |
The marketplace refused to show the page to every connection tried. This usually passes within minutes |
failed |
The page could not be read for another reason |
not_read |
The page was not read: it is past the first three products, the request ran out of time, or another request was reading it at that moment |
A page that could not be read leaves that product’s numbers absent, and absent is not 0. The answer is still a 200. A page read for another request in the last 30 minutes answers yours too, with its own details_fetched_at.
gmv_estimate is on a product only once its page has been read twice, at least an hour apart within 30 days:
"gmv_estimate": { "units_sold": 120, "gmv_min": 4330800, "gmv_max": 4330800, "currency": "IDR", "from": "2026-10-20T03:00:00Z", "to": "2026-10-24T03:00:00Z"}It is an estimate: units_sold is the increase in the page’s units-sold count between two of our readings (from and to), valued at the later reading’s lowest and highest variant price. It covers the product’s sales on every channel, not this video’s. It is absent for a product read for the first time, or when the count went down.