REST API endpoint reference
Every endpoint is a GET request under https://app.searcherries.com/api/v1 with a bearer token. Read the overview for authentication, periods, pagination, rate limits and errors. The OpenAPI document at https://app.searcherries.com/openapi/v1.yaml describes the same endpoints for API clients.
Each endpoint returns the dataset of the MCP tool named next to it, so an analysis written against one surface applies to the other.
| Endpoint | MCP tool | Returns |
|---|---|---|
GET /projects | list-projects | Your projects with status, platforms, connected sources and data counts. |
GET /projects/{project} | get-project-summary | One compact snapshot of a project. |
GET /projects/{project}/answers | get-ai-answers | Stored AI answers with their judgments. |
GET /projects/{project}/search-performance | get-search-performance | Google Search Console or Bing data for one window. |
GET /projects/{project}/competitors | get-competitors | Brands the AI platforms name, ranked, in detail or by month. |
GET /projects/{project}/citations | get-citations | Cited URLs or domains. |
GET /projects/{project}/ai-traffic | get-ai-traffic | GA4 traffic from AI assistants and AI Overviews. |
GET /projects/{project}/action-plan | get-action-plan | Prioritized next steps with evidence. |
{project} is the numeric project id from GET /projects. An id that belongs to another account answers 404.
GET /projects
Lists the projects of your account. It takes no parameters.
Each project carries id, brand_name, brand_website, status, country, language, selected_ai_models, last_checked_at, connections (whether GA4, Search Console and Bing are connected), connected_data (freshness of the newest stored snapshot per source) and data_availability (counts of stored questions, answers, judgments, competitor snapshots and connected-source snapshots).
GET /projects/{project}
One compact snapshot of a project, about 16 KB. Blocks: profile (brand, market, business profile), questions (the primary question and up to 15 additional questions with their last and next check), ai_visibility (score, mentions by platform, change against the previous period, share of voice), answer_insights (how often and how prominently the brand is named, negative and off-topic answers), competitors (own brand and top 10), citations (top cited domains), search (30-day Google and Bing totals with top-5 lists), ai_traffic (30-day GA4 AI traffic), connections (health) and recommendations (latest summary).
| Parameter | Meaning |
|---|---|
period | AI visibility period. Default last_30_days. |
include | Blocks to include, comma-separated. Omit for the whole summary. |
The response repeats the blocks it contains in included and links the project report in report_url.
GET /projects/{project}/answers
Stored AI answers, one row per check and platform, joined with their judgments: prominence_level (0 not named, 1 named in passing, 2 one of the options, 3 top recommendation), on_topic, names_brands, brand_sentiment, brand_drawback, evidence_quote, cited URLs and the web searches the platform ran. brand_mentioned is null for answers the nightly judgment has not reached yet.
| Parameter | Meaning |
|---|---|
period | Report period; ignored when since or until is given. |
since, until | Check dates, YYYY-MM-DD. |
prompt_id | One customer question (its id in the project summary). |
platform | One AI platform: chatgpt, perplexity, ai_overviews, gemini, claude or grok. |
prominence_max | Keep answers with prominence at most this level. 1 lists the gaps. |
only_flagged | Only negative, drawback or off-topic answers. |
include_answer_text | Include the answer text. Caps the page at 20 rows. |
max_answer_chars | Characters per answer when text is included (200 to 20000, default 1200). |
limit, offset | Pagination, 1 to 100 rows. |
A prompt_id of another project is a 422 on prompt_id.
GET /projects/{project}/search-performance
Google Search Console or Bing Webmaster Tools data for one window.
| Parameter | Meaning |
|---|---|
source | google (default) or bing. |
period | 30d (default), 90d, 365d. |
dataset | summary (default), top_queries, top_pages, top_countries, queries_by_country, opportunities, trends, ai_question_queries (Google only), daily, history. |
query_contains, page_contains, country | Text filters on the list datasets. |
min_impressions, min_clicks, min_position, max_position | Numeric filters. |
sort | clicks (default), impressions, ctr, position. |
limit, offset | Pagination for list datasets. |
Lists are the stored top sample (up to 50 rows per dimension, up to 1000 question-shaped queries), not an exhaustive export. history sums the daily series per calendar month.
GET /projects/{project}/competitors
| Parameter | Meaning |
|---|---|
period | Report period. |
dataset | ranking (default), detail, history. |
competitor | Brand name or a fragment of it. Required for detail. |
include_highlights, highlights_per_platform | Highlight sentences per platform in the ranking (default 3, maximum 5). |
limit, offset | Rows for ranking (default 15, maximum 50) or months for history (default 12). |
ranking returns one row per brand for the period, the own brand included, ranked by visibility. history returns the stored month-by-month snapshots.
GET /projects/{project}/citations
| Parameter | Meaning |
|---|---|
period | Report period. |
group_by | url (default) or domain. |
platform, prompt_id, url_contains | Filters for the URL grouping. |
own_site_only | Only URLs on the project website. |
limit, offset | Pagination. |
GET /projects/{project}/ai-traffic
| Parameter | Meaning |
|---|---|
period | 30d (default), 90d, 365d. |
dataset | summary (default), sources, landing_pages, daily, history. |
source | One AI source: chatgpt, gemini, perplexity, claude, copilot, meta_ai, other_ai_assistants or ai_overviews. |
path_contains | Filter on landing page paths. |
limit, offset | Pagination for landing_pages. |
GET /projects/{project}/action-plan
Prioritized next steps for a project.
| Parameter | Meaning |
|---|---|
audience | business (default) for traffic and business priorities, marketing for brand answers and content, seo for search pages and queries. |
period | AI visibility period. Default last_30_days. Search and traffic use their own rolling 30-day snapshots. |
limit | Maximum number of actions, 1 to 10 (default 5). Fewer are returned when the evidence is thin. |
The response has a status (ready, needs_data or no_priority_signals), the actions, data_notes about missing or stale sources and a snapshot of the project. Each action carries a title, a suggested owner, the next step, dated evidence, a success measure, a link to the matching Searcherries report and next_request, the API request that returns the supporting rows.
Actions come from four stored signals: answers that are negative about the brand or name a drawback, answers where the brand is not named, Search Console and Bing queries with many impressions and few clicks, and the landing pages of AI visitors. The order follows the chosen audience. The plan is a suggestion built from stored data; it does not estimate impact, effort or revenue.
Size and freshness
Responses are single JSON documents. The project summary stays around 16 KB, the action plan within about 24 KB, and the other endpoints within about 40 KB at default limits. Check period, fetched_at and is_stale before combining numbers from different endpoints.