Skip to main content
POST
/
search
/
batches
Batch results
curl --request POST \
  --url https://api.agentfirst.dev/search/batches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "terms": [
    "foo bar baz"
  ],
  "engine": "google",
  "serps": 1,
  "size": null,
  "offset": null,
  "device": null,
  "country": null,
  "subdivision": null,
  "city": null,
  "uule": null,
  "language": null,
  "display": null,
  "urls": [
    "https://www.google.com/search?q=foo+bar+baz&hl=fr&gl=fr&ie=UTF-8"
  ],
  "awaiting": "ai",
  "expiration": 0,
  "callback": "https://webhook.site/02e249f8-1faf-4fab-bcf5-78ce683e85a8"
}
'
{
  "id": "a0482596-c2ad-445a-a435-727002156a20",
  "count": 1
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
terms
string[]
required

The broad or exact words or phrases to query (e.g., foo bar baz or "foo bar baz").

Required array length: 1 - 1000 elements
Maximum string length: 255
Example:
["foo bar baz"]
​
engine
enum<string>
default:google

The search engine to use.

Available options:
google,
bing (coming soon)
Example:

"google"

​
serps
integer
default:1

The number of results pages to fetch.

Required range: 1 <= x <= 10
Example:

1

​
size
integer

The number of results per page to fetch; page size is unset by default.

Required range: 0 <= x <= 100
Example:

null

​
offset
integer

The number of initial results to skip; results aren’t offset by default.

Required range: 0 <= x <= 100
Example:

null

​
device
string

The name as returned by the devices resource [blocked] of the device to emulate searching on (these names are case insensitive); device emulation is unused by default.

Example:

null

​
country
string

The two-letter ISO code of the country to search from (these codes are case insensitive); a random country is used by default.

Example:

null

​
subdivision
string

The alphanumeric second part (proceeding the separator) of a first-level subdivision code in the (prerequisite) country to search from (these codes are case insensitive); a random subdivision is used by default.

Example:

null

​
city
string

The commonly spelled name of the city in the (prerequisite) country to search from (these names are temporarily case sensitive); a random city is used by default.

Example:

null

​
uule
string

The proprietary encoded string for emulating the location to search from; if possible, the actual location is searched from not emulated; location emulation is unused by default.

Example:

null

​
language
string

The commonly spelled name, two-letter ISO code, or Google code of the language to search in (these names and codes are case insensitive); the language is unset by default.

Example:

null

​
display
string

The commonly spelled name, two-letter ISO code, or Google code 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.

Example:

null

​
urls
string<uri>[]

The URLs of the results pages to retrieve; if given, the URLs override any of the above params.

Required array length: 1 - 1000 elements
Example:
[
  "https://www.google.com/search?q=foo+bar+baz&hl=fr&gl=fr&ie=UTF-8"
]
​
awaiting
enum<string>

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.

Available options:
ai,
answers,
ads
Example:

"ai"

​
expiration
integer
default:1

The age in days of when to consider cached results expired, where 0 disables caching.

Required range: 0 <= x <= 1
Example:

0

​
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.

Example:

"https://webhook.site/02e249f8-1faf-4fab-bcf5-78ce683e85a8"

Response

A job identifier and confirmation count.

​
id
string<uuid>
required

The identifier to retrieve the batch searches with.

Example:

"a0482596-c2ad-445a-a435-727002156a20"

​
count
integer
required

The number of queries in the batch as confirmed by the API.

Required range: 1 <= x <= 1000
Example:

1