One endpoint for each thing you can do: read your account, businesses, keywords, scans, reviews and listings, or start scans.
Base URL: https://citednearby.com. Requests and answers are JSON.
Every endpoint answers with your own account's data inside a data field. Ids are UUIDs. Each one gives the same data as the MCP tool of the same name, so you can switch between them freely.
The POST endpoints start scans and use credits, charged exactly as in the dashboard. They need an API key with "Can start scans" ticked, take a JSON body and answer 202 straight away: the scans run in the background, usually for 1 to 3 minutes. Follow them with GET /api/v1/scans/{id} until the status is completed.
What the key can do: read, and scan if "Can start scans" was ticked.
data.api_key.expires_at
When the key stops working (ISO 8601), or null if it does not expire.
JSON
{
"message": "Unauthenticated."
}
GET
/api/v1/account
Your credits, plan, the AI engines it includes and what each kind of scan costs.
Returns: The signed-in account: name, credit balance, plan, monthly credits, the AI engines the plan can scan, how many businesses are used and allowed, whether this connection can start scans, and what scans cost in credits (per map scan by grid size, per AI answer, per Web Search page). Call this first, and before a large scan.
Same data as the MCP tool get_account.
Lists are cut to 3 items here; real answers have them all.
GET
/api/v1/businesses
Every business in your account.
Returns: Every business in the account: id, name, category, address, website, phone, how many keywords are tracked, its latest finished map scan in one line, and a dashboard link. The business id is what the other tools take.
Same data as the MCP tool list_businesses.
One business with its overview across maps, AI, Web Search, reviews, listings and campaigns.
Returns: One business with its overview: details, what needs attention, its keywords with their latest results per platform, campaigns, review rating per site, listing watch status, the latest citation audit summary, and a dashboard link. The best single call for "how is this business doing".
Same data as the MCP tool get_business.
Parameter
In
Type
Description
business_id
path
string
The business id (UUID) from GET /api/v1/businesses.
Lists are cut to 3 items here; real answers have them all.
GET
/api/v1/businesses/{business_id}/reviews
A business' review profiles per site and its latest reviews.
Returns: A business' review profiles per review site (rating on a 5-star scale, review count, link, when last checked) and its most recent reviews (rating, text cut to about 600 characters, author, date, whether the owner replied). Filter reviews by site, a maximum rating (for example 3 to see the unhappy ones) and a start date. Returns 20 reviews unless limit is given (max 50).
Same data as the MCP tool get_reviews.
Parameter
In
Type
Description
business_id
path
string
The business id (UUID) from GET /api/v1/businesses.
Lists are cut to 3 items here; real answers have them all.
GET
/api/v1/businesses/{business_id}/listings
A business' citation audit, Google listing watch and backlink gaps.
Returns: A business' listings health: the latest citation audit (directories it is found on, missing, with a wrong name, address or phone, and where competitors are listed but the business is not), the Google listing watch (status, last check, recent changes to the Google profile) and the top backlink gaps.
Same data as the MCP tool get_listings.
Parameter
In
Type
Description
business_id
path
string
The business id (UUID) from GET /api/v1/businesses.
Lists are cut to 3 items here; real answers have them all.
GET
/api/v1/keywords
Your tracked keywords with their latest results.
Returns: Tracked keywords (the searches a business is tracked for), most recently scanned first, up to 100. Each has its platform, the latest and previous headline figure (ATRP for Google Maps where lower is better, mention rate for AI where higher is better, Google position for Web Search where lower is better), the change (positive means better), how many scans it has and a dashboard link. Filter by business and platform.
Same data as the MCP tool list_keywords.
Parameter
In
Type
Description
business_id
query
string
Only this business (UUID from list_businesses). Optional.
platform
query
string: google_maps, google_search, google_ai_overview, google_ai_mode, chatgpt, gemini, perplexity, grok, claude
Only this platform: google_maps, google_search (Web Search) or an AI engine. Optional.
Lists are cut to 3 items here; real answers have them all.
GET
/api/v1/keywords/{keyword_id}/history
A keyword's finished scans in date order, to chart it over time.
Returns: The finished scans of one tracked keyword in date order (oldest first), each with its headline figures: the trend of that keyword. Takes the keyword id from list_keywords. Returns the latest 20 scans unless limit is given (max 100).
Same data as the MCP tool get_keyword_history.
Parameter
In
Type
Description
keyword_id
path
string
The keyword id (UUID) from GET /api/v1/keywords.
limit
query
integer (min 1, max 100)
How many of the latest scans to return (default 20). Optional.
Lists are cut to 3 items here; real answers have them all.
GET
/api/v1/campaigns
Your campaigns with their schedule, keywords and what a run costs.
Returns: Campaigns (scheduled scans of several keywords, which can mix Google Maps, Web Search and AI engines): id, business, keywords, platforms, schedule, whether active, next and last run, last run status and the credits one run uses. The campaign id is what run_campaign takes.
Same data as the MCP tool list_campaigns.
Parameter
In
Type
Description
business_id
query
string
Only this business (UUID from list_businesses). Optional.
Returns: Scans, newest first: id, business, keyword, platform, status, progress, dates, credits used, headline figures when finished, and a dashboard link. Filter by business, keyword, campaign, platform, status or a start date. Returns 20 unless limit is given (max 100). Use get_scan for one scan in full.
Same data as the MCP tool list_scans.
Parameter
In
Type
Description
business_id
query
string
Only this business (UUID from list_businesses). Optional.
keyword_id
query
string
Only this tracked keyword (UUID from list_keywords). Optional.
campaign_id
query
string
Only scans started by this campaign (UUID from list_campaigns). Optional.
platform
query
string: google_maps, google_search, google_ai_overview, google_ai_mode, chatgpt, gemini, perplexity, grok, claude
Only this platform. Optional.
status
query
string: pending, running, completed, failed
Only scans in this status. Optional.
since
query
string
Only scans started on or after this date (YYYY-MM-DD). Optional.
Lists are cut to 3 items here; real answers have them all.
GET
/api/v1/scans/{scan_id}
One scan in full: settings, figures, the grid of ranks and competitors (maps), brands and sources (AI) or the results above you (Web Search).
Returns: One scan in full: settings, status and progress (call again until status is completed), the headline figures, and by kind. Google Maps scan: ATRP, ARP, Local Visibility, the grid of ranks (rows north to south) and the top competitors. AI scan: mention rate, share of voice, average position, the businesses and websites the answers named, and per-town results or the grid. Web Search check: the position and page of the website and the results above it. Includes the previous scan of the same keyword for comparison and a dashboard link.
Same data as the MCP tool get_scan.
Parameter
In
Type
Description
scan_id
path
string
The scan id (UUID) from GET /api/v1/scans.
include_grid
query
boolean
Include the grid of ranks (default true). Turn it off for a shorter answer. Optional.
{
"data": {
"id": "ff6e4435-5d73-4701-8dab-131c52b6b06b",
"business": {
"id": "4130d4b5-f65a-4b38-8fa2-db5d69fa21eb",
"name": "Slice & Crust Midtown"
},
"keyword": "pizza delivery",
"platform": "google_maps",
"platform_label": "Google Maps",
"status": "completed",
"progress": "25/25",
"sample": "5 × 5 grid",
"created_at": "2026-10-22T22:49:17+00:00",
"completed_at": "2026-10-22T22:49:17+00:00",
"credits_used": 25,
"result": {
"atrp": 6.7,
"arp": 4.7,
"local_visibility_percent": 40,
"points_found": 22,
"points_scanned": 25
},
"failure_reason": null,
"url": "https://citednearby.com/dashboard/rank-scans/ff6e4435-5d73-4701-8dab-131c52b6b06b",
"settings": {
"grid_size": 5,
"radius": 2,
"distance_unit": "mi",
"points_switched_off": 0
},
"previous_scan": {
"id": "c45f34dd-d735-4b14-bb27-01f5d89f23b3",
"date": "2026-10-15T22:49:16+00:00",
"result": {
"atrp": 6.7,
"arp": 4.7,
"local_visibility_percent": 40,
"points_found": 22,
"points_scanned": 25
}
},
"metrics": {
"atrp": 6.7,
"arp": 4.7,
"local_visibility_percent": 40,
"points_scanned": 25,
"points_found": 22,
"points_in_top_3": 10,
"meaning": "ATRP: average rank over all points, 21 counts as not found (lower is better). ARP: average rank where found. Local Visibility: share of points where the business is in the top 3."
},
"competitors": [
{
"name": "Columbus Circle Pizzeria",
"is_you": false,
"category": "Pizza restaurant",
"address": "1600 Example Ave, New York, NY 10019",
"rating": 4.2,
"reviews": 2036,
"atrp": 4.4,
"local_visibility_percent": 44,
"best_rank": 1,
"points_appearing": 24
},
{
"name": "Koreatown Pizza Bar",
"is_you": false,
"category": "Pizza restaurant",
"address": "20 Example St, New York, NY 10016",
"rating": 4.2,
"reviews": 3634,
"atrp": 4.8,
"local_visibility_percent": 48,
"best_rank": 1,
"points_appearing": 23
},
{
"name": "Garment District Slice",
"is_you": false,
"category": "Pizza restaurant",
"address": "1400 Example Ave, New York, NY 10018",
"rating": 4.5,
"reviews": 17266,
"atrp": 4.9,
"local_visibility_percent": 68,
"best_rank": 1,
"points_appearing": 22
}
],
"grid": [
[
8,
9,
5,
2,
2
],
[
"-",
"-",
5,
1,
2
],
[
8,
10,
3,
2,
3
],
[
5,
4,
3,
6,
8
],
[
2,
1,
6,
"-",
9
]
],
"grid_legend": "Rows run north to south, columns west to east. A number is the business' rank at that point; \"-\" not in the top 20; \"off\" switched off; \"?\" not scanned yet or failed."
}
}
Lists are cut to 3 items here; real answers have them all.
POST
/api/v1/scans/map
Uses credits
Start a Google Maps geo-grid scan of a keyword.
Returns: Start a Google Maps geo-grid scan of a keyword for a business. Uses credits: one per grid point (a 7x7 grid is 49), charged as in the dashboard (get_account lists the costs). Without grid settings it uses the keyword's existing grid, else the grid sized to the business' competition, else 7x7. Returns the scan id, the credits used and left and a dashboard link; results are usually ready in 1-3 minutes: call get_scan with the id. Only run it when the user asked for a scan.
Same data as the MCP tool run_map_scan.
Parameter
In
Type
Description
business_id
body
string
The business id (UUID) from list_businesses.
keyword
body
string
What customers search, e.g. "emergency plumber".
grid_size
body
integer: 3, 5, 7, 9, 11, 13, 15, 17, 19, 21
Points per side of the grid (3, 5, 7 ... 21). More points cost more credits. Optional. Optional.
radius
body
number (min 0.1, max 50)
Distance from the center to the edge of the grid, in the distance unit. Optional. Optional.
{
"data": {
"message": "Scan started. Results are usually ready in 1-3 minutes: call GET /api/v1/scans/{id} with this id (8bee8160-2b00-456c-b2d2-f14db076d326) to see progress and results.",
"credits_used": 49,
"credits_left": 4896,
"scans": [
{
"id": "8bee8160-2b00-456c-b2d2-f14db076d326",
"business": {
"id": "4130d4b5-f65a-4b38-8fa2-db5d69fa21eb",
"name": "Slice & Crust Midtown"
},
"keyword": "pizza delivery",
"platform": "google_maps",
"platform_label": "Google Maps",
"status": "running",
"progress": "0/49",
"sample": "7 × 7 grid",
"created_at": "2026-10-22T22:49:18+00:00",
"completed_at": null,
"credits_used": 49,
"result": null,
"failure_reason": null,
"url": "https://citednearby.com/dashboard/rank-scans/8bee8160-2b00-456c-b2d2-f14db076d326"
}
],
"dashboard_url": "https://citednearby.com/dashboard/rank-scans/8bee8160-2b00-456c-b2d2-f14db076d326"
}
}
POST
/api/v1/scans/ai
Uses credits
Ask AI engines a customer's question and see whether they recommend the business.
Returns: Ask AI engines a question customers ask (for example "who is the best plumber in Austin?") and see whether they recommend the business. One scan per engine. Uses credits: one per AI answer, charged as in the dashboard; get_account lists the engines the plan includes and the cost. Google AI Overviews and AI Mode are asked over a small grid around the business; ChatGPT, Gemini, Perplexity, Grok and Claude are asked several times about each town. Returns the scan ids, the credits used and left and a dashboard link; results are usually ready in 1-3 minutes: call get_scan with each id. Only run it when the user asked for a scan.
Same data as the MCP tool run_ai_scan.
Parameter
In
Type
Description
business_id
body
string
The business id (UUID) from list_businesses.
prompt
body
string
The question to ask, as a customer would, e.g. "best pizza near me". "near me" becomes the town; or write {location} where the town goes.
platforms
body
array of string
Which AI engines to ask: google_ai_overview, google_ai_mode, chatgpt, gemini, perplexity, grok, claude. Only engines in the plan work (get_account lists them).
towns
body
array of string
Towns the chat assistants are asked about, e.g. "Chelsea, New York". Default: the business' own town. Optional.
answers_per_town
body
integer (min 1, max 10)
How many times each town is asked (more is steadier, and costs more). Default 5. Optional.
Example request
curl
curl -X POST "https://citednearby.com/api/v1/scans/ai" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"business_id":"BUSINESS_ID","prompt":"best pizza near me","platforms":["chatgpt","google_ai_overview"]}'
JSON
{
"data": {
"message": "2 scans started. Results are usually ready in 1-3 minutes: call GET /api/v1/scans/{id} with this id (9bc5e9cf-3bb5-4b37-ac03-42009775d159, 222b82fe-db58-4099-bf5b-34309cb892f1) to see progress and results.",
"credits_used": 14,
"credits_left": 4882,
"scans": [
{
"id": "9bc5e9cf-3bb5-4b37-ac03-42009775d159",
"business": {
"id": "4130d4b5-f65a-4b38-8fa2-db5d69fa21eb",
"name": "Slice & Crust Midtown"
},
"keyword": "best pizza near me",
"platform": "google_ai_overview",
"platform_label": "Google AI Overviews",
"status": "running",
"progress": "0/9",
"sample": "3 × 3 grid",
"created_at": "2026-10-22T22:49:18+00:00",
"completed_at": null,
"credits_used": 9,
"result": null,
"failure_reason": null,
"url": "https://citednearby.com/dashboard/rank-scans/9bc5e9cf-3bb5-4b37-ac03-42009775d159/ai"
},
{
"id": "222b82fe-db58-4099-bf5b-34309cb892f1",
"business": {
"id": "4130d4b5-f65a-4b38-8fa2-db5d69fa21eb",
"name": "Slice & Crust Midtown"
},
"keyword": "best pizza near me",
"platform": "chatgpt",
"platform_label": "ChatGPT",
"status": "running",
"progress": "0/5",
"sample": "5 answers in 1 town",
"created_at": "2026-10-22T22:49:18+00:00",
"completed_at": null,
"credits_used": 5,
"result": null,
"failure_reason": null,
"url": "https://citednearby.com/dashboard/rank-scans/222b82fe-db58-4099-bf5b-34309cb892f1/ai"
}
],
"dashboard_url": "https://citednearby.com/dashboard/rank-scans/9bc5e9cf-3bb5-4b37-ac03-42009775d159/ai"
}
}
Lists are cut to 3 items here; real answers have them all.
POST
/api/v1/scans/web-search
Uses credits
Check where the business' website ranks in Google's regular results.
Returns: Check where the business' website ranks in Google's regular (organic) results for a keyword. Needs the business to have a website. Uses credits: one per page of 10 results read (5 for the default top 50, held up front; pages not needed are refunded when the check finishes). Without a location it uses the business' own town. Returns the scan id, the credits used and left and a dashboard link; results are usually ready in 1-3 minutes: call get_scan with the id. Only run it when the user asked for a check.
Same data as the MCP tool run_web_search_check.
Parameter
In
Type
Description
business_id
body
string
The business id (UUID) from list_businesses.
keyword
body
string
What customers search, e.g. "emergency plumber".
location
body
string
Where the search is made from, as Google names it: City,State,Country (e.g. "Austin,Texas,United States"). Default: the business' own town. Optional.
national
body
boolean
Set true to search without a location (national results) instead of the business' town. Optional.
max_results
body
integer (min 10, max 100)
How many Google results to look through, 10 to 100 (default 50). Optional.
{
"data": {
"message": "Scan started. Results are usually ready in 1-3 minutes: call GET /api/v1/scans/{id} with this id (4babe3d3-37b1-4e32-95b9-3ff9dd4c0dd9) to see progress and results. The credits shown are held for the most this check can read; the ones for pages it does not need are refunded when it finishes.",
"credits_used": 5,
"credits_left": 4877,
"scans": [
{
"id": "4babe3d3-37b1-4e32-95b9-3ff9dd4c0dd9",
"business": {
"id": "4130d4b5-f65a-4b38-8fa2-db5d69fa21eb",
"name": "Slice & Crust Midtown"
},
"keyword": "pizza delivery",
"platform": "google_search",
"platform_label": "Google Search",
"status": "running",
"progress": "0/5",
"sample": "Top 50 · New York, New York, United States",
"created_at": "2026-10-22T22:49:18+00:00",
"completed_at": null,
"credits_used": 5,
"result": null,
"failure_reason": null,
"url": "https://citednearby.com/dashboard/rank-scans/4babe3d3-37b1-4e32-95b9-3ff9dd4c0dd9/web"
}
],
"dashboard_url": "https://citednearby.com/dashboard/rank-scans/4babe3d3-37b1-4e32-95b9-3ff9dd4c0dd9/web"
}
}
POST
/api/v1/scans/{scan_id}/rescan
Uses credits
Run an earlier scan again with the same settings.
Returns: Run an earlier scan again with the same settings (Google Maps, AI or Web Search), so the new scan joins the same keyword's history. Uses credits, the same as the first run (the scan's credits_used shows it). Returns the new scan id, the credits used and left and a dashboard link; results are usually ready in 1-3 minutes: call get_scan with the id. Only run it when the user asked for it.
Same data as the MCP tool rescan.
Parameter
In
Type
Description
scan_id
path
string
The scan id (UUID) from GET /api/v1/scans.
Example request
curl
curl -X POST "https://citednearby.com/api/v1/scans/SCAN_ID/rescan" \
-H "Authorization: Bearer YOUR_API_KEY"
JSON
{
"data": {
"message": "Scan started. Results are usually ready in 1-3 minutes: call GET /api/v1/scans/{id} with this id (db4f95ee-9737-4df5-8705-21393cb1f6da) to see progress and results.",
"credits_used": 25,
"credits_left": 4852,
"scans": [
{
"id": "db4f95ee-9737-4df5-8705-21393cb1f6da",
"business": {
"id": "4130d4b5-f65a-4b38-8fa2-db5d69fa21eb",
"name": "Slice & Crust Midtown"
},
"keyword": "pizza delivery",
"platform": "google_maps",
"platform_label": "Google Maps",
"status": "running",
"progress": "0/25",
"sample": "5 × 5 grid",
"created_at": "2026-10-22T22:49:18+00:00",
"completed_at": null,
"credits_used": 25,
"result": null,
"failure_reason": null,
"url": "https://citednearby.com/dashboard/rank-scans/db4f95ee-9737-4df5-8705-21393cb1f6da"
}
],
"dashboard_url": "https://citednearby.com/dashboard/rank-scans/db4f95ee-9737-4df5-8705-21393cb1f6da"
}
}
POST
/api/v1/campaigns/{campaign_id}/run
Uses credits
Run a campaign now, outside its schedule.
Returns: Run a campaign right now, outside its schedule: every keyword is scanned on Google Maps, and on the campaign's Web Search and AI engines too. Uses credits: the whole run is charged up front, as in the dashboard (list_campaigns shows credits_per_run); if the balance does not cover it, nothing starts. The schedule does not change. Returns the scan ids, the credits used and left and a dashboard link; results are usually ready in 1-3 minutes: call get_scan with each id. Only run it when the user asked for it.
Same data as the MCP tool run_campaign.
Parameter
In
Type
Description
campaign_id
path
string
The campaign id (UUID) from GET /api/v1/campaigns.
Example request
curl
curl -X POST "https://citednearby.com/api/v1/campaigns/CAMPAIGN_ID/run" \
-H "Authorization: Bearer YOUR_API_KEY"