Glossary
The terms you meet when you solve Cloudflare Turnstile from your own code, each defined on its own. The guides go deeper.
- 5-second challenge
- The old name for Cloudflare's JavaScript challenge page, after the few seconds it took. Today a WAF rule shows a Managed or Non-Interactive Challenge in its place, which Cloudflare says typically takes less than five seconds; passing it earns a cf_clearance cookie. The Cloudflare 5-second challenge
- Action
- An optional label a site gives a Turnstile widget, such as login, set with data-action or the action option of turnstile.render(). A task passes it on so the token carries the same action the site expects. Action and cData
- API key
- The secret that authorizes your code's calls to ZeroCaptcha. It starts with zc_live_, is shown once when created, and can be limited to scopes and IP addresses, capped per day, rotated or revoked. API keys
- Callback
- A URL you name when you create a task, which ZeroCaptcha calls with the result once the task ends, instead of your code polling for it. Each call is signed so you can check it came from us. Callbacks
- CAPTCHA solver
- A service that completes a CAPTCHA challenge for a program and returns the proof, such as a token, that the site checks. It is meant for automation a site's owner allows. Cloudflare Turnstile solver
- cData
- Optional customer data a site attaches to a Turnstile widget with data-cdata or the cData option. Cloudflare returns it when the token is verified, so a task that passes it on gets a token the site accepts. Action and cData
- cf_clearance
- The cookie Cloudflare sets once a browser passes one of its challenge pages. It lets later requests through, and Cloudflare ties it to the visitor and device that earned it: in practice the user agent, and usually the address. The cf_clearance cookie
- cf-turnstile-response
- The hidden form field a Turnstile widget fills with its token. The site's server reads it from the form and verifies it with Cloudflare. Submitting a Cloudflare Turnstile token
- Challenge page
- The interstitial page Cloudflare shows in front of a whole site, such as "Just a moment...", before it lets a visitor through with a cf_clearance cookie. It is not the same thing as a Turnstile widget inside a page. Challenge pages and Cloudflare Turnstile
- Cloudflare Turnstile
- Cloudflare's CAPTCHA alternative: a widget that checks a visitor in the background, or with one click, and gives the page a token its server verifies. What is Cloudflare Turnstile
- Compatible format
- ZeroCaptcha's createTask, getTaskResult and getBalance calls, in the JSON shape many CAPTCHA-solving clients already speak, with the key sent as clientKey in the body. Compatible format API
- createTask
- The call that starts a task: it takes the task's type and details, holds the price on your balance, and answers at once with a taskId to poll. createTask and getTaskResult
- getTaskResult
- The call that reads a task by its taskId: processing while it runs, then ready with the token, or an error code if it failed. createTask and getTaskResult
- Hold
- The task's price, set aside from your balance while the task runs. It becomes a charge when a token is ready, and goes back to your balance at once if the task fails or expires. Pricing
- Idempotency key
- A value you send with createTask in the Idempotency-Key header. The same key with the same request within 24 hours returns the first task instead of creating another, so a retried request is never charged twice. Idempotency keys
- in.php and res.php
- 2Captcha's original API: in.php submits a task and res.php reads its result or the balance. ZeroCaptcha answers both for method=turnstile. 2Captcha format
- Proxyless task
- A task solved from the solver's own network, such as TurnstileTaskProxyless. Its counterpart, TurnstileTask, is solved through a proxy you supply. Solving through a proxy
- Sitekey
- The public key that identifies a Turnstile widget, such as 0x4AAAAAAA…, found in data-sitekey or the sitekey option of turnstile.render(). A task needs it with the page's URL. Finding the sitekey
- Siteverify
- Cloudflare's endpoint where a site's server checks a Turnstile token with its secret key. A token passes it once, within 300 seconds of being issued. Token expiry
- Spend cap
- The most a key's tasks may hold or be charged in one UTC day, in US dollars. A task that would pass it is refused before any money moves. Securing API keys
- Task
- One request to solve one challenge. It is queued, solved, and ends ready with a token, failed or expired; only a ready task is charged. Quickstart
- Token
- The proof a solved Turnstile widget produces, which the site's form sends and its server verifies. It works once and expires 300 seconds after it is issued. Token expiry
- WAF challenge
- A Cloudflare WAF rule whose action is Managed Challenge, Non-Interactive Challenge or Interactive Challenge: a matching request gets the "Just a moment..." challenge page instead of the site, until the browser holds a cf_clearance cookie. Cloudflare WAF and 5-second challenge solver
- Widget mode
- How a Turnstile widget behaves, chosen in the Cloudflare dashboard: managed, which may ask for a click; non-interactive, which never does; or invisible, which shows nothing. Widget modes