TikTok profile batch API from quote to export
The workflow has separate quote, submission and result requests. Store the batch ID immediately after a 202 response so your application can resume polling after a restart.
Authenticate and prepare targets
Create a cabinet token and send Authorization: Bearer sk_live_…. The profile workflow needs metadata:read and analyze:write. Submit a JSON urls list with mode="profile". Start with one or two permitted targets. Find the route reference in the API documentation.
Request a quote first
POST /api/v1/profiles/quote returns free, paid, reused, maximum_charge and tariff_version. Send the same urls, the approved maximum_charge and the returned tariff_version to POST /api/v1/profile-batches. A quote does not start collection. A changed free allowance may require a fresh cost confirmation.
Keep a stable retry key
Send Idempotency-Key on submission, for example profile-import-2026-11-06-001. After a network interruption, retry the same request body and key. The server returns the existing batch. A different list or approved cost requires a new key. Conflicting key reuse returns 409.
Poll and export
Read GET /api/v1/profile-batches/{id} until a terminal state, with a delay between requests. Read rows using after and limit. After completion, use export?format=json or export?format=csv. POST /api/v1/profile-batches/{id}/cancel stops remaining work while preserving delivered rows.
Handle errors at the right level
401 requires authentication, 402 requires allowance or credits, 409 calls for checking the key or quote, 422 requires input correction, and 429 requires waiting before retrying. For an accepted batch, inspect each row’s status and error_code. Settlement follows successful card delivery. The CSV guide explains manual result checks.