Async is supported by both Unlocker API and SERP API products
Async VS Sync requests
There are 2 ways for us to handle your Unlocker API and SERP API requests:default
Synchronous requests - Send a request and get a real-time response immediately- Asynchronous requests - Send a request (without waiting for an immediate response) and retrieve the results later via our designated API endpoint. Callback times are usually up to 5 minutes but may take up to 8 hours during peak periods. Responses are stored for up to 48 hours from the time the request was sent.
Async is recommended for those with high-volume requests who don’t need to serve an immediate or live response and can wait a few minutes to retrieve all their responses at once.
Why should I use Async?
- 99.99% success rate
- Stability
- Flexibility - the ability to retrieve your requests at a later time of your choosing (and not have to wait for the response immediately after sending the request)
How it works
Sending requests and receiving responses with Async mode is a two-step flow:- Sending the request - This request includes the search parameters, returns a
response_ID
, and is a direct request (i.e. you will be billed for this request). - Collecting the response - This request includes the
response_ID
and is free of charge (i.e. you will not be billed for this request). If you call for aresponse_ID
which is still being processed you will receive a 102 status code.
We store responses for up to 48 hours from the time the request was sent.
Getting started
1
Enable "Asynchronous requests"
Within your specific Unlocker API or SERP API zone, under “Advanced settings”, enable the “Asynchronous requests” toggle.

2
[Optional] Setting up a webhook (POST or GET)
This is where you will get notified on the status of your future requests
A webhook can also be set per request (see “Initial request parameters” below)
3
Sending an async request
The request syntax is slightly different from that of synchronous requests and requires an API key for authentication. See a basic example below (for more request parameters see below):You’ll receive a response to the above that contains an
x-response-id
header with the ID of your request. This is the RESPONSE_ID
for this request which you will use when collecting your results in the next step.You can easily save the
RESPONSE_ID
in your script by initializing it along with your request like this:4
Webhook notification
If you’ve set up a webhook, you’ll receive a notification immediately when the requests are ready with the following parameters:
status
, response_id
, request_url
and hook_data
(optional - if you’ve used the webhook_data
parameter in your request).Allowlist our webhook IPs
Our asynchronous webhooks delivery sends notifications from a pair of stable IP addresses, so please make sure to allowlist them:100.27.150.189
18.214.10.85
5
Collecting your results
Using the
RESPONSE_ID
received in step 3, send the following:API - Request creation - POST /{unblocker|serp}/req
Example
Parameters
(*) mandatory parameter
Parameter | Type | Description |
---|---|---|
url (*) | String | Defines the url of the request |
method | String | Defines the HTTP method of the request |
headers | Object | Defines headers to be used in the request |
body | String or Object | Defines body to be sent with request. If an object is specified, it is serialized to JSON, and Content-Type header is set to application/json. |
country | String | Defines country to be used for request (2-letters code) |
webhook_url | String | Defines the URL to which the job status notification will be sent. If you don’t want to setup a default webhook (above) or prefer the URL to be different per request, use this. |
webhook_method | String | Defines the HTTP method to use with the webhook_url (GET or POST) |
webhook_data | Any | Defines the data that will be sent with job status notification |
SERP-specific parameters
Parameter | Type | Description |
---|---|---|
query (*) | Object | |
brd_json | 1 or “html” | Defines the response format |
SERP Example
API - Response collection - GET /{unblocker|serp}/get_result
Note: response_id
comes from the x-response-id
header of the request creation response
Example
Parameters
(*) mandatory parameter
Parameter | Description |
---|---|
response_id (*) | Defines the job id. Received in the response headers of your initial async request. |
Multiple queries in a single request
SERP API only
multi
parameter instead of query
.
These parallel requests use the same peer IP and session and can be used for collecting additional data, comparison tests, etc. – e.g., making a pair of requests with different parameters/values. They use the same IP and session.
Conditions:
- Supported only for a zone with Async enabled (as shown above)
- Supported only for Google Search
- Limited to 2 requests
- Billed as 2 requests
Sample Request