---
title: "Batch results"
method: POST
path: "/search/batches"
---

# Batch results

`POST /search/batches`

Queue multiple searches for later retrieval.

## Request body

- union
  - object
    - `terms` string[], required — The broad or exact words or phrases to query (e.g., `foo bar baz` or `"foo bar baz"`).
    - `engine` 'google' | 'bing (coming soon)' — The search engine to use.
    - `serps` integer — The number of results pages to fetch.
    - `size` integer — The number of results per page to fetch; page size is unset by default.
    - `offset` integer — The number of initial results to skip; results aren’t offset by default.
    - `device` string — The name as returned by the [devices resource](devices) of the device to emulate searching on (these names are case insensitive); device emulation is unused by default.
    - `country` string — The [two-letter ISO code](https://www.iso.org/obp/ui/#search/code) of the country to search from (these codes are case insensitive); a random country is used by default.
    - `subdivision` string — The alphanumeric second part (proceeding the separator) of a [first-level subdivision code](https://www.iso.org/obp/ui/#search/code) in the (prerequisite) country to search from (these codes are case insensitive); a random subdivision is used by default.
    - `city` string — The [commonly spelled name](https://www.geonames.org/) of the city in the (prerequisite) country to search from (these names are temporarily case sensitive); a random city is used by default.
    - `uule` string — The [proprietary encoded string](https://moz.com/blog/geolocation-the-ultimate-tip-to-emulate-local-search) for emulating the location to search from; if possible, the actual location is searched from not emulated; location emulation is unused by default.
    - `language` string — The commonly spelled name, [two-letter ISO code](https://www.loc.gov/standards/iso639-2/php/code_list.php), or [Google code](https://www.google.com/advanced_search) of the language to search in (these names and codes are case insensitive); the language is unset by default.
    - `display` string — The commonly spelled name, [two-letter ISO code](https://www.loc.gov/standards/iso639-2/php/code_list.php), or [Google code](https://www.google.com/advanced_search) of the search interface’s display language (these names and codes are case insensitive); the display language is unset by default or set to the language if given.
    - `urls` string[] — The URLs of the results pages to retrieve; if given, the URLs override any of the above params.
    - `awaiting` 'ai' | 'answers' | 'ads' — The lazy result features to wait to load; any AI overview, which can take significant time to generate, is awaited for a maximum of **1 minute**; multiple features can be provided by repeating the key; lazy results aren’t awaited by default.
    - `expiration` integer — The age in days of when to consider cached results expired, where `0` disables caching.
    - `callback` string — The HTTP or HTTPS callback URL or Amazon SQS queue URL or ARN to notify when the batch results have been retrieved; any SQS queue must grant `sqs:SendMessage` permission to the `arn:aws:iam::180363035301:role/api-instance` AWS principal.
  - object
    - `terms` string[] — The broad or exact words or phrases to query (e.g., `foo bar baz` or `"foo bar baz"`).
    - `engine` 'google' | 'bing (coming soon)' — The search engine to use.
    - `serps` integer — The number of results pages to fetch.
    - `size` integer — The number of results per page to fetch; page size is unset by default.
    - `offset` integer — The number of initial results to skip; results aren’t offset by default.
    - `device` string — The name as returned by the [devices resource](devices) of the device to emulate searching on (these names are case insensitive); device emulation is unused by default.
    - `country` string — The [two-letter ISO code](https://www.iso.org/obp/ui/#search/code) of the country to search from (these codes are case insensitive); a random country is used by default.
    - `subdivision` string — The alphanumeric second part (proceeding the separator) of a [first-level subdivision code](https://www.iso.org/obp/ui/#search/code) in the (prerequisite) country to search from (these codes are case insensitive); a random subdivision is used by default.
    - `city` string — The [commonly spelled name](https://www.geonames.org/) of the city in the (prerequisite) country to search from (these names are temporarily case sensitive); a random city is used by default.
    - `uule` string — The [proprietary encoded string](https://moz.com/blog/geolocation-the-ultimate-tip-to-emulate-local-search) for emulating the location to search from; if possible, the actual location is searched from not emulated; location emulation is unused by default.
    - `language` string — The commonly spelled name, [two-letter ISO code](https://www.loc.gov/standards/iso639-2/php/code_list.php), or [Google code](https://www.google.com/advanced_search) of the language to search in (these names and codes are case insensitive); the language is unset by default.
    - `display` string — The commonly spelled name, [two-letter ISO code](https://www.loc.gov/standards/iso639-2/php/code_list.php), or [Google code](https://www.google.com/advanced_search) of the search interface’s display language (these names and codes are case insensitive); the display language is unset by default or set to the language if given.
    - `urls` string[], required — The URLs of the results pages to retrieve; if given, the URLs override any of the above params.
    - `awaiting` 'ai' | 'answers' | 'ads' — The lazy result features to wait to load; any AI overview, which can take significant time to generate, is awaited for a maximum of **1 minute**; multiple features can be provided by repeating the key; lazy results aren’t awaited by default.
    - `expiration` integer — The age in days of when to consider cached results expired, where `0` disables caching.
    - `callback` string — The HTTP or HTTPS callback URL or Amazon SQS queue URL or ARN to notify when the batch results have been retrieved; any SQS queue must grant `sqs:SendMessage` permission to the `arn:aws:iam::180363035301:role/api-instance` AWS principal.

## Response `202`

A job identifier and confirmation count.

- object
  - `id` string, uuid, required — The identifier to retrieve the batch searches with.
  - `count` integer, required — The number of queries in the batch as confirmed by the API.

## Other responses

- `401` — The authorization header was missing.
- `402` — No more credits are available.
- `403` — The API token was invalid.
- `422` — One or more parameters were invalid.
- `500` — An unknown error occurred.

## Changes

> 9 revisions in range; 1 could not be searched.

- **2026-07-06** `bfddf5b2c698` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/joinmassive/apis/massive/changes/search/batches/post.md)

---

[API](https://skmtc.dev/joinmassive/apis/massive.md) · [All operations](https://skmtc.dev/joinmassive/apis/massive/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/joinmassive/massive/revisions/3a9f7769563f/schema)