Use the REST API

The Searcherries REST API gives scripts, spreadsheets and automation platforms read access to the data Searcherries has collected for your projects: AI visibility metrics, stored AI answers with their judgments, competitors, cited URLs and domains, Google Search Console and Bing Webmaster Tools snapshots, GA4 AI-traffic snapshots and a prioritized action plan. It returns the same datasets as the MCP connection, as JSON over HTTPS.

The API is read-only. It cannot edit projects, change questions, delete data, manage billing or trigger fresh calls to analytics providers. Every response is built from data Searcherries already stores, and each one says when that data was fetched. Read about data updates.

The API is available with paid-plan access, including an active eligible trial.

Base URL and format

All endpoints live under:

https://app.searcherries.com/api/v1

Requests use GET with query-string parameters. Responses are JSON documents. Booleans in the query string accept true, false, 1 and 0. Lists such as include accept a comma-separated value.

The machine-readable description of every endpoint, parameter and response is an OpenAPI 3.1 document at https://app.searcherries.com/openapi/v1.yaml. Import it into an API client or an integration platform to get the endpoints ready to call.

Authenticate

The API uses the personal access tokens of the MCP page. Create a token on the Other clients tab of MCP and send it as a bearer token:

Authorization: Bearer YOUR_TOKEN

YOUR_TOKEN is a placeholder for the value you generated. A token created for an MCP client works with the API as well, and a token revoked on the MCP page stops working everywhere at once. An account can have up to five active tokens; each one expires on the date shown in the table.

A request without a valid token receives 401. A token of an account without paid-plan access receives 403 with the error code paid_plan_required.

Try it

List your projects:

curl -H "Authorization: Bearer YOUR_TOKEN" https://app.searcherries.com/api/v1/projects

The response contains the numeric id of each project. Use it to read the project summary:

curl -H "Authorization: Bearer YOUR_TOKEN" https://app.searcherries.com/api/v1/projects/123

Replace 123 with your project id. The endpoint reference lists every endpoint and parameter.

Periods

AI visibility data (answers, competitors, citations, the metrics in the summary) uses report periods anchored to the latest completed check: last_30_days (default), last_60_days, last_90_days, this_year and last_year. A period without enough history falls back to the nearest available one, and the period object of the response says which period was used.

Connected sources (Google Search Console, Bing Webmaster Tools, GA4) are stored as rolling windows ending on the collection day: 30d, 90d and 365d. Their responses carry period, fetched_at and is_stale. When a source or a window has no stored data, the response says "available": false and explains why in reason.

Pagination

Datasets that return rows include a pagination object:

{
  "offset": 0,
  "limit": 25,
  "returned": 25,
  "total": 112,
  "has_more": true
}

Request the next page with a larger offset while has_more is true. The default page has 25 rows and the maximum is 100 (50 for competitors). Lists from connected sources are the stored top sample, not an exhaustive export.

Rate limits

Each account can make 60 requests per minute on Starter and 120 on Pro. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. When the budget is used up, the API answers 429 with a Retry-After header and the same number of seconds in retry_after. Wait and retry; do not retry in a tight loop.

Errors

Every error is a JSON object with one error key:

{
  "error": {
    "code": "validation_failed",
    "message": "The request parameters are invalid.",
    "status": 422,
    "errors": {
      "period": ["The selected period is invalid."]
    }
  }
}

Privacy and access

A token reads the data of the Searcherries account that created it and nothing else. Keep tokens out of public repositories, shared documents and screenshots; if one is exposed, revoke it on the MCP page and create a replacement.

The API serves stored data to the tool you connect. That tool may have its own subscription, usage charges and data-handling settings. Connect only tools you intend to use with your project data.