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.

Read next