---
title: "SERP Batch Endpoint"
method: POST
path: "/v1/serp/batch"
tags: ["SERP"]
---

# SERP Batch Endpoint

`POST /v1/serp/batch`

## Request body

- SerpBatchPayload
  - `inputs` object[], required — Array of SERP requests. Each object can include search parameters and async/storage settings.
    - `country` string — ISO Alpha-2 country code used to access the target search engine (e.g. US, DE, GB).
    - `device` 'desktop' | 'mobile' — Device type used for the search request.
    - `domain` string — Top-level domain for the search engine (e.g. "com", "co.uk", "de").
    - `locale` string — Locale used for the search request.
    - `location` string — Geo-location for the search (canonical Google location name).
    - `num_results` integer — Number of results to return (1–100).
    - `page` integer — The result page number for pagination.
    - `parse` boolean — When true, the SERP response is parsed into structured JSON.
    - `query` string — The search keyword or phrase to query.
    - `render` boolean — Whether to render the page in a browser before extracting.
    - `search_engine` 'google_search' | 'google_sge' | 'google_aio' | 'google_maps_search' | 'google_maps_reviews' | 'google_maps_place' | 'google_news' | 'google_images' | 'bing_search' | 'yandex_search' — The search engine to query.
    - `show_hidden_results` boolean — When true, disables Google result filtering (filter=0) so omitted/duplicate and highly similar pages are also returned. Applies to Google search engines.
    - `callback_url` string — URL to call back when async operation completes
    - `storage_compress` boolean — Whether to compress stored data
    - `storage_object_name` string — Custom name for the stored object
    - `storage_type` string — Type of storage to use for results
    - `storage_url` string — URL for storage location
  - `shared_inputs` object — Shared parameters applied to the entire batch. Can include search parameters and async/storage settings.
    - `country` string — ISO Alpha-2 country code used to access the target search engine (e.g. US, DE, GB).
    - `device` 'desktop' | 'mobile' — Device type used for the search request.
    - `domain` string — Top-level domain for the search engine (e.g. "com", "co.uk", "de").
    - `locale` string — Locale used for the search request.
    - `location` string — Geo-location for the search (canonical Google location name).
    - `num_results` integer — Number of results to return (1–100).
    - `page` integer — The result page number for pagination.
    - `parse` boolean — When true, the SERP response is parsed into structured JSON.
    - `query` string — The search keyword or phrase to query.
    - `render` boolean — Whether to render the page in a browser before extracting.
    - `search_engine` 'google_search' | 'google_sge' | 'google_aio' | 'google_maps_search' | 'google_maps_reviews' | 'google_maps_place' | 'google_news' | 'google_images' | 'bing_search' | 'yandex_search' — The search engine to query.
    - `show_hidden_results` boolean — When true, disables Google result filtering (filter=0) so omitted/duplicate and highly similar pages are also returned. Applies to Google search engines.
    - `callback_url` string — URL to call back when async operation completes
    - `storage_compress` boolean — Whether to compress stored data
    - `storage_object_name` string — Custom name for the stored object
    - `storage_type` string — Type of storage to use for results
    - `storage_url` string — URL for storage location

## Response `200`

Batch created successfully

- SerpBatchResponse — Response when a batch of SERP tasks is created successfully.
  - `batch_id` string, required — Unique identifier for the batch.
  - `batch_size` number, required — Number of tasks in the batch.
  - `tasks` object[], required — List of created tasks.
    - `_query` unknown, required
    - `account_name` string — Account name that owns the task.
    - `api_type` 'web' | 'serp' | 'ecommerce' | 'social' | 'media' | 'agent' | 'extract' | 'fast-serp' | 'labs'
    - `batch_id` string, nullable — Batch ID if this task is part of a batch.
    - `created_at` string, required — Timestamp when the task was created.
    - `download_url` string, uri, nullable — URL for downloading the task results.
    - `error` string, nullable — Error message if the task failed.
    - `error_type` string, nullable — Classification of the error type.
    - `id` string, required — Unique task identifier.
    - `input` unknown, required
    - `modified_at` string — Timestamp when the task was last modified.
    - `output_url` string, nullable — Storage location of the output data.
    - `queue` string — Queue name the task was submitted to.
    - `state` 'pending' | 'queued' | 'in_progress' | 'success' | 'error', required — Current state of the task.
    - `status_code` number — HTTP status code from the task execution.
    - `status_url` string, uri, required — URL for checking the task status.

---

[API](https://skmtc.net/nimbleway/apis/api-gateway.md) · [All operations](https://skmtc.net/nimbleway/apis/api-gateway/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nimbleway/api-gateway/revisions/9bfe220b7a29/schema)