Skip to main content

Cloudflare Turnstile

Cloudflare Turnstile is a modern, privacy-focused CAPTCHA alternative developed by Cloudflare. It functions similarly to reCAPTCHA but without tracking user behavior. Turnstile appears as a widget on forms and verifies users with minimal interaction—often invisibly.

Overview​

Turnstile typically appears in two forms:

  • Standalone widget embedded directly in a website's form
  • Cloudflare interstitial challenge pages during DDoS protection
  • Three modes: Managed, Non-Interactive, and Invisible
  • Returns a token that must be submitted with the form
Cloudflare Turnstile Example

Example: Cloudflare Turnstile verification widget

How to Solve Cloudflare Turnstile​

Step 1: Locate the Site Key​

Find the Turnstile site key from the webpage:

  1. Inspect element code on the page where Turnstile appears
  2. Look for data-sitekey attribute in the div element
  3. Or find it in turnstile.render() JavaScript call: 
    turnstile.render('#challengeContainer', {
      sitekey: '3x00000000000000000000FF'
    });

Step 2: Submit the Task to CaptchaAI​

Send a GET request to https://ocr.captchaai.com/in.php with the sitekey and page URL:

import requests

# Submit the captcha task
params = {
    'key': 'YOUR_API_KEY',
    'method': 'turnstile',
    'sitekey': '3x00000000000000000000FF',
    'pageurl': 'https://example.com/page',
    'json': '1'
}

response = requests.get('https://ocr.captchaai.com/in.php', params=params)
result = response.json()
task_id = result['request']
print(f"Task ID: {task_id}")

Step 3: Retrieve the Solution​

Wait 10-15 seconds, then poll for the result using a GET request to https://ocr.captchaai.com/res.php:

import time

time.sleep(10)  # Wait 10 seconds

params = {
    'key': 'YOUR_API_KEY',
    'action': 'get',
    'id': task_id,
    'json': '1'
}

response = requests.get('https://ocr.captchaai.com/res.php', params=params)
result = response.json()

if result['status'] == 1:
    token = result['request']
    print(f"Solution Token: {token}")

Step 4: Inject the Token​

Inject the token into the hidden field and submit the form:

# Using Selenium
from selenium import webdriver

driver = webdriver.Chrome()
driver.get('https://example.com/page')

# Inject the token into Turnstile field
driver.execute_script(f'''
    document.querySelector('[name="cf-turnstile-response"]').value = "{token}";
''')

# Submit the form
driver.find_element_by_tag_name('form').submit()

Response Format​

JSON Response (with json=1):

{
  "status": 1,
  "request": "0.4uMMZZdSfsVM8...610cd090"
}

Plain Text Response:

OK|0.4uMMZZdSfsVM8...610cd090

Common Errors​

  • ERROR_WRONG_USER_KEY: API key is incorrect format. Check your API key (32 characters).
  • ERROR_KEY_DOES_NOT_EXIST: API key doesn't exist. Verify your API key.
  • ERROR_ZERO_BALANCE: Insufficient account balance. Top up your account to continue.
  • ERROR_PAGEURL: pageurl parameter is missing. Provide the full page URL.
  • ERROR_WRONG_SITEKEY: sitekey is blank or malformed. Verify the sitekey extraction.
  • ERROR_BAD_PROXY: Proxy is marked as bad. Use a different proxy server.
  • CAPCHA_NOT_READY: Solution not ready yet. Wait 5 seconds and poll again.

For complete error documentation, see the Error Handling Guide.

Tips & Best Practices​

Tip: Always use the exact page URL where Turnstile appears - URL mismatch can cause failures.

Tip: Use json=1 parameter for structured responses that are easier to parse.

Tip: Turnstile tokens are single-use - request a fresh token for each challenge.

Tip: Include proxy and user-agent parameters for better accuracy on protected sites.

API Reference​

For complete API specifications and advanced options, visit the CaptchaAI API Documentation and select Cloudflare Turnstile from the sidebar.