Testing your own forms
Keep CI pipelines and staging checks running for login, sign-up and contact forms protected by Turnstile.
Token task
Cloudflare Turnstile token API
Send the page URL and Turnstile site key, and get a token your script submits with the form, usually in a few seconds.
- Price / 1,000
- —
- Typical speed
- —
- Success
- —
Pay only for solved tasks. Failed tasks are refunded automatically.
What you send, what you get
What is Cloudflare Turnstile?
Turnstile is a mostly invisible check that runs when a page loads and produces a token without asking the visitor to solve anything. The page sends that token with its form or request, and the site verifies it. bypass.so returns the token for you.
Token tasks run asynchronously: createTask returns a taskId right away and you poll for the token. Typical time to a result is about eight seconds.
POST/createTask
GET/getTaskResult/{taskId}
POST/reportBad?task_id={taskId}
Every request needs your API key. Create an account to get one, top up any amount, and you are ready to send tasks.
Request parameters
| Field | Description |
|---|---|
| clientKeystringrequired | Your API key. You can also send it as Authorization: Bearer <key> instead. |
| typestringrequired | Always TurnstileTask for this task. |
| websiteURLstringrequired | Full URL of the page that shows the widget. |
| websiteKeystringrequired | The Turnstile site key, from the widget's data-sitekey. It starts with 0x. |
| actionstringoptional | The widget's data-action value, if the page sets one. |
Request · POST /createTask
Response fields
| Field | Meaning |
|---|---|
| errorId | 0 on success, 1 on error. Errors also carry errorCode and errorDescription. |
| status | processing while the task runs, then ready or failed. |
| taskId | Returned by createTask. Use it to poll and to report a wrong answer. |
| solution.token | The Turnstile token. Submit it in the cf-turnstile-response field. |
| solution.tokenField | Name of the form field the token belongs in, when it is known. |
| solution.tokenLifetime | Seconds the token stays usable after it is issued, when it is known. |
Integration
Copy, paste, solve
Plain HTTPS and JSON. No SDK to install.
- Create the taskSend your key,
TurnstileTaskand its fields. - Poll for the resultCheck every 2 to 3 seconds while status is
processing. - Use the tokenRead
solution.tokenand continue your flow. - Wrong answer? Report it
POST /reportBad?task_id=<taskId>with your key as Bearer returns that task's price once.
Errors and limits
| errorCode | When it happens |
|---|---|
| ERROR_KEY_INVALID | The API key is missing or not recognised (HTTP 403). |
| ERROR_INSUFFICIENT_CREDITS | Your balance does not cover the task price. Top up and resend (HTTP 402). |
| ERROR_TASK_NOT_SUPPORTED | The type value is unknown or not live yet (coming soon). Nothing is charged. |
| ERROR_BAD_REQUEST | The body is not valid JSON or a field has the wrong type (HTTP 400). |
| ERROR_CAPTCHA_UNSOLVABLE | The task could not be completed. The held price is refunded automatically. |
| ERROR_RATE_LIMIT | Too many requests in a short time. Back off and retry (HTTP 429). |
| ERROR_NOT_FOUND | Unknown taskId, or the task belongs to another key (HTTP 404). |
Check your balance any time with GET /balance and Authorization: Bearer <key>. Full list in the error reference.
Using the result
From token to submitted form
What your own script does with the Turnstile token once the task is ready.
Copy the site key
Find the Turnstile widget on the page you are testing and copy its
data-sitekey(it starts with0x) and the page URL.Request a token
Create a
TurnstileTaskand pollgetTaskResultevery 2 to 3 seconds until it is ready.Fill the response field
Set the token as the value of the hidden
cf-turnstile-responseinput inside the form.Submit within the lifetime
Turnstile tokens are valid for up to five minutes and work once. Submit the form promptly.
Token field on the pagecf-turnstile-responseIf the page reads the token through a callback, call that callback with the token instead of only setting the input.
Use cases
Where teams use Cloudflare Turnstile tasks
Built for testing, accessibility and data work on sites you own or are allowed to automate.
Uptime checks
Run synthetic transactions on protected pages to confirm customers can still get through.
Permitted integrations
Keep approved scripts and partner tools working on pages that add the widget.
Use bypass.so only where you have permission. Respect each site's terms and rate limits, and never use results to access accounts or data that are not yours. See our acceptable use policy.
Pricing
Cloudflare Turnstile pricing
—per 1,000 solved tasks
That is — per task, or — tasks for $100.
- No subscription, no minimum volume
- Failed tasks are refunded automatically
- Bigger top-ups get bonus credit
Volume bonus on a single top-up
| Tier | Top-up | Bonus | Effective / 1k | Tasks covered |
|---|
Related types
Same key, more task types
Where do I find the site key?
On the widget container as
data-sitekey, or in the render call in the page script. Turnstile keys start with 0x.How long is a token valid?
Up to five minutes and single use. When the response includes
tokenLifetime, it tells you the number of seconds.Is this the same as the full-page challenge?
No. This type returns tokens for the Turnstile widget embedded in a page or form. It does not cover full-page interstitial checks.
How long does a task take?
Typically around eight seconds. Poll
GET /getTaskResult/{taskId} every two to three seconds.What if a token is rejected?
Report it with
POST /reportBad and the taskId; the task's price is returned to your balance once. Then request a new token.Send your first Cloudflare Turnstile task
Create an account, top up from a few dollars and get your key. You only pay for tasks that return a result.