End-to-end testing
Run sign-up, login and checkout tests on your own staging or production sites without disabling the widget.
Token task
reCAPTCHA v2 token API
Send the page URL and its site key, and get back a ready-to-submit reCAPTCHA v2 token for the checkbox or image challenge.
- Price / 1,000
- —
- Typical speed
- —
- Success
- —
Pay only for solved tasks. Failed tasks are refunded automatically.
What you send, what you get
What is reCAPTCHA v2?
reCAPTCHA v2 is the “I'm not a robot” checkbox, sometimes followed by an image grid. When it passes, the page puts a response token into a hidden field that the server verifies. bypass.so returns that token so your script can submit the form.
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 RecaptchaV2Task for this task. |
| websiteURLstringrequired | Full URL of the page that shows the widget. |
| websiteKeystringrequired | The site key, found in the data-sitekey attribute of the widget or in the script that renders it. |
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.gRecaptchaResponse | The response token. Submit it in the g-recaptcha-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,
RecaptchaV2Taskand its fields. - Poll for the resultCheck every 2 to 3 seconds while status is
processing. - Use the tokenRead
solution.gRecaptchaResponseand 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 response token once the task is ready.
Find the site key
Open the page you are testing and copy the
data-sitekeyvalue of the widget, plus the page URL.Request a token
Create a
RecaptchaV2Taskand pollgetTaskResultevery 2 to 3 seconds until it is ready.Put it in the form
Set the token as the value of the hidden
g-recaptcha-responsetextarea, or pass it to the page's callback if the site uses one.Submit promptly
Send the form right away. Tokens are single-use and expire after about two minutes.
Token field on the pageg-recaptcha-responseIf the page uses an invisible widget or a JavaScript callback, call that callback with the token instead of only filling the field.
Use cases
Where teams use reCAPTCHA v2 tasks
Built for testing, accessibility and data work on sites you own or are allowed to automate.
Monitoring
Check that forms behind the checkbox keep working with synthetic transactions on a schedule.
Permitted data workflows
Collect public data you are allowed to access, at a pace the site can handle.
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
reCAPTCHA v2 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?
In the page markup: the widget element carries a
data-sitekey attribute. It can also appear as the k= value in the widget's frame URL or in the render call.How long is a token valid?
About two minutes, and it can be used once. Request the token when you are ready to submit, not ahead of time.
Does it work for the invisible variant?
Yes. Send the same URL and site key. On submit, call the page's callback function with the token if the form does not read the field directly.
How long does a task take?
Typically around eight seconds. Poll
GET /getTaskResult/{taskId} every two to three seconds.What if the site rejects a token?
Report it with
POST /reportBad and the taskId; the price of that task is returned to your balance once. Then send a new task.Do I pay for failed tasks?
No. The price is held when you send the task and charged only when a token is returned.
Send your first reCAPTCHA v2 task
Create an account, top up from a few dollars and get your key. You only pay for tasks that return a result.