{ "openapi": "3.0.1", "info": { "title": "Google SERP & AI Mode API — Search Results & Citations", "description": "Search Google for organic results, ads, local packs, People Also Ask and AI Overviews. Switch to Google AI Mode for answers and citations. Batch keywords, location targeting, pagination and domain rank tracking.", "version": "1.0", "x-build-id": "r27oNDTXi6n7wpXED" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/gauravlabs~google-serp-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-gauravlabs-google-serp-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/gauravlabs~google-serp-api/runs": { "post": { "operationId": "runs-sync-gauravlabs-google-serp-api", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/gauravlabs~google-serp-api/run-sync": { "post": { "operationId": "run-sync-gauravlabs-google-serp-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "queries" ], "properties": { "mode": { "title": "Search mode", "enum": [ "serp", "ai_mode" ], "type": "string", "description": "AI Mode is a separate Google search surface. AI Overviews are optional panels within normal SERPs.", "default": "serp" }, "queries": { "title": "Search keywords", "type": "array", "description": "1–1000 keywords. Duplicates are skipped. Maximum requests limits the run.", "items": { "type": "string" } }, "maxRequests": { "title": "Maximum requests per run", "minimum": 1, "maximum": 500, "type": "integer", "description": "Counts all attempts, including optional AI Overview follow-ups. This is a per-run cap.", "default": 10 }, "maxPagesPerQuery": { "title": "Maximum SERP pages per keyword", "minimum": 1, "maximum": 11, "type": "integer", "description": "SERP only. Each successful page is a billable request. AI Mode requires 1.", "default": 1 }, "start": { "title": "Starting SERP offset", "minimum": 0, "maximum": 100, "type": "integer", "description": "0, 10, 20, …100. Final offset cannot exceed 100. AI Mode requires 0.", "default": 0 }, "hl": { "title": "Interface language", "type": "string", "description": "Examples en, de, fr, hi. Interface language differs from the strict lr filter.", "default": "en" }, "gl": { "title": "Country perspective", "type": "string", "description": "Lowercase two-letter code, for example us, gb, in, de. Set this together with location.", "default": "us" }, "google_domain": { "title": "Google regional domain", "type": "string", "description": "Examples google.com, google.co.uk, google.de. Regional availability varies.", "default": "google.com" }, "device": { "title": "Device", "enum": [ "desktop", "mobile" ], "type": "string", "description": "Mobile SERPs may not report total result counts or next-page links.", "default": "desktop" }, "location": { "title": "Canonical Google location (optional)", "type": "string", "description": "Example New York,New York,United States. Must match Google's location name; also set gl." }, "uule": { "title": "Advanced UULE location (optional)", "type": "string", "description": "Encoded Google location. Takes precedence over location." }, "targetDomains": { "title": "Domains to track (optional)", "type": "array", "description": "Up to 100 domains, e.g. example.com. Returns observed organic positions in SERP mode. Not-found means absent from fetched pages, not absent from Google.", "items": { "type": "string" } }, "cache": { "title": "Allow cached SERP results", "type": "boolean", "description": "SERP only. False requests fresh results. Cached and fresh pages have the same Actor price.", "default": false }, "resolveGoto": { "title": "Resolve Google redirect links", "type": "boolean", "description": "SERP only. Best-effort destination URLs; unresolved links may remain Google redirects.", "default": true }, "resolveAiOverview": { "title": "Complete deferred AI Overviews", "type": "boolean", "description": "SERP only. May add one separately billable follow-up per deferred panel. Counts toward maxRequests. AI availability is not guaranteed.", "default": false }, "safe": { "title": "SafeSearch", "enum": [ "", "active" ], "type": "string", "description": "Use Google's default or request adult-content filtering in either mode.", "default": "" }, "lr": { "title": "Strict result language (SERP only)", "type": "string", "description": "Example lang_en or lang_de. Leave empty in AI Mode." }, "cr": { "title": "Strict result country (SERP only)", "type": "string", "description": "Example countryUS or countryDE. Leave empty in AI Mode." }, "time_period": { "title": "Time filter (SERP only)", "enum": [ "", "last_hour", "last_day", "last_week", "last_month", "last_year" ], "type": "string", "description": "Restrict SERP results by recency. Leave empty for AI Mode.", "default": "" }, "nfpr": { "title": "Disable spelling correction (SERP only)", "type": "boolean", "description": "Prevent automatic query correction. Leave false for AI Mode.", "default": false }, "filter": { "title": "Similar-results filter (SERP only)", "enum": [ "", "0", "1" ], "type": "string", "description": "Control Google's similar and omitted-results filtering. Leave empty for AI Mode.", "default": "" }, "requestTimeoutSecs": { "title": "Request timeout in seconds", "minimum": 60, "maximum": 180, "type": "integer", "description": "At least 60 seconds. No automatic Actor retries; failed fetches are not billed by this Actor.", "default": 90 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }