Overview

This overview covers the base URL, authentication, rate limits, pagination, and error formats for the Reporting API.

Base URL

All Reporting API requests should be made to:

https://v2.serpwatch.io/api

Endpoints are under the /reporting namespace.

Authentication

All API requests require a Bearer token. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Get your API key

1. In the SerpWatch app, open Account settings.
2. Select the API Details tab.
3. Click Generate API Key.
4. Copy the API key and store it securely.

Rate Limiting

Authenticated requests are rate-limited. The current limit is returned in response headers:

When rate limited, the API returns 429 with a retry_after field:

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please try again later.",
  "retry_after": 46
}

Pagination

List endpoints use cursor-based pagination. Use the cursor query parameter from links.next or meta.next_cursor.

GET /reporting/projects?cursor=eyJwcm9qZWN0cy5pZCI6MzMwODIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0

The keyword history endpoint uses page and per_page, and returns meta.date_range.max_allowed_days to indicate the maximum allowed date range.

Error Handling

Errors return JSON. Some endpoints return a structured error object, while others return a flat error format.

Structured error example:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}

Flat error example:

{
  "error": "UNAUTHORIZED",
  "message": "Missing API token"
}