> For the complete documentation index, see [llms.txt](https://help.rankability.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.rankability.com/api/api-search-intelligence.md). # Search Intelligence API endpoints Run a single query across Google plus the major AI search platforms (ChatGPT, Perplexity, Gemini, Claude, Grok, Bing) and get structured per-platform results in one call. Includes brand and domain extraction. The Search Intelligence agent API lets you run a single search query in parallel across Google and the major AI platforms, then get back a structured response with per-platform results, citations, and (optionally) brand/domain extraction. Use it to power external dashboards, citation monitors, and AI-search visibility reports. ## Endpoints at a glance | Method & Path | Scope | Purpose | | ---------------------------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `POST /api/agent/v1/search-intelligence/query` | `search_intelligence:query` | Run a query across the requested platforms. **Synchronous** — returns once all platforms settle or the 90s budget expires. | | `GET /api/agent/v1/search-intelligence/query/:runId` | `search_intelligence:query` | Fetch a previously-run query by `runId`. Useful when the original POST timed out at the wall-clock budget but partial state is in the DB. | ## Authentication and scope Both endpoints use the standard agent API auth: `Authorization: Bearer rk_live_...`. Add the `search_intelligence:query` scope to your API key under **Settings > API keys** (the scope name in the picker is exactly `search_intelligence:query`). Before provider work, read the current usage contract and call `GET /api/agent/v1/usage/estimate?operation=search_intelligence_query&platform_count=4` with the intended provider count. The estimate starts no query. Full-platform pooled accounts receive standard or high impact; the current legacy Agent API contract reports no customer credit deduction but the query still invokes providers and requires approval in an agent workflow. ## Supported platforms The `platforms` field accepts any subset of the following (max 7): * `google_organic` — Google organic SERP results (parsed) * `chatgpt` — ChatGPT response with citations * `perplexity` — Perplexity answer with sources * `gemini` — Google Gemini response * `claude` — Anthropic Claude response * `grok` — xAI Grok response * `bing` — Bing organic SERP results If `platforms` is omitted, the default set is `["google_organic", "chatgpt", "perplexity", "gemini"]`. ## Run a query ``` POST /api/agent/v1/search-intelligence/query Authorization: Bearer rk_live_YOUR_KEY Content-Type: application/json { "query": "best crm for small business", "platforms": ["google_organic", "chatgpt", "perplexity", "gemini"], "location": "United States", "gl": "us", "language": "en", "hl": "en", "device": "desktop", "includeRaw": false, "extract": { "brands": ["HubSpot", "Salesforce", "Pipedrive"], "domains": ["hubspot.com", "salesforce.com", "pipedrive.com"] } } ``` | Field | Type | Required | Default | Description | | ----------------- | ------- | -------- | ----------------- | ---------------------------------------------------------------------------------------- | | `query` | string | Yes | — | The search query. 1–250 characters. | | `platforms` | array | No | see above | Up to 7 platform identifiers. Duplicates rejected. | | `location` | string | No | `"United States"` | Display name of the search location (max 255 chars). | | `gl` | string | No | `"us"` | Two-letter country code for SERP context. | | `language` | string | No | `"en"` | Language code (e.g. `en`, `es`, `de`). | | `hl` | string | No | `"en"` | UI language hint passed to providers that accept it. | | `device` | enum | No | `"desktop"` | `"desktop"` or `"mobile"`. | | `includeRaw` | boolean | No | `false` | If `true`, the response includes the raw upstream payload per platform (larger payload). | | `extract.brands` | array | No | — | Up to 20 brand names to detect mentions of in each platform's response. | | `extract.domains` | array | No | — | Up to 20 domains to detect citations of in each platform's response. | ## Response (200 OK) The response includes the `runId`, the query parameters, the requested platforms, and a per-platform result array. Each platform entry contains its raw answer (when `includeRaw: true`), parsed citations, and — when `extract` was provided — brand-mention and domain-citation flags. ``` { "runId": "0a1b2c3d-...", "query": "best crm for small business", "requestedPlatforms": ["google_organic", "chatgpt", "perplexity", "gemini"], "completedPlatforms": ["google_organic", "chatgpt", "perplexity", "gemini"], "failedPlatforms": [], "parameters": { "location": "United States", "gl": "us", "language": "en", "hl": "en", "device": "desktop" }, "results": [ { "platform": "google_organic", "status": "success", "answer": null, "citations": [ { "url": "https://hubspot.com/...", "title": "..." }, ... ], "extract": { "brands": { "HubSpot": true, "Salesforce": true }, "domains": { "hubspot.com": true } } }, { "platform": "chatgpt", "status": "success", "answer": "For small businesses, HubSpot is often recommended ...", "citations": [ ... ], "extract": { ... } } ], "createdAt": "2026-05-12T15:32:00.000Z" } ``` ## Limits and timing * **Per-platform timeout:** 45 seconds. * **Total endpoint budget:** 90 seconds. If the orchestrator overruns, the POST returns `504 timeout`. The 504 envelope does not include a `runId`, so retry the POST rather than trying to hydrate a partial run. * **Concurrency:** Up to 4 platforms run in parallel internally. * **Brand / domain extraction:** Up to 20 entries each. ## Partial-failure behaviour If **some** platforms succeed and others fail, the response is still `200 OK`. Failed platforms appear in `failedPlatforms` with an error code, and successful platforms appear in `results` with `status: "success"`. If **all** requested platforms fail, the endpoint returns `502` with a top-level `runId` so you can still hydrate the partial DB state. The body shape is: ``` { "runId": "0a1b2c3d-...", "error": { "code": "all_platforms_failed", "message": "All requested platforms failed" }, "response": { ...same shape as the success response... } } ``` ## Hydrate a previous run ``` GET /api/agent/v1/search-intelligence/query/{runId}?includeRaw=true Authorization: Bearer rk_live_YOUR_KEY ``` The `includeRaw` query parameter is optional and defaults to `false`. The response is the same shape as the POST response. Add `view=summary` to either the POST or GET route for a bounded operational response. Summary view retains run identity, requested/completed/failed platforms, parameters, timestamps, per-platform status, latency, citation and organic-result counts, answer presence, extracted-entity flags, and errors. It omits answer text, citations, organic-result rows, and raw provider payloads. `view=full` preserves the normalized response; `includeRaw=true` is honored only with full view. Send a stable `Idempotency-Key` header on POST retries. Rankability replays the saved response within the Agent API idempotency window instead of repeating the provider fan-out. ## MCP equivalents Use `search_intelligence_run` to start the synchronous provider fan-out and `search_intelligence_get` to read the saved run. MCP defaults to summary view; request full normalized evidence only after the run is known, and keep raw provider payloads off unless they are specifically required. Estimate `search_intelligence_query`, show the selected platform count and current usage state, obtain approval, and reuse one idempotency key. ## Error codes | HTTP | Code | When | | ---- | ---------------------- | -------------------------------------------------------------------------------------------------------------------- | | 400 | `invalid_input` | Missing or oversized `query`, unknown platform identifier, duplicate platforms, brands/domains array over 20. | | 401 | `unauthorized` | Missing or invalid `Authorization` header. | | 403 | `forbidden` | API key is missing the `search_intelligence:query` scope. | | 404 | `not_found` | `runId` not found in your org. | | 429 | `rate_limited` | Per-minute rate limit exceeded. | | 502 | `all_platforms_failed` | All requested platforms failed. `runId` is still returned at the top level. | | 504 | `timeout` | Wall-clock budget (90s) exceeded. The 504 envelope does not return a `runId` — retry the POST rather than hydrating. | ## Common gotcha The endpoint is `POST .../search-intelligence/query` — not `GET .../search-intelligence`. A `GET` on the bare path returns the unknown-route fallthrough; make sure you're posting JSON to the `/query` sub-path. ## Related articles * [Getting started with the API](/api/api-getting-started.md) — Overview of the agent API and authentication. * [Authentication and API keys](/api/api-authentication.md) — How to create keys and add scopes. * [API usage, rate limits, and errors](/api/api-credits-rate-limits-and-errors.md) — Pooled usage, rate limits, and error codes. * [Page Auditor API endpoints](/api/api-page-auditor.md) — The other recently-published agent endpoint.