Cloudflare Turnstile
From widget configuration to a token you can submit. Find the site key, preserve the widget context, and connect the response to your form.
{
"clientKey": "capzy_YOUR_API_KEY",
"task": {
"type": "AntiTurnstileTaskProxyLess",
"websiteURL": "https://example.com/login",
"websiteKey": "0x4AAAAAAAYOUR_SITE_KEY"
}
}Illustrative payloads. Replace the example URL and site key.
First, find your site key.
The public widget key becomes websiteKey in your request. Here’s where to look.
Three keys, three jobs.
Widget site key: websiteKey.
Capzy API key: clientKey.
Cloudflare secret: server validation.
Look for data-sitekey.
Open the page containing the widget. Right-click near it, choose Inspect, then search the Elements panel for data-sitekey. Copy the attribute value into websiteKey.
<div
class="cf-turnstile"
data-sitekey="0x4AAAAAAAYOUR_SITE_KEY"
data-action="login"
></div>Use the key on the widget you are submitting. A page can contain more than one widget.
Read HTML widget keys from the console
This reads widgets with a data-sitekey attribute in the current document. For widgets rendered programmatically, use the JavaScript method.
[...document.querySelectorAll("[data-sitekey]")].map(el => ({
websiteKey: el.getAttribute("data-sitekey"),
action: el.getAttribute("data-action"),
cdata: el.getAttribute("data-cdata")
}));Know what goes in.
Select a parameter to see what it does, where to find it, and where it belongs in the request.
Capzy supplies the solving network. No proxy credentials are needed.
Request authentication
Task parameters
websiteKey
stringRequiredThe public site key associated with the Turnstile widget. Use the widget’s site key, not your Capzy API key or Cloudflare secret.
Read data-sitekey in the HTML or sitekey in the turnstile.render configuration.
Open the site-key guide0x4AAAAAAAYOUR_SITE_KEY{
"clientKey": "capzy_YOUR_API_KEY",
"task": {
"type": "AntiTurnstileTaskProxyLess",
"websiteURL": "https://example.com/login",
"websiteKey": "0x4AAAAAAAYOUR_SITE_KEY"
}
}The highlighted line matches your selected parameter. Optional proxy credentials can be omitted for an unauthenticated proxy.
Does the widget set action or cData? Enable widget context above to see those fields.
Make your first request.
Create a task, poll for a result, then read solution.token. Choose your language and copy the example.
# pip install requests
import os
import time
import requests
API = "https://api.capzy.ai"
payload = {
"clientKey": "capzy_YOUR_API_KEY",
"task": {
"type": "AntiTurnstileTaskProxyLess",
"websiteURL": "https://example.com/login",
"websiteKey": "0x4AAAAAAAYOUR_SITE_KEY"
}
}
payload["clientKey"] = os.environ["CAPZY_API_KEY"]
def post(endpoint, body):
response = requests.post(f"{API}/{endpoint}", json=body, timeout=30)
response.raise_for_status()
data = response.json()
if data.get("errorId") or data.get("status") == "failed":
raise RuntimeError(data.get("errorDescription") or
data.get("errorCode") or "Task failed")
return data
created = post("createTask", payload)
deadline = time.monotonic() + (created.get("timeout") or 120)
result = created
while result.get("status") != "ready":
if time.monotonic() >= deadline:
raise TimeoutError("Turnstile task timed out")
time.sleep(1)
result = post("getTaskResult", {
"clientKey": payload["clientKey"],
"taskId": created["taskId"],
})
token = result["solution"]["token"]
# Submit once to your target form as cf-turnstile-response.
print(token)Before running Replace the example URL, site key and any proxy placeholders. Set CAPZY_API_KEY in your environment.
Polling behaviorThe example checks HTTP and API errors, waits between polls, and uses the task’s timeout (120 seconds if none is returned).
Understand what comes back.
Follow the task from creation to completion. Each state shows the actual response shape and your next move.
Your token is in solution.token.
Submit the token with your target form or pass it to the integration’s success handler. Each token can be validated once.
statusstring- ready means the solution is available.
solution.tokenstring- The Turnstile response token to submit to the target site.
{
"errorId": 0,
"status": "ready",
"solution": {
"token": "0.EXAMPLE_TURNSTILE_TOKEN"
}
}Illustrative values. Additional metadata may be returned.
Put the token in your form.
The default response field is cf-turnstile-response. Use the field name or callback expected by your target’s integration.
const form = new URLSearchParams();
form.set("cf-turnstile-response", result.solution.token);
// Add the other fields required by your form.
await fetch("https://example.com/your-form-handler", {
method: "POST",
body: form
});For sites you own, validate the token on your server with Cloudflare’s Siteverify API. Writing a hidden field alone does not run a site’s JavaScript success callback.
When something doesn’t work.
A few checks resolve the most common integration mistakes.
The HTML has no data-sitekey. Where else should I look?
The widget may use explicit JavaScript rendering. Search loaded sources in DevTools for turnstile.render or sitekey and read the widget configuration. Open the page or form that actually loads the widget; a key may not appear until that part of the page is rendered.
Which key belongs in websiteKey?
Use the public Cloudflare Turnstile widget site key. Your Capzy API key goes in clientKey at the top level of the request. The Cloudflare secret key is used only on your own server for Siteverify validation and should never be sent as a task parameter.
When should I include action and cdata?
Include them when the original widget sets them. Read data-action and data-cdata in the HTML, or action and cData in the JavaScript render configuration. Preserve the original values. The Capzy API field is lowercase cdata; do not invent a value when the widget does not supply one.
The returned token is rejected. What should I check?
Check that websiteURL matches the widget's page, websiteKey matches the widget, and any action or cdata values match the original configuration. Tokens expire 300 seconds after generation and can be validated only once. Submit promptly. If the target requires the same IP, use your proxy for both solving and submission. Follow the site's expected field name or success callback.
Do I need to supply a proxy?
AntiTurnstileTaskProxyLess uses Capzy's solving network and does not need proxy credentials. Choose AntiTurnstileTask when you want to supply your own proxy. If the target requires a matching IP, keep the same proxy exit for the solve and the submission.
Can I reuse the same token?
No. Turnstile tokens are single-use and expire after 300 seconds. Create a new task for each fresh token you need. A duplicate or expired token cannot be validated successfully.
Is this the right solver for a full-page Cloudflare block?
For full-page 'Just a moment...' or 'Checking your browser...' interstitials, use AntiCloudflareTask with a proxy. The Cloudflare Challenge solver returns a cf_clearance cookie and matching user-agent. This Turnstile solver returns a widget token for a form.
Seeing a full-page “Just a moment…” screen?
Use the Cloudflare Challenge solver for a cf_clearance cookie. A Turnstile widget token serves a different purpose.
Ready to connect your workflow?
Get your Capzy API key and use the integration above.
Proxyless task · Live configuration