api-reference

# DataForSEO REST API Reference Curated REST endpoints with curl examples, for code that calls the API directly. Inside Claude Code the same endpoints are reached through the MCP server's `api_request` tool (see the `mcp-patterns` skill); the paths and bodies below are identical, only the transport differs. For the full documentation see [docs.dataforseo.com/v3](https://docs.dataforseo.com/v3/), or read one endpoint at a time with `docs_search`. For the complete OpenAPI schema see [github.com/dataforseo/OpenApiDocumentation](https://github.com/dataforseo/OpenApiDocumentation). ## Authentication DataForSEO uses HTTP Basic Authentication with the **API login** and the **API password** from the [API Access](https://app.dataforseo.com/api-access) page. The API password is generated by DataForSEO and is not your account password. ```bash curl -X POST "https://api.dataforseo.com/v3/dataforseo_labs/google/keyword_ideas/live" \ -u "${DATAFORSEO_LOGIN:-$DATAFORSEO_USERNAME}:${DATAFORSEO_PASSWORD}" \ -H "Content-Type: application/json" \ -d '[{"keywords": ["seo tools"], "location_name": "United States", "language_code": "en", "limit": 10}]' ``` The MCP server reads `DATAFORSEO_LOGIN` and `DATAFORSEO_PASSWORD`; `DATAFORSEO_USERNAME` is accepted as an alias of `DATAFORSEO_LOGIN`. **Base URL:** `https://api.dataforseo.com` **Method:** `POST` for the data endpoints; `GET` for locations, languages, models and account data **Body:** a JSON array of task objects `[{...}, {...}]`; a Live endpoint takes exactly one task per request Append `.ai` to a path (`/v3/serp/google/organic/live/advanced.ai`) for the cropped, LLM-friendly response; the MCP server does this for you by default. ## API Convention Endpoints follow `POST /v3/{api_module}/{engine or vendor}/{endpoint}/{mode}`: | Module | Example path | Returns | |--------|--------------|---------| | SERP | `/v3/serp/google/organic/live/advanced` | Organic SERP results | | Labs | `/v3/dataforseo_labs/google/keyword_ideas/live` | Keyword ideas | | Backlinks | `/v3/backlinks/backlinks/live` | Backlink list | | Keywords Data | `/v3/keywords_data/google_ads/search_volume/live` | Search volume | | OnPage | `/v3/on_page/lighthouse/live/json` | Lighthouse audit | | Content Analysis | `/v3/content_analysis/search/live` | Content citations | | Domain Analytics | `/v3/domain_analytics/technologies/domain_technologies/live` | Tech stack | | AI Optimization | `/v3/ai_optimization/llm_mentions/search_mentions/live` | LLM mentions | | Merchant | `/v3/merchant/amazon/products/live/advanced` | Amazon product search | | App Data | `/v3/app_data/google/app_listings/search/live` | App listings | | Business Data | `/v3/business_data/business_listings/search/live` | Local business listings | ## Response Format Full (non-`.ai`) response: ```json { "version": "0.1.20241203", "status_code": 20000, "status_message": "Ok.", "tasks": [{ "id": "...", "status_code": 20000, "result": [{ ... }], "result_count": 10, "cost": 0.075 }] } ``` **Status codes:** 20000 is success, 40000 and up is a client error, 50000 and up is a server error. The `.ai` response keeps only `id`, `status_code`, `status_message` and `items`, so it has no `cost` field. ## Top 5 Endpoints ### Keyword Ideas ```bash POST /v3/dataforseo_labs/google/keyword_ideas/live Body: [{"keywords": ["project management"], "location_name": "United States", "language_code": "en", "limit": 20}] ``` ### SERP Analysis ```bash POST /v3/serp/google/organic/live/advanced Body: [{"keyword": "best crm software", "location_name": "United States", "language_code": "en", "depth": 20}] ``` ### Backlinks Summary ```bash POST /v3/backlinks/summary/live Body: [{"target": "example.com", "include_subdomains": true}] ``` ### Lighthouse Audit ```bash POST /v3/on_page/lighthouse/live/json Body: [{"url": "https://example.com", "for_mobile": false}] ``` ### Domain Technologies ```bash POST /v3/domain_analytics/technologies/domain_technologies/live Body: [{"target": "example.com"}] ``` ## Detailed Endpoint References - [SERP and Labs endpoints](references/api-serp-labs.md) - [Backlinks and Keywords Data endpoints](references/api-backlinks-keywords.md) - [OnPage, Content Analysis, Domain Analytics, AI Optimization endpoints](references/api-onpage-content-domain.md) - Every task with a minimal body, including Merchant, App Data and Business Data: `../mcp-patterns/references/endpoint-paths.md`