RankSharkDocs
Campaigns

Create a campaign

RankShark TrackScopetrack:write

POST
/v1/track/campaigns

Validated against the plan (points per scan, keywords per campaign, campaigns, engines). A grid campaign (mode "grid", the default) needs business and grid: find the business with POST /v1/track/find. A website campaign (mode "website") needs domain, location and country, on engine search, bing_search or ai. runNow: true also starts the first scan and needs track:run. Fields not listed in CampaignInput are ignored.

Scope: track:write.

Authorization

headerAuthorizationBearer <rstk_… API key or OAuth access token>

A Track API key (rstk_…, Settings → API & MCP) or an OAuth access token issued for this API

Request Body

application/json
  1. body

A campaign's settings. Create: keywords and (grid) business and grid, or (website) domain, location and country. Update: only the fields sent change.

name?string

Default: the business name (website campaigns: the domain)

Lengthlength <= 120
mode?string

grid (default): a business on a grid. website: domain (required) scanned at one location (required) in country; engine search, bing_search or ai; grid, center and zoom are not used; one point per keyword

Value in"grid""website"
location?
business?

A result of POST /v1/track/find as it is (grid campaigns); {name} (website campaigns, AI visibility); other fields are ignored

keywords?array<>

Keywords (80 characters each), or prompts for engine "ai" (300); the plan sets how many (limits.keywordsPerTracker)

Itemsitems <= 100
engine?string

One engine (when engines is not given). "search" / "bing_search" alone on a grid campaign: its local pack and web results on the grid

Value in"maps""local_pack""search""bing_maps""bing_local_pack""bing_search""ai"
engines?array<>

Several engines, each paid at its own point cost: local_pack / bing_local_pack rank the listing in the search page's local pack, search / bing_search the website in the web results (at location, or on the grid with webGrid). "ai" asks aiEngines

webGrid?boolean

search / bing_search on the grid (default false: at location, the business's city unless given)

aiGrid?

Rank engines and "ai" together: the AI answers' grid (same centre, radius and shape)

aiEngines?array<>

engine "ai": the AI engines to ask (GET /v1/track/engines says which the plan has)

aliases?array<>

Other names the AI answers may use (AI campaigns; up to 10)

Itemsitems <= 10
grid?
center?

Grid centre (default: the business position)

zoom?|

10-18, null = automatic

Range10 <= value <= 18
language?string

Language code (default en)

Lengthlength <= 12
country?string

ISO 3166 alpha-2, lower case (default us)

Lengthlength <= 2
ipLocation?|

Where the searches come from (default: suggested from the grid centre)

domain?|

The business's site (organic rank, AI citations); required for a website campaign

Lengthlength <= 500
page?|

AI campaigns: a page whose citations count on their own

Lengthlength <= 1000
schedule?
paused?boolean

Scheduled runs paused

clientId?|

The business the campaign belongs to (tc_…); null: not assigned

Match^tc_[A-Za-z0-9]{10,40}$
folder?|

A folder inside the business

Lengthlength <= 60
runNow?boolean

Create only: start the first scan (needs track:run)

Response Body

OK

application/json
  1. response
id*string

gt_…

name*string
mode*string

website: a domain at one location (one point per keyword; on a search engine the metrics score its organic rank)

Value in"grid""website"
location?|

A website campaign's location, or where a grid campaign's web results are searched (off the grid); null otherwise

business?|null
keywords*array<string>
engine*string

The first of engines

Value in"maps""local_pack""search""bing_maps""bing_local_pack""bing_search""ai"
engines*array<>

The engines it scans, in this order: maps, local_pack, search, bing_maps, bing_local_pack, bing_search, ai

webGrid?boolean

The web results (search / bing_search) on the grid; false: at location

grid?|null
center?|null
points?integer

Grid points one scan of one keyword has

aiEngines?array<>|

Campaigns with "ai"; null otherwise

aliases?array<string>|null
aiGrid?|

Rank engines and AI together: the AI answers' grid; null otherwise

aiPoints?|

Points of aiGrid (when it has one)

zoom?|

null = automatic

language?string
country?string
ipLocation?|null
domain?string|null
page?string|null
schedule?|null
nextRunAt?|

The next scheduled run

Formatdate-time
lastRunAt?|
Formatdate-time
paused?boolean
clientId?|

The business the campaign belongs to (tc_…); null: not assigned

folder?|

A folder inside the business

lastScheduleError?|

Why the last scheduled run did not start

quickScan?boolean

A quick scan (runs once); absent on campaigns

latest*array<>

The latest result per keyword and engine

active?array<>

List only: its unfinished scans

createdAt?|
Formatdate-time
updatedAt?|
Formatdate-time
Example Request
curl -X POST 'https://panel.rankshark.io/v1/track/campaigns' \  -H 'Content-Type: application/json' \  -d '{  "name": "Harbor Dental · Austin",  "business": {    "name": "Harbor Dental",    "address": "1200 S Congress Ave, Austin, TX 78704",    "category": "Dentist",    "lat": 30.2509,    "lng": -97.7493,    "fid": "0x8644b50a3e3c0b1d:0x6a8d1e2f3c4b5a69",    "pid": "ChIJd8BlQ2BZwokRAFUEcm_qrcA",    "cid": "7677826127960431209",    "website": "https://harbordental.example",    "phone": "+1 512-555-0142",    "mapsUrl": "https://www.google.com/maps/place/?q=place_id:ChIJd8BlQ2BZwokRAFUEcm_qrcA",    "rating": 4.8,    "reviews": 312  },  "keywords": [    "dentist near me",    "emergency dentist",    "teeth whitening austin"  ],  "engines": [    "maps"  ],  "grid": {    "size": 7,    "radiusM": 4828,    "shape": "square",    "unit": "mi"  },  "schedule": {    "freq": "weekly",    "hour": 9,    "dow": 1,    "tz": "America/Chicago"  },  "clientId": "tc_5Rw8Jn3Ys2QeLk",  "folder": "Austin"}'
Example Response
{  "id": "gt_8fK2mQ9xLp3s",  "name": "Harbor Dental · Austin",  "mode": "grid",  "location": null,  "business": {    "name": "Harbor Dental",    "address": "1200 S Congress Ave, Austin, TX 78704",    "category": "Dentist",    "lat": 30.2509,    "lng": -97.7493,    "fid": "0x8644b50a3e3c0b1d:0x6a8d1e2f3c4b5a69",    "pid": "ChIJd8BlQ2BZwokRAFUEcm_qrcA",    "cid": "7677826127960431209",    "website": "https://harbordental.example",    "phone": "+1 512-555-0142",    "mapsUrl": "https://www.google.com/maps/place/?q=place_id:ChIJd8BlQ2BZwokRAFUEcm_qrcA",    "rating": 4.8,    "reviews": 312  },  "keywords": [    "dentist near me",    "emergency dentist",    "teeth whitening austin"  ],  "engine": "maps",  "engines": [    "maps"  ],  "webGrid": false,  "grid": {    "size": 7,    "radiusM": 4828,    "shape": "square",    "unit": "mi"  },  "center": {    "lat": 30.2509,    "lng": -97.7493  },  "points": 49,  "aiEngines": null,  "aliases": null,  "aiGrid": null,  "zoom": null,  "language": "en",  "country": "us",  "ipLocation": {    "country": "us",    "region": "texas",    "city": "austin"  },  "domain": "harbordental.example",  "page": null,  "schedule": {    "freq": "weekly",    "hour": 9,    "dow": 1,    "dom": 1,    "tz": "America/Chicago"  },  "nextRunAt": "2026-11-09T15:00:00.000Z",  "lastRunAt": null,  "paused": false,  "clientId": "tc_5Rw8Jn3Ys2QeLk",  "folder": "Austin",  "lastScheduleError": null,  "latest": [],  "createdAt": "2026-09-14T18:22:10.000Z",  "updatedAt": "2026-11-02T15:06:12.000Z"}

Update a business POST

name is required; the other fields are replaced by what is sent (displayName and logoDataUrl only when sent). Scope: `track:write`.

Delete a campaign and all its scans DELETE

Its unfinished scans are cancelled first, like POST /v1/track/scans/{id}/cancel: one cancelled before any point gives its points back. This cannot be undone. Scope: `track:delete`.