How jobs work

Every request needs a bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

A missing or invalid token gets 401. A valid token that isn't scoped for the endpoint you're calling gets 403 — contact support to enable access. Create a key in Scraping jobs and fund your wallet before submitting jobs; the same key also works for the Data API.

Every endpoint works the same way: submit → job ID → poll → download. Nothing returns the full result in the submit response.

1. Submit. POST the endpoint's /submit path (or its single POST route). You get back a job_id or task_id.
2. Poll. GET the matching retrieve/{id} path until the status is terminal (see the table below). Keep the ID and keep polling — don't resubmit while a job is still running.
3. Download. Depending on the endpoint, results come back inline in the retrieve response, via a signed download_url, or per item from a separate data path. See Results below.

Single-item endpoints (Shopee Product Page, Product Ratings, the bulk CSV uploads, and every other marketplace's PDP/search/merchant endpoints) have no approval step and typically finish in seconds to tens of minutes. The four endpoints that go through Shopee's manual review — Variant Sold, Listing product (Search Items), Merchant Items, and Shopee App Search — queue first and can take hours; see Approval flow below.

Jobs for Variant Sold, Merchant Items, Search Items (Listing product), and Shopee App Search go through manual approval:

1. You submit → status AWAITING_APPROVAL. No charge yet.
2. Our team reviews and approves, typically within 24 hours.
3. Approved work only runs inside Shopee's processing window — Monday–Friday, 08:00–17:00 Asia/Jakarta (WIB). Outside that window an approved job sits queued with a runs_after timestamp for the next window; that's expected, not an error — keep polling, don't resubmit.
4. Job starts → PROCESSING, then COMPLETED or PARTIAL_COMPLETE. If approval is declined or the 24-hour window passes first, the job becomes REJECTED and nothing is charged.

Shopee Product Page, PDP Bundling, Product Ratings, and every bulk CSV endpoint (across Shopee, Tokopedia, Blibli, TikTok Shop, Amazon, and Mercado Libre) do not require approval — they start processing immediately, any hour.

Recurring (cron/run_at) schedules for Listing product and Merchant Items follow the same window — a submission isn't even created outside it.

Per-item status inside a job's results (not the job status itself) is typically PENDING / SUCCESS / FAILED.

• Inline: single-item endpoints (Shopee Product Page, Product Ratings) return the result directly in the retrieve response.
• Signed download_url: most bulk endpoints compile results into a single gzip-compressed JSONL (or CSV) file and hand back a link to it. Tokopedia PDP Bulk and Blibli PDP Bulk links are plain signed GCS URLs valid for 7 days — no bearer token needed. Other endpoints' download_url values require the same Bearer token you submitted with; the guide doesn't state a fixed expiry for those, so download promptly.
• Per item: Search Items and Merchant Items instead give each successful item its own download_url path under /v1/shopee/pgnt/jobs/{job_id}/items/{token}/data, which still needs your Bearer token.
• Most records carry collected_at as an integer Unix timestamp (UTC seconds) — when the data was actually captured upstream, not when your job ran.

• No-approval endpoints (bulk CSV uploads, single-item fetches, and the rest of the non-gated endpoints) reserve credits upfront at submit, for every row, URL, or item in the request.
• Approval-gated endpoints (Variant Sold, Search/Merchant Items, Shopee App Search) are not charged at submit. Credits are deducted only once a job is approved and actually starts processing — a job that's rejected or times out before that point costs nothing.
• Refunds cover whatever doesn't come back successfully: failed and canceled items are all non-billable. Terminating a bulk task early refunds its unfinished items too.
• Prices vary per endpoint and per unit (request, URL, item, or page) and change over time — see the live rate card rather than relying on a number in these docs.

Instead of polling, bulk endpoints can notify a signed webhook when results are ready — see Scraping webhooks.