FAQ
More
Getting started
Section titled “Getting started”Is there a free trial, a sandbox or a test key?
Section titled “Is there a free trial, a sandbox or a test key?”No. There is one kind of key, and every task it creates solves a real challenge. A task is charged only if it succeeds, so trying the API costs one task’s price; see pricing. Top-ups start at $10.
Which API format should I use?
Section titled “Which API format should I use?”REST v1 for new code: resource URLs, a bearer key, Idempotency-Key for safe retries and a problem
document for every error. Use the createTask format or the
2Captcha format when you already have a client written for them.
Do you have client libraries?
Section titled “Do you have client libraries?”For Node.js, Python and Go, they are coming: none is in its package registry yet. Until they are, and in any other language, call the API over plain HTTP, as the quickstart does; the AI brief has tested reference clients in four languages.
Can my AI coding assistant write the integration?
Section titled “Can my AI coding assistant write the integration?”Yes. Give it the integration brief: one file with every call, field and error code, the retry rules, tested clients and a checklist. Keep your key in the environment, not in the chat.
Tasks and tokens
Section titled “Tasks and tokens”How long does a task take?
Section titled “How long does a task take?”It depends on the site and the solvers’ load. A task ends by its deadline, 150 seconds after it was created by default; the status page shows the median time to a token over the last day.
How often should I poll?
Section titled “How often should I poll?”Every 2 seconds, until the status is final, and stop at a deadline. Or name a callback URL and we call you.
How long is a token valid?
Section titled “How long is a token valid?”A Turnstile token works once, for 300 seconds after it was issued. A challenge page’s clearance lasts as long as the site allows, 30 minutes by default; we serve it for 30 minutes.
I read my task after its token expired. Was I charged?
Section titled “I read my task after its token expired. Was I charged?”Yes: the task succeeded, so it was charged, even though the token expired before you used it. Use tokens as soon as they are ready. See How a task works.
Is a failed task charged?
Section titled “Is a failed task charged?”No. A task that fails or expires releases its hold in full, and a refused request is never charged.
The site rejects the token. What now?
Section titled “The site rejects the token. What now?”Check that websiteURL is the page with the widget, that websiteKey, action and cdata match
the widget exactly, that you submit the token in the field or callback the page uses, and within
300 seconds. With TurnstileTask, the site may also expect the form from the address that solved
it. See Solving Cloudflare Turnstile.
You can report it: POST /v1/tasks/{id}/report with {"verdict": "bad"}, reportbad in the
2Captcha format, or reportIncorrect in the createTask format. We read reports to find sites and
settings that fail. A report refunds nothing, as every charge is final.
Can it solve Cloudflare WAF and 5-second challenge pages?
Section titled “Can it solve Cloudflare WAF and 5-second challenge pages?”Yes. When a Cloudflare WAF rule, Bot Fight Mode or Under Attack mode answers with the “Just a
moment…” challenge page, once known as the 5-second challenge, a CloudflareChallengeTask passes
it through your proxy and returns the cf_clearance cookie with the user agent it was issued for. A
block, such as error 1020, is a refusal rather than a challenge, and no task passes it. See
Cloudflare WAF and 5-second challenges.
Do I need a proxy?
Section titled “Do I need a proxy?”Not for Turnstile: TurnstileTaskProxyless needs none. A Cloudflare challenge page always does,
because its clearance works only from the address that earned it. See
Cloudflare WAF and 5-second challenges.
Which proxies work?
Section titled “Which proxies work?”HTTP and HTTPS proxies on a public address, with an optional login and password. SOCKS is not supported yet.
What sites can I send tasks for?
Section titled “What sites can I send tasks for?”Only sites you are allowed to automate, under the Acceptable Use Policy.
No kind of site is blocked by a rule: staff block a site by hand, after a report or when its owner
opts out, and a task for a blocked site is refused with domain_blocked and costs nothing.
Errors and limits
Section titled “Errors and limits”Which errors should I retry?
Section titled “Which errors should I retry?”429, 5xx, a lost connection, and idempotency_key_in_use, after Retry-After. Nothing else as is.
See Errors and retries.
Is there a rate limit?
Section titled “Is there a rate limit?”Not on creating tasks: your balance and your account’s share of the queue (50 tasks at once by default) bound it. Reads have budgets, 200 every 2 seconds per key and per account by default. See Rate limits.
A reply was lost. Did I create the task twice?
Section titled “A reply was lost. Did I create the task twice?”Not if you sent an Idempotency-Key: sending the same request with the same key within 24 hours
returns the first task. To check, list your tasks with GET /v1/tasks?idempotencyKey=….
Keys and account
Section titled “Keys and account”My key leaked. What do I do?
Section titled “My key leaked. What do I do?”Revoke it on the dashboard’s API keys page: it stops at once. Then create a new one. To replace a key without an outage, rotate it instead. See Authentication.
Can my team share an account?
Section titled “Can my team share an account?”Yes. Invite people as owners or members; see Teams and roles.
Do I have to verify my email or turn on two-factor?
Section titled “Do I have to verify my email or turn on two-factor?”Confirming your email is needed before you create an API key or add funds: open the link we email you when you sign up, or send it again from the dashboard. Everything else works before. Two-factor is optional, and we recommend it: see Account security.
How do I get a copy of my data, or delete my account?
Section titled “How do I get a copy of my data, or delete my account?”In the dashboard’s Settings. Your data downloads a copy as a JSON file: an owner’s covers the account, a member’s covers them. Delete account, for owners, deletes it at once, confirmed with your password or a passkey: its keys stop working, queued tasks are cancelled without charge, and its people’s personal data is erased. A balance left is lost, as top-ups are final, and payment records stay as the law requires. See Account security.
My account is suspended. What can I do?
Section titled “My account is suspended. What can I do?”Keep reading: you can still sign in and see everything. Its keys are refused and it can’t make tasks, keys or top-ups. To appeal, open Support in the dashboard: the form becomes an appeal, and a person reads it and answers by email. If the suspension is lifted, everyone on the account is emailed and the keys work again at once.
Payments
Section titled “Payments”How do I pay?
Section titled “How do I pay?”In crypto, through NOWPayments’ checkout page, from $10 with no maximum. You pick the coin there. See Billing.
Can I get a refund?
Section titled “Can I get a refund?”No: top-ups are final. You pay only for solved tasks, and you can start with $10. See the refund policy.
I sent less, or more, than the invoice asked.
Section titled “I sent less, or more, than the invoice asked.”We credit what arrived, at the processor’s quote: the share that arrived when you paid less, and all of it when you paid more. See Billing.
Can I get a receipt with my company’s details?
Section titled “Can I get a receipt with my company’s details?”Yes. Add your company name, address or tax ID under billing details; every receipt after that carries them.
Support
Section titled “Support”How do I reach you?
Section titled “How do I reach you?”Use the contact form, or Support in the dashboard. Quote the request_id of a
failed request, or a task’s ID. Never send your API key: we never need it.