Submit a job
https://scraper.riken.me/v1/jobsTry it
Paste your key under Authorization and send a live request to https://scraper.riken.me. The key stays in this browser tab only (session storage, cleared when the tab closes) and is sent nowhere else. A live request spends credits like any other.
Queue a bulk job and hold its credits. Answers 202 at once; poll
poll_url. Handles lose a leading @; units are trimmed and deduplicated
case-insensitively; at most 50,000 units per job.
Billing is per unit attempted, not per result found, at the job kind's price pinned at submit. The whole hold is taken now; unused credit comes back when the job finishes or is cancelled.
Idempotency-Key: the same key with the same request returns the same job
(Idempotency-Replayed: true, idempotent_replay: true), no second hold.
The same key with a different request is 409 idempotency_conflict.
Unknown body fields are a 400. Per-key rate limit and a per-key cap on
queued plus running jobs apply (429 rate_limited, 429 concurrency_limit).
Headers
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
x-api-key | string | one of the auth headers | Your API key. If both headers are sent, `x-api-key` wins. | sk_... |
Authorization | string | one of the auth headers | `Authorization: Bearer <key>`, the same key. | Bearer sk_... |
Idempotency-Key | string | no | Any string up to 255 characters. Makes a retry safe for 24 hours; bound to this API key and the request's parameters. | profile-dagestantrainingcamp-2026-11-01 |
application/json- body
kind*JobKindtiktok.search keywords; tiktok.screen handles (profile and first
videos); tiktok.walk handles (newest posts, about 24 per creator);
tiktok.audience handles (US+CA audience share); instagram.search
keywords; instagram.fetch handles (profile and feed).
"tiktok.search""tiktok.screen""tiktok.walk""tiktok.audience""instagram.search""instagram.fetch"keywords?array<string>For tiktok.search and instagram.search. Trimmed, deduplicated; no control characters, no leading #.
items <= 50000handles?array<string>For the other kinds. A leading @ is removed.
items <= 50000options?Passed to the scraper. Validated at submit for tiktok.walk
(max_videos, walk_timeout_s, min_days, early_stop),
tiktok.search (region) and tiktok.audience (us_ca_share_min); other
keys are passed through.
priority?integerLower runs first. 0 or absent takes the kind's default band. Not settable on POST /v1/search.
0 <= valuechunk_size?integerOperator tuning; leave it out.
1 <= value <= 1000Status codes
| Status | Charged | Meaning |
|---|---|---|
| 202 | Depends | Accepted (or replayed for the same Idempotency-Key). Credits are held, not yet spent. |
| 400 | Free | A malformed body, parameter or cursor. Free. |
| 401 | Free | Missing, unknown or revoked key. Free. |
| 402 | Free | The key cannot cover the job's hold. Micro fields are the exact integers; the credit strings are the same amounts for people. Free. |
| 409 | Free | This Idempotency-Key was already used for a different request. Free. |
| 429 | Free | The key's request rate (rate_limited) or its cap on queued plus running jobs (concurrency_limit, Retry-After 10). Free. |
| 500 | Free | Our fault. Free. |
Accepted (or replayed for the same Idempotency-Key). Credits are held, not yet spent.
application/json- response
job_id*integerint64job*idempotent_replay?booleanpoll_url*stringExample request
# A call can be held open up to 180 s (audience: 300 s). Set a client timeout above that.curl -X POST 'https://scraper.riken.me/v1/jobs' \ -H 'Idempotency-Key: profile-dagestantrainingcamp-2026-11-01' \ -H 'Content-Type: application/json' \ -d '{ "kind": "tiktok.walk", "handles": [ "lucymfit", "@dishes.easyrecieps" ], "options": { "max_videos": 120, "early_stop": { "min_reels_per_week": 3, "full_weeks": 4, "ignore_current_week": true, "reel_kinds": [ "video" ], "views": { "min_views_per_video": 40000, "min_share_clearing": 0.8, "band_min_age_days": 10, "band_max_age_days": 40, "min_band_videos": 5, "exclude_pinned": true } } }}'{ "job_id": 685, "job": { "id": 685, "kind": "tiktok.walk", "state": "queued", "priority": 120, "progress": { "units_done": 0, "units_total": 2 }, "credits": { "held_micro": 2000000, "spent_micro": 0, "held": "2.000000", "spent": "0.000000" }, "created_at": "2026-11-05T10:00:00Z" }, "poll_url": "/v1/jobs/685"}