v2.0
Swagger UI Get Started

API Reference Overview

This reference documents all available endpoints in the SerpWatch API. Learn about the base URL, authentication, request formats, and response structures.

Base URL

All API requests should be made to:

https://engine.v2.serpwatch.io

The API only accepts HTTPS connections. HTTP requests will be rejected.

API Versioning

The API uses URL path versioning. The current versions are:

Version Path Prefix Status Notes
v2 /api/v2/ Current Google SERP with multi-page depth support
v1 /api/v1/ Stable Multi-engine support (Google, Bing, Yahoo, YouTube)

Which version should I use?

Use v2 for Google SERP crawling with advanced features like depth control. Use v1 for multi-engine support (Bing, Yahoo, YouTube) or keyword research endpoints.

Authentication

All API endpoints require authentication using a Bearer token in the Authorization header: 

Authorization: Bearer YOUR_API_KEY

See the Authentication guide for details on obtaining and using API keys.

Request Format

Content Type

All POST requests must include the Content-Type header:

Content-Type: application/json

Request Body

POST request bodies should be valid JSON. Parameters are case-sensitive and should use snake_case naming: 

{
  "keyword": "search query",
  "location_name": "United States",
  "device": "desktop",
  "depth": 10
}

Response Format

All responses are returned as JSON with appropriate HTTP status codes.

Successful Response

Successful requests return a 2xx status code with a JSON body:

200 OK 
{
  "id": "task_abc123",
  "status": "completed",
  "keyword": "search query",
  "result": {
    "organic": [...],
    "ads": [...]
  }
}

Error Response

Error responses include a detail field explaining the issue:

422 Unprocessable Entity 
{
  "detail": [
    {
      "loc": ["body", "keyword"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Endpoint Summary

Authentication

Method Endpoint Description
POST /token Get access token
POST /api/v1/users Create API key
GET /api/v1/users/me Get current user info

SERP Crawling (v2 - Google)

Method Endpoint Description
POST /api/v2/serp/crawl Create Google SERP task
POST /api/v2/serp/crawl/google/batch Create batch Google SERP tasks
GET /api/v2/serp/crawl/{task_id} Get task results

SERP Crawling (v1 - Multi-Engine)

Method Endpoint Description
POST /api/v1/serp/{engine}/crawl Create SERP task (google, bing, yahoo, youtube)
POST /api/v1/serp/{engine}/crawl/live Live SERP crawl (synchronous)
POST /api/v1/serp/crawl/{engine}/batch Create batch SERP tasks
GET /api/v1/serp/crawl/{task_id} Get task results
GET /api/v1/serp/crawl/{task_id}/html Get raw HTML
GET /api/v1/serp/crawl List crawl tasks

Keyword Data

Method Endpoint Description
POST /api/v1/keyword-sv Get keyword search volume
GET /api/v1/keyword-sv/{task_id} Get keyword data task result
POST /api/v1/keyword-sv/live Live keyword metrics (synchronous)

Keyword Research

Method Endpoint Description
POST /api/v1/keyword-research/ideas Get keyword suggestions
POST /api/v1/keyword-research/suggest/live Live autocomplete suggestions
POST /api/v1/keyword-research/trends/live Google Trends data

Common Parameters

These parameters are shared across multiple SERP endpoints:

Parameter Type Description
keyword string The search query to crawl
depth integer Number of results to fetch (1-100)
device string desktop or mobile
location_name string Geographic location (e.g., "United States", "New York,United States")
language_code string Language code (e.g., "en", "es", "fr")
postback_url string Webhook URL for result delivery
frequency integer Cache duration in hours

Task Statuses

Tasks progress through these statuses:

Status Description
awaiting Task queued, waiting to be processed
crawling Actively fetching search results
parsing Processing and structuring results
success Task completed successfully
completed Task completed (alias for success)
error Task failed (see error_message)

OpenAPI Specification

The complete OpenAPI specification is available at:

https://engine.v2.serpwatch.io/openapi.json

You can also explore the API interactively using: