Agentic Platform
Documentation API reference Tools Skills

Tools

Google SERP

google_serp MCP Keywords Web search

Fetch the Google SERP for a given query (returns all data)

Fetch the Google SERP for a given query (returns all data). When `save_to_tmp_storage` is enabled, the SERP results are written to temporary project storage and a URL is returned instead of the inline results.

Playground

POST
item
query required

The search query to analyze

config
location_id

Location ID (optional)

location_request

Location request (ex: Paris, FR), will translate to location ID

country_code

ISO3166 country code (ex: GB)

lang_code

BCP47 language code (ex: "en", "en-GB")

device

Device to use for search (optional - defaults to mobile)

save_to_tmp_storage

Save the bulky result payload to Botify temporary storage and return the temporary URL instead of the payload. Use this to save output tokens.

limit

Limit the number of results (optional - defaults to 30)

data_level

Should we return just main information (item_type (organic, shopping, knowledge_graph, people_also_ask, people_also_search...), title, description, rank), or all information (featured snippets, ratings, prices, refinement chips...)

Credits

Fixed cost per item requested, plus one set of search results (live) per query. Every query is fetched while you wait, including the ones in a batch: this tool has no background route, so asking for many at once costs the same per query as asking for one.

These usage SKUs can be charged on a call.

SKU Credits Description
Tool call 1 per request Charged once per successful item, on top of any usage below.
Search results (live) 2 per query One organic search-results page for one query, fetched while you wait.

Schemas

item is what you send, config how the tool behaves, and the response is what you get back.

Item

object
Properties
query string required

The search query to analyze

max length 700

Example
{
  "query": "string"
}

Configuration

object
Properties
location_id integer | null

Location ID (optional)

Default: null

location_request string | null

Location request (ex: Paris, FR), will translate to location ID

Default: null

country_code string | null

ISO3166 country code (ex: GB)

Default: null

lang_code string | null

BCP47 language code (ex: "en", "en-GB")

Default: null

device string

Device to use for search (optional - defaults to mobile)

Values: mobile desktop

Default: "mobile"

save_to_tmp_storage boolean

Save the bulky result payload to Botify temporary storage and return the temporary URL instead of the payload. Use this to save output tokens.

Default: false

limit integer

Limit the number of results (optional - defaults to 30)

Default: 30

data_level string

Should we return just main information (item_type (organic, shopping, knowledge_graph, people_also_ask, people_also_search...), title, description, rank), or all information (featured snippets, ratings, prices, refinement chips...)

Values: main all

Default: "main"

Example
{
  "location_id": null,
  "location_request": null,
  "country_code": null,
  "lang_code": null,
  "device": "mobile",
  "save_to_tmp_storage": false,
  "limit": 30,
  "data_level": "main"
}

Response

object
Properties
results GoogleSearchRawResults

The SERP results. Omitted when `save_to_tmp_storage` is True; see `results_tmp_storage_url` instead.

Type: GoogleSearchRawResults

Default: null

results_tmp_storage_url string | null

Temporary storage URL of the SERP results. Returned instead of `results` when `save_to_tmp_storage` is True.

Default: null

location_name string required

description of output2

query string required

The search query to analyze

Example
{
  "results": null,
  "results_tmp_storage_url": null,
  "location_name": "string",
  "query": "string"
}

Type Definitions

1 type

These are the available sub-object types that can be used in the properties above.

GoogleSearchRawResults object
#
keyword string required
type string required
se_domain string required
location_code integer required
language_code string required
check_url string required
datetime string required
spell string | null required
item_types array required
se_results_count integer required
items_count integer required
items array required

Endpoints

POST http://agents.botify.com/{organization}/{project}/google_serp/process
POST http://agents.botify.com/{organization}/{project}/google_serp/batch_process
POST http://agents.botify.com/{organization}/{project}/google_serp/async_process
POST http://agents.botify.com/{organization}/{project}/google_serp/async_batch_process

See running a long job in the background for the polling flow.

cURL

curl -X POST "http://agents.botify.com/{organization}/{project}/google_serp/process" \
  -H "Authorization: Bearer $BOTIFY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "item": {
    "query": "<query>"
  }
}'

Over MCP

This tool is exposed as the MCP tool google_serp. An MCP client passes organization, project and item as tool arguments. Set up MCP →

Raw metadata