Submit a Video-Detail Job

POST /api/video-jobs/full — 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.

Note

All requests require your Megomi API key, via either the Authorization: Bearer <key> header or the X-API-Key header.

Endpoints

Method	Path	Returns
POST	/api/video-jobs/full	Everything below in one call
POST	/api/video-jobs	Legacy alias of /full — same price, kept for backward compatibility

Tip

Earlier versions of this API exposed per-field endpoints (/likes, /views, /comments, /shares, /saves, /basket-status, /basket-details). Those still exist internally but are restricted to superadmin keys — the public product surface is /full (and its legacy /api/video-jobs alias) only. Every field is included in the full result at no extra cost, so just read the field(s) you need off the response.

Request & Response

Request body

Provide either videoUrl, or both handle and itemId — not a mix of the two.

Name	Type	Required	Description
videoUrl	string	One of videoUrl or handle+itemId	A TikTok video URL
handle	string	One of videoUrl or handle+itemId	Creator handle, without @
itemId	string	One of videoUrl or handle+itemId	TikTok video/item ID
webhookUrl	string	No	If set, Megomi POSTs the finished result here instead of (or in addition to) you polling for it. Must be http:// or https:// and resolve to a public address — loopback, private, and link-local targets are rejected with 400

Response body

Field	Type	Description
requestId	string	Opaque ID for this request (req_…) — not a database index, so it can’t be used to guess how many requests Megomi has served. Keep it if you plan to resubmit later
itemId	string	Resolved TikTok item ID
status	string	queued | processing | success | not-found | blocked | timed-out | cancelled
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
result	object | null	Shape depends on the endpoint called — see below. null until the job resolves
finishReason	string | null	Present once the job reaches a terminal status

Responses come back 200 with a terminal result if the job resolves within 10 seconds. Otherwise 202 — there’s no separate polling endpoint, so from here you either wait for your webhookUrl, or resubmit the exact same request later to get the (by-then-resolved) result inline, at no extra charge.

cURL

curl -X POST "https://api.megomi.com/api/video-jobs/full" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"videoUrl": "https://www.tiktok.com/@creator/video/7123456789012345678"}'

Node.js

const res = await fetch("https://api.megomi.com/api/video-jobs/full", {
  method: "POST",
  headers: {
    "x-api-key": process.env.MEGOMI_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    videoUrl: "https://www.tiktok.com/@creator/video/7123456789012345678",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.megomi.com/api/video-jobs/full",
    json={"videoUrl": "https://www.tiktok.com/@creator/video/7123456789012345678"},
    headers={"x-api-key": "YOUR_API_KEY"},
)
print(res.json())

PHP

<?php
$ch = curl_init("https://api.megomi.com/api/video-jobs/full");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: YOUR_API_KEY", "content-type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "videoUrl" => "https://www.tiktok.com/@creator/video/7123456789012345678",
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($ch);

Go

body, _ := json.Marshal(map[string]string{
    "videoUrl": "https://www.tiktok.com/@creator/video/7123456789012345678",
})
req, _ := http.NewRequest("POST", "https://api.megomi.com/api/video-jobs/full", bytes.NewReader(body))
req.Header.Set("x-api-key", "YOUR_API_KEY")
req.Header.Set("content-type", "application/json")
resp, _ := http.DefaultClient.Do(req)

200 · full

{
  "requestId": "req_9f1kQ3zP7mLxA2dR",
  "itemId": "7123456789012345678",
  "status": "success",
  "coalesced": false,
  "cached": false,
  "result": {
    "likes": 128400,
    "views": 2114500,
    "comments": 3021,
    "shares": 884,
    "saves": 2110,
    "hasBasket": true,
    "basketProducts": [{ "id": "1729...", "title": "..." }]
  },
  "finishReason": null
}

202 · queued

{
  "requestId": "req_7bN0wVh4TzKx9pQe",
  "itemId": "7123456789012345678",
  "status": "queued",
  "coalesced": false,
  "cached": false,
  "result": null
}

400

{ "status": 400, "title": "Bad Request", "detail": "provide either videoUrl, or both handle and itemId" }

401

{ "status": 401, "title": "Unauthorized", "detail": "invalid API key" }

402

{
  "status": 402,
  "title": "Payment Required",
  "detail": "insufficient credit balance",
  "required": 1,
  "balance": 0
}

403 · blocked

{
  "status": 403,
  "title": "Forbidden",
  "detail": "source refused the lookup",
  "requestId": "req_2wYh8LmN5vRtCx1s",
  "itemId": "7123456789012345678",
  "finishReason": "blocked"
}