# 틱톡 키워드 영상 검색 키워드·해시태그로 틱톡 영상을 최대 50개까지 검색해 조회수·좋아요·댓글·공유 수와 작성자 정보를 수집합니다. 인증: Authorization: Bearer $APICK_API_KEY 본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다. 인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다. ## POST /rest/tiktok_search/jobs 응답 필드 - `data` (object): 아래 하위 항목을 확인하세요. - `data.job_id` (string): 아래 하위 항목을 확인하세요. - `data.product` (string): 아래 하위 항목을 확인하세요. - `data.status` (string): 아래 하위 항목을 확인하세요. - `data.max_results` (integer): 아래 하위 항목을 확인하세요. - `data.unit_point` (integer): 아래 하위 항목을 확인하세요. - `data.reserved_point` (integer): 아래 하위 항목을 확인하세요. - `data.charged_point` (integer): 아래 하위 항목을 확인하세요. - `data.result_count` (integer): 아래 하위 항목을 확인하세요. - `data.created_at` (string): 아래 하위 항목을 확인하세요. - `data.completed_at` (string): 아래 하위 항목을 확인하세요. null 허용. - `data.result_expires_at` (string): 아래 하위 항목을 확인하세요. - `data.items` (array): 아래 하위 항목을 확인하세요. - `data.items[].video_id` (string): 아래 하위 항목을 확인하세요. - `data.items[].url` (string): 아래 하위 항목을 확인하세요. - `data.items[].username` (string): 아래 하위 항목을 확인하세요. - `data.items[].description` (string): 아래 하위 항목을 확인하세요. - `data.items[].posted_at` (string): 아래 하위 항목을 확인하세요. - `data.items[].views` (integer): 아래 하위 항목을 확인하세요. - `data.items[].likes` (integer): 아래 하위 항목을 확인하세요. - `data.items[].comments` (integer): 아래 하위 항목을 확인하세요. - `data.items[].shares` (integer): 아래 하위 항목을 확인하세요. - `data.items[].saves` (integer): 아래 하위 항목을 확인하세요. - `data.items[].duration_sec` (integer): 아래 하위 항목을 확인하세요. - `data.items[].hashtags` (array): 아래 하위 항목을 확인하세요. - `data.items[].region` (string): 아래 하위 항목을 확인하세요. - `data.items[].cover_image_url` (string): 아래 하위 항목을 확인하세요. - `data.items[].author` (object): 아래 하위 항목을 확인하세요. - `data.items[].author.followers` (integer): 아래 하위 항목을 확인하세요. - `data.items[].author.is_verified` (boolean): 아래 하위 항목을 확인하세요. - `data.result_expired` (boolean): 아래 하위 항목을 확인하세요. - `api` (object): 아래 하위 항목을 확인하세요. - `api.success` (boolean): 아래 하위 항목을 확인하세요. - `api.cost` (integer): 아래 하위 항목을 확인하세요. ## 작업 접수: POST /rest/tiktok_search/jobs ### 입력 - `keyword` (string, 필수): 검색어 또는 해시태그 (예: 캠핑 요리, #캠핑, 1~100자) - `max_results` (string, 선택): 최대 결과 수 1~50 (기본 10). 이 수만큼 포인트를 먼저 예약하고 실제 건수만 차감 - `idempotency_key` (string, 선택): 응답을 못 받아 다시 보낼 때 같은 접수로 처리할 키(8~128자, 영문·숫자·_.:-) ### 응답 명세 ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "job_id": { "type": "string" }, "product": { "type": "string" }, "status": { "type": "string" }, "max_results": { "type": "integer" }, "unit_point": { "type": "integer" }, "reserved_point": { "type": "integer" }, "charged_point": { "type": "integer" }, "result_count": { "type": "integer" }, "created_at": { "type": "string" }, "completed_at": { "type": "string", "nullable": true }, "result_expires_at": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "video_id": { "type": "string" }, "url": { "type": "string" }, "username": { "type": "string" }, "description": { "type": "string" }, "posted_at": { "type": "string" }, "views": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "saves": { "type": "integer" }, "duration_sec": { "type": "integer" }, "hashtags": { "type": "array", "items": { "type": "string" } }, "region": { "type": "string" }, "cover_image_url": { "type": "string" }, "author": { "type": "object", "properties": { "followers": { "type": "integer" }, "is_verified": { "type": "boolean" } } } } } }, "result_expired": { "type": "boolean" } } }, "api": { "type": "object", "properties": { "success": { "type": "boolean" }, "cost": { "type": "integer" } } } } } ``` ### 정적 응답 예시 ```json { "data": { "job_id": "5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5", "product": "tiktok_search", "status": "processing", "max_results": 10, "unit_point": 5, "reserved_point": 50, "charged_point": 0, "result_count": 0, "created_at": "2026-10-06T10:00:00.000Z", "completed_at": null }, "api": { "success": true, "cost": 50 } } ``` ### 정적 응답 예시 ```json { "data": { "job_id": "5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5", "product": "tiktok_search", "status": "completed", "max_results": 10, "unit_point": 5, "reserved_point": 0, "charged_point": 5, "result_count": 1, "created_at": "2026-10-06T10:00:00.000Z", "completed_at": "2026-10-06T10:01:12.000Z", "result_expires_at": "2026-10-09T10:01:12.000Z", "items": [ { "video_id": "7473282881658309895", "url": "https://www.tiktok.com/@camper.muka/video/7473282881658309895", "username": "camper.muka", "description": "이번 주 캠핑요리 종결해드릴게요 ...", "posted_at": "2026-02-20T09:00:00.000Z", "views": 120000, "likes": 5400, "comments": 88, "shares": 120, "saves": 900, "duration_sec": 59, "hashtags": [ "캠핑요리" ], "region": "KR", "cover_image_url": "https://p16-sign.tiktokcdn.com/...", "author": { "followers": 45000, "is_verified": false } } ], "result_expired": false }, "api": { "success": true, "cost": 0 } } ``` ### curl ```curl curl --fail-with-body --request POST 'https://apick.app/rest/tiktok_search/jobs' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form-string 'keyword=캠핑 요리' \ --form-string 'max_results=10' ``` ### Node.js (서버 ESM) ```javascript const form = new FormData(); form.append("keyword", "캠핑 요리"); form.append("max_results", "10"); const response = await fetch("https://apick.app/rest/tiktok_search/jobs", { method: "POST", headers: { Authorization: "Bearer " + process.env.APICK_API_KEY }, body: form, signal: AbortSignal.timeout(120_000), }); if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`); const result = await response.json(); console.log(result); ``` ### python ```python import os import requests parts = [ ("keyword", (None, "캠핑 요리")), ("max_results", (None, "10")), ] response = requests.request("POST", "https://apick.app/rest/tiktok_search/jobs", headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]}, files=parts, timeout=(10, 120)) response.raise_for_status() result = response.json() print(result) ``` ### php ```php '캠핑 요리', 'max_results' => '10', ]; $curl = curl_init('https://apick.app/rest/tiktok_search/jobs'); curl_setopt_array($curl, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => $headers, CURLOPT_POSTFIELDS => $form, CURLOPT_RETURNTRANSFER => true, CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120, ]); $body = curl_exec($curl); if ($body === false) { throw new RuntimeException(curl_error($curl)); } $status = curl_getinfo($curl, CURLINFO_HTTP_CODE); curl_close($curl); if ($status >= 400) { throw new RuntimeException($body); } $result = json_decode($body, true, 512, JSON_THROW_ON_ERROR); print_r($result); ``` ## GET /rest/scrape_jobs/5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5 응답 필드 - `data` (object): 아래 하위 항목을 확인하세요. - `data.job_id` (string): 아래 하위 항목을 확인하세요. - `data.product` (string): 아래 하위 항목을 확인하세요. - `data.status` (string): 아래 하위 항목을 확인하세요. - `data.max_results` (integer): 아래 하위 항목을 확인하세요. - `data.unit_point` (integer): 아래 하위 항목을 확인하세요. - `data.reserved_point` (integer): 아래 하위 항목을 확인하세요. - `data.charged_point` (integer): 아래 하위 항목을 확인하세요. - `data.result_count` (integer): 아래 하위 항목을 확인하세요. - `data.created_at` (string): 아래 하위 항목을 확인하세요. - `data.completed_at` (string): 아래 하위 항목을 확인하세요. null 허용. - `data.result_expires_at` (string): 아래 하위 항목을 확인하세요. - `data.items` (array): 아래 하위 항목을 확인하세요. - `data.items[].video_id` (string): 아래 하위 항목을 확인하세요. - `data.items[].url` (string): 아래 하위 항목을 확인하세요. - `data.items[].username` (string): 아래 하위 항목을 확인하세요. - `data.items[].description` (string): 아래 하위 항목을 확인하세요. - `data.items[].posted_at` (string): 아래 하위 항목을 확인하세요. - `data.items[].views` (integer): 아래 하위 항목을 확인하세요. - `data.items[].likes` (integer): 아래 하위 항목을 확인하세요. - `data.items[].comments` (integer): 아래 하위 항목을 확인하세요. - `data.items[].shares` (integer): 아래 하위 항목을 확인하세요. - `data.items[].saves` (integer): 아래 하위 항목을 확인하세요. - `data.items[].duration_sec` (integer): 아래 하위 항목을 확인하세요. - `data.items[].hashtags` (array): 아래 하위 항목을 확인하세요. - `data.items[].region` (string): 아래 하위 항목을 확인하세요. - `data.items[].cover_image_url` (string): 아래 하위 항목을 확인하세요. - `data.items[].author` (object): 아래 하위 항목을 확인하세요. - `data.items[].author.followers` (integer): 아래 하위 항목을 확인하세요. - `data.items[].author.is_verified` (boolean): 아래 하위 항목을 확인하세요. - `data.result_expired` (boolean): 아래 하위 항목을 확인하세요. - `api` (object): 아래 하위 항목을 확인하세요. - `api.success` (boolean): 아래 하위 항목을 확인하세요. - `api.cost` (integer): 아래 하위 항목을 확인하세요. ## 상태·목록 조회: GET /rest/scrape_jobs/5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5 ### 입력 ### 응답 명세 ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "job_id": { "type": "string" }, "product": { "type": "string" }, "status": { "type": "string" }, "max_results": { "type": "integer" }, "unit_point": { "type": "integer" }, "reserved_point": { "type": "integer" }, "charged_point": { "type": "integer" }, "result_count": { "type": "integer" }, "created_at": { "type": "string" }, "completed_at": { "type": "string", "nullable": true }, "result_expires_at": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "video_id": { "type": "string" }, "url": { "type": "string" }, "username": { "type": "string" }, "description": { "type": "string" }, "posted_at": { "type": "string" }, "views": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "saves": { "type": "integer" }, "duration_sec": { "type": "integer" }, "hashtags": { "type": "array", "items": { "type": "string" } }, "region": { "type": "string" }, "cover_image_url": { "type": "string" }, "author": { "type": "object", "properties": { "followers": { "type": "integer" }, "is_verified": { "type": "boolean" } } } } } }, "result_expired": { "type": "boolean" } } }, "api": { "type": "object", "properties": { "success": { "type": "boolean" }, "cost": { "type": "integer" } } } } } ``` ### 정적 응답 예시 ```json { "data": { "job_id": "5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5", "product": "tiktok_search", "status": "processing", "max_results": 10, "unit_point": 5, "reserved_point": 50, "charged_point": 0, "result_count": 0, "created_at": "2026-10-06T10:00:00.000Z", "completed_at": null }, "api": { "success": true, "cost": 50 } } ``` ### 정적 응답 예시 ```json { "data": { "job_id": "5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5", "product": "tiktok_search", "status": "completed", "max_results": 10, "unit_point": 5, "reserved_point": 0, "charged_point": 5, "result_count": 1, "created_at": "2026-10-06T10:00:00.000Z", "completed_at": "2026-10-06T10:01:12.000Z", "result_expires_at": "2026-10-09T10:01:12.000Z", "items": [ { "video_id": "7473282881658309895", "url": "https://www.tiktok.com/@camper.muka/video/7473282881658309895", "username": "camper.muka", "description": "이번 주 캠핑요리 종결해드릴게요 ...", "posted_at": "2026-02-20T09:00:00.000Z", "views": 120000, "likes": 5400, "comments": 88, "shares": 120, "saves": 900, "duration_sec": 59, "hashtags": [ "캠핑요리" ], "region": "KR", "cover_image_url": "https://p16-sign.tiktokcdn.com/...", "author": { "followers": 45000, "is_verified": false } } ], "result_expired": false }, "api": { "success": true, "cost": 0 } } ``` ### curl ```curl curl --fail-with-body --request GET 'https://apick.app/rest/scrape_jobs/5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5' \ --header "Authorization: Bearer $APICK_API_KEY" ``` ### Node.js (서버 ESM) ```javascript const response = await fetch("https://apick.app/rest/scrape_jobs/5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5", { method: "GET", headers: { Authorization: "Bearer " + process.env.APICK_API_KEY }, signal: AbortSignal.timeout(120_000), }); if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`); const result = await response.json(); console.log(result); ``` ### python ```python import os import requests response = requests.request("GET", "https://apick.app/rest/scrape_jobs/5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5", headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]}, timeout=(10, 120)) response.raise_for_status() result = response.json() print(result) ``` ### php ```php 'GET', CURLOPT_HTTPHEADER => $headers, CURLOPT_RETURNTRANSFER => true, CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120, ]); $body = curl_exec($curl); if ($body === false) { throw new RuntimeException(curl_error($curl)); } $status = curl_getinfo($curl, CURLINFO_HTTP_CODE); curl_close($curl); if ($status >= 400) { throw new RuntimeException($body); } $result = json_decode($body, true, 512, JSON_THROW_ON_ERROR); print_r($result); ``` ## GET /rest/scrape_jobs/:job_id 응답 필드 - `data` (object): 아래 하위 항목을 확인하세요. - `data.job_id` (string): 아래 하위 항목을 확인하세요. - `data.product` (string): 아래 하위 항목을 확인하세요. - `data.status` (string): 아래 하위 항목을 확인하세요. - `data.max_results` (integer): 아래 하위 항목을 확인하세요. - `data.unit_point` (integer): 아래 하위 항목을 확인하세요. - `data.reserved_point` (integer): 아래 하위 항목을 확인하세요. - `data.charged_point` (integer): 아래 하위 항목을 확인하세요. - `data.result_count` (integer): 아래 하위 항목을 확인하세요. - `data.created_at` (string): 아래 하위 항목을 확인하세요. - `data.completed_at` (string): 아래 하위 항목을 확인하세요. null 허용. - `data.result_expires_at` (string): 아래 하위 항목을 확인하세요. - `data.items` (array): 아래 하위 항목을 확인하세요. - `data.items[].video_id` (string): 아래 하위 항목을 확인하세요. - `data.items[].url` (string): 아래 하위 항목을 확인하세요. - `data.items[].username` (string): 아래 하위 항목을 확인하세요. - `data.items[].description` (string): 아래 하위 항목을 확인하세요. - `data.items[].posted_at` (string): 아래 하위 항목을 확인하세요. - `data.items[].views` (integer): 아래 하위 항목을 확인하세요. - `data.items[].likes` (integer): 아래 하위 항목을 확인하세요. - `data.items[].comments` (integer): 아래 하위 항목을 확인하세요. - `data.items[].shares` (integer): 아래 하위 항목을 확인하세요. - `data.items[].saves` (integer): 아래 하위 항목을 확인하세요. - `data.items[].duration_sec` (integer): 아래 하위 항목을 확인하세요. - `data.items[].hashtags` (array): 아래 하위 항목을 확인하세요. - `data.items[].region` (string): 아래 하위 항목을 확인하세요. - `data.items[].cover_image_url` (string): 아래 하위 항목을 확인하세요. - `data.items[].author` (object): 아래 하위 항목을 확인하세요. - `data.items[].author.followers` (integer): 아래 하위 항목을 확인하세요. - `data.items[].author.is_verified` (boolean): 아래 하위 항목을 확인하세요. - `data.result_expired` (boolean): 아래 하위 항목을 확인하세요. - `api` (object): 아래 하위 항목을 확인하세요. - `api.success` (boolean): 아래 하위 항목을 확인하세요. - `api.cost` (integer): 아래 하위 항목을 확인하세요. ## 상태·목록 조회: GET /rest/scrape_jobs/:job_id ### 입력 ### 응답 명세 ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "job_id": { "type": "string" }, "product": { "type": "string" }, "status": { "type": "string" }, "max_results": { "type": "integer" }, "unit_point": { "type": "integer" }, "reserved_point": { "type": "integer" }, "charged_point": { "type": "integer" }, "result_count": { "type": "integer" }, "created_at": { "type": "string" }, "completed_at": { "type": "string", "nullable": true }, "result_expires_at": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "video_id": { "type": "string" }, "url": { "type": "string" }, "username": { "type": "string" }, "description": { "type": "string" }, "posted_at": { "type": "string" }, "views": { "type": "integer" }, "likes": { "type": "integer" }, "comments": { "type": "integer" }, "shares": { "type": "integer" }, "saves": { "type": "integer" }, "duration_sec": { "type": "integer" }, "hashtags": { "type": "array", "items": { "type": "string" } }, "region": { "type": "string" }, "cover_image_url": { "type": "string" }, "author": { "type": "object", "properties": { "followers": { "type": "integer" }, "is_verified": { "type": "boolean" } } } } } }, "result_expired": { "type": "boolean" } } }, "api": { "type": "object", "properties": { "success": { "type": "boolean" }, "cost": { "type": "integer" } } } } } ``` ### 정적 응답 예시 ```json { "data": { "job_id": "5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5", "product": "tiktok_search", "status": "processing", "max_results": 10, "unit_point": 5, "reserved_point": 50, "charged_point": 0, "result_count": 0, "created_at": "2026-10-06T10:00:00.000Z", "completed_at": null }, "api": { "success": true, "cost": 50 } } ``` ### 정적 응답 예시 ```json { "data": { "job_id": "5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5", "product": "tiktok_search", "status": "completed", "max_results": 10, "unit_point": 5, "reserved_point": 0, "charged_point": 5, "result_count": 1, "created_at": "2026-10-06T10:00:00.000Z", "completed_at": "2026-10-06T10:01:12.000Z", "result_expires_at": "2026-10-09T10:01:12.000Z", "items": [ { "video_id": "7473282881658309895", "url": "https://www.tiktok.com/@camper.muka/video/7473282881658309895", "username": "camper.muka", "description": "이번 주 캠핑요리 종결해드릴게요 ...", "posted_at": "2026-02-20T09:00:00.000Z", "views": 120000, "likes": 5400, "comments": 88, "shares": 120, "saves": 900, "duration_sec": 59, "hashtags": [ "캠핑요리" ], "region": "KR", "cover_image_url": "https://p16-sign.tiktokcdn.com/...", "author": { "followers": 45000, "is_verified": false } } ], "result_expired": false }, "api": { "success": true, "cost": 0 } } ``` ### curl ```curl curl --fail-with-body --request GET "https://apick.app/rest/scrape_jobs/${APICK_JOB_ID}" \ --header "Authorization: Bearer $APICK_API_KEY" ``` ### Node.js (서버 ESM) ```javascript const response = await fetch(`https://apick.app/rest/scrape_jobs/${encodeURIComponent(process.env.APICK_JOB_ID)}`, { method: "GET", headers: { Authorization: "Bearer " + process.env.APICK_API_KEY }, signal: AbortSignal.timeout(120_000), }); if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`); const result = await response.json(); console.log(result); ``` ### python ```python import os import requests from urllib.parse import quote response = requests.request("GET", "https://apick.app" + "/rest/scrape_jobs/{job_id}".format(job_id=quote(os.environ["APICK_JOB_ID"], safe="")), headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]}, timeout=(10, 120)) response.raise_for_status() result = response.json() print(result) ``` ### php ```php 'GET', CURLOPT_HTTPHEADER => $headers, CURLOPT_RETURNTRANSFER => true, CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120, ]); $body = curl_exec($curl); if ($body === false) { throw new RuntimeException(curl_error($curl)); } $status = curl_getinfo($curl, CURLINFO_HTTP_CODE); curl_close($curl); if ($status >= 400) { throw new RuntimeException($body); } $result = json_decode($body, true, 512, JSON_THROW_ON_ERROR); print_r($result); ``` ## 코드·오류 ## 상세 기능·요금 지원 API 요약 수집 작업은 접수한 뒤 상태를 조회해 결과를 받는 흐름입니다. 접수할 때 max_results 만큼 포인트를 예약하고, 완료되면 실제로 받은 결과 건수만큼만 차감한 뒤 나머지를 바로 돌려드립니다. 대상을 찾지 못하거나 실패하면 예약한 포인트를 모두 돌려드립니다. Method API entry point 기능 성공 결과 POST /rest/tiktok_search/jobs 수집 작업 접수 HTTP 202와 job_id GET /rest/scrape_jobs/{job_id} 작업 상태·결과 조회(무료) HTTP 200과 현재 상태·결과 1. 작업 접수 Header 이름 필수 설명 Authorization O Bearer 인증키 요청 항목 · multipart/form-data 이름 타입 필수 설명 keyword String O 검색어 또는 해시태그 (예: 캠핑 요리, #캠핑, 1~100자) max_results Integer X 최대 결과 수 1~50 (기본 10) idempotency_key String X 응답을 못 받아 다시 보낼 때 같은 접수로 처리할 키. 영문·숫자·_.:-, 8~128자 진행 중인 작업은 계정당 최대 5개입니다. 공개 영상만 수집합니다. 검색 결과 순서는 틱톡 검색 순서를 따릅니다. ## 상세 코드·정책 2. 상태·결과 조회 GET /rest/scrape_jobs/{job_id} 를 5~10초 간격으로 호출해 status 가 completed 또는 failed 가 될 때까지 확인합니다. 보통 1~3분 안에 끝납니다. 조회는 무료이며, 완료되면 이 조회에서 정산이 끝납니다. Body (data) 이름 타입 설명 job_id String 작업 ID (32자리). 상태·결과 조회에 씁니다 product String 수집 상품 이름 status String waiting · processing · completed · failed max_results Integer 요청한 최대 결과 수 unit_point Integer 결과 1건당 포인트(이 작업에 적용된 단가) reserved_point Integer 현재 예약 중인 포인트. 완료·실패하면 0 charged_point Integer 최종 차감 포인트(완료 시 결과 건수 × 단가) result_count Integer 받은 결과 수 created_at String 접수 시각 (ISO 8601) completed_at String 완료 시각. 진행 중이면 null items Array 수집 결과(완료 시). 각 항목의 필드는 아래 표 video_id String 영상 ID url String 영상 주소 username String 작성자 사용자명 description String 설명 posted_at String 게시 시각 views Integer 조회수 likes Integer 좋아요 수 comments Integer 댓글 수 shares Integer 공유 수 saves Integer 저장 수 duration_sec Number 영상 길이(초) hashtags Array 해시태그 region String 지역 코드 cover_image_url String 표지 이미지 author Object { followers, is_verified } result_expires_at String 결과 보관 기한(완료 후 72시간) result_expired Boolean 보관 기한이 지나 결과를 지웠으면 true error Object 실패 시 { code, message } 오류 코드 HTTP error_code 설명 400 SCRAPE_INPUT_INVALID 입력 형식 또는 max_results 범위 오류. 상류를 호출하지 않으며 포인트는 차감되지 않습니다 402 SCRAPE_POINTS_INSUFFICIENT max_results 만큼의 포인트가 부족합니다 403 SCRAPE_PAYMENT_REQUIRED 충전 이력이 있는 계정만 이용할 수 있습니다 404 SCRAPE_JOB_NOT_FOUND 작업이 없거나 다른 계정의 작업입니다 409 SCRAPE_IDEMPOTENCY_CONFLICT 같은 idempotency_key 로 다른 내용을 접수했습니다 429 SCRAPE_TOO_MANY_JOBS 진행 중인 작업이 5개입니다. 끝난 뒤 다시 접수해 주세요 503 SCRAPE_TEMPORARILY_UNAVAILABLE 일시적으로 접수하지 못했습니다. 포인트는 차감되지 않습니다 작업 실패 TARGET_NOT_FOUND · TARGET_PRIVATE · SCRAPE_TIMEOUT · SCRAPE_FAILED 상태 조회의 error.code. 예약한 포인트는 모두 돌려드립니다 ## 상세 예제 접수 요청 form-data 전체 예제 보기 접수 응답 (HTTP 202) { "data": { "job_id": "5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5", "product": "tiktok_search", "status": "processing", "max_results": 10, "unit_point": 5, "reserved_point": 50, "charged_point": 0, "result_count": 0, "created_at": "2026-10-06T10:00:00.000Z", "completed_at": null }, "api": { "success": true, "cost": 50 } } 상태 조회 form-data 전체 예제 보기 완료 응답 (HTTP 200) { "data": { "job_id": "5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5", "product": "tiktok_search", "status": "completed", "max_results": 10, "unit_point": 5, "reserved_point": 0, "charged_point": 5, "result_count": 1, "created_at": "2026-10-06T10:00:00.000Z", "completed_at": "2026-10-06T10:01:12.000Z", "result_expires_at": "2026-10-09T10:01:12.000Z", "items": [ { "video_id": "7473282881658309895", "url": "https://www.tiktok.com/@camper.muka/video/7473282881658309895", "username": "camper.muka", "description": "이번 주 캠핑요리 종결해드릴게요 ...", "posted_at": "2026-02-20T09:00:00.000Z", "views": 120000, "likes": 5400, "comments": 88, "shares": 120, "saves": 900, "duration_sec": 59, "hashtags": [ "캠핑요리" ], "region": "KR", "cover_image_url": "https://p16-sign.tiktokcdn.com/...", "author": { "followers": 45000, "is_verified": false } } ], "result_expired": false }, "api": { "success": true, "cost": 0 } }