# Callback Mechanism

The `callbackUrl` parameter allows you to receive the SERP API response directly to your own API endpoint.

When this parameter is included in the request, the API returns a confirmation response indicating that the request has been received. Once the request is completed, the SERP API sends the final results to the specified `callbackUrl`.

***

### Environments

Base URL: `https://serp-api.netnut.io`\
Endpoint: `/search`\
Method: `GET`

***

### Param

Add `callbackUrl={your_endpoint}` to the request URL.

Example:

```http
https://serp-api.netnut.io/search?q=netnut&callbackUrl=https://my-api.com
```

***

### Example Request

```bash
curl --location 'https://serp-api.netnut.io/search?hl=en&gl=us&q=netnut&callbackUrl=https://my-api.com' \
--header 'Authorization: Basic base64(username:password)'
```

***

### Initial API Response

When `callbackUrl` is provided, the API returns HTTP 202 (Accepted) with a confirmation response:

```json
{
  "message": "Request received",
  "traceId": "9b2f2e3c-6c9d-4a6f-9f2b-1b7a7c2d4e11",
  "response_url": "https://my-api.com"
}
```

***

### Callback Response

Once the request is completed, the SERP API sends the final response to your endpoint using the **POST** method.

Example payload sent to your endpoint:

```json
{
  "data": {
    "url": "https://www.google.com/search?q=netnut",
    "general": {
      "searchEngine": "google",
      "resultsCount": 118000,
      "searchTime": 0.39,
      "device": "desktop",
      "searchType": "text",
      "pageTitle": "netnut - Google Search",
      "timestamp": "2025-05-19T20:54:49.412Z"
    },
    "input": {
      "originalUrl": "https://www.google.com/search?q=netnut",
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
      "jobId": "01d5db18-bb65-4d1f-808a-f572767b35cd"
    },
    "ads": [
      {
        "title": "Residential Proxy",
        "link": "https://www.lunaproxy.com/",
        "business_name": "LunaProxy",
        "website": "https://www.lunaproxy.com",
        "description": "lunaprxoy best IP provider — lunaproxy is the leading residential proxy network. 2025 Top Residential Proxy Provider",
        "position": "1",
        "type": "general_ad"
      },
      {
        "title": "Netnut Proxy",
        "link": "https://netnut.io/",
        "business_name": "netnut.io",
        "website": "https://www.netnut.io",
        "description": "Best Proxy for Data Mining — Get real residential proxies with high speed. Free trial. 24/7 support.",
        "position": "2",
        "type": "general_ad"
      },
      {
        "title": "PYPROXY Proxy",
        "link": "https://www.pyproxy.com/",
        "business_name": "pyproxy.com",
        "website": "https://www.pyproxy.com",
        "description": "Pyproxy IP Pools — High-speed rotating residential proxies from over 190 regions with zero verification code.",
        "position": "3",
        "type": "general_ad"
      }
    ],
    "organic": [
      {
        "title": "NetNut - The Largest Proxy & Web Data Collection Network",
        "description": "Reliable support from NetNut team: NetNut's residential proxy network is impressive, offering access to a large pool of IPs worldwide. Their tailored ...",
        "link": "https://netnut.io/",
        "extensions": [
          {
            "type": "site_link",
            "text": "Proxies for Price Comparison",
            "extended": true,
            "link": "https://netnut.io/proxy-use-cases/proxies-for-price-comparison/",
            "rank": 1
          },
          {
            "type": "site_link",
            "text": "Login",
            "extended": true,
            "link": "https://portal.netnut.io/",
            "rank": 2
          },
          {
            "type": "site_link",
            "text": "Residential Proxies",
            "extended": true,
            "link": "https://netnut.io/residential-proxies/",
            "rank": 3
          },
          {
            "type": "site_link",
            "text": "Static Residential Proxies",
            "extended": true,
            "link": "https://netnut.io/static-residential-proxies/",
            "rank": 4
          },
          {
            "type": "site_link",
            "text": "Rotating Residential Proxies",
            "extended": true,
            "link": "https://netnut.io/rotating-residential-proxies/",
            "rank": 5
          },
          {
            "type": "site_link",
            "text": "More results from netnut.io »",
            "extended": true,
            "link": "https://www.google.com/search?q=netnut+site:netnut.io",
            "rank": 6
          }
        ],
        "displayLink": "https://netnut.io",
        "rank": 1
      }
    ],
    "related": [
      {
        "listGroup": false,
        "link": "https://www.google.com/search?q=Netnut+proxy",
        "text": "Netnut proxy",
        "rank": 1,
        "globalRank": 0
      }
    ],
    "peopleAlsoAsk": [
      {
        "question": "Is NetNut legit?",
        "answerSource": "NetNut.io Reviews 2025: Details, Pricing, & Features - G2",
        "answerLink": "https://www.g2.com/products/netnut-io/reviews",
        "answerDisplayLink": "https://www.g2.com › products › netnut-io › reviews",
        "answerHtml": "<div>...</div>",
        "answers": [
          {
            "type": "answer",
            "text": "NetNut has been a reliable choice for handling data tasks that require speed and stability...",
            "rank": 1
          }
        ],
        "rank": 1
      }
    ],
    "pagination": {
      "currentPage": 1,
      "nextPage": 2,
      "nextPageLink": "https://www.google.com/search?q=netnut&start=10",
      "nextPageStart": 10,
      "otherPages": {
        "2": "https://www.google.com/search?q=netnut&start=10"
      }
    },
    "html": "<!doctype html><html......"
  }
}
```

***

### Things to Consider

* `callbackUrl` must be a **publicly accessible endpoint** that can receive **POST** requests.
* The initial response includes a `traceId` you can use for tracking.
* The callback payload follows the same response structure as the SERP API response.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.netnut.io/netnut-documentation/netnut-scraper-apis/serp-api/google-scraper/google-search/callback-mechanism.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.