Tracker: AI and search visibility
Create and update tracking projects, trigger scans and read SPI, citations and results.
Tracker — Capabilities and declarative upsert
Section titled “Tracker — Capabilities and declarative upsert”Call GET /api/agent/v1/reporter/capabilities?client_id=UUID before a compound Tracker write. It returns the canonical platform catalog, the current account’s allowed and disallowed platforms, and whether the selected client already satisfies YouTube, TikTok, and Local Pack identity requirements. The capacity block reports report_limit, current_reports, and remaining_slots for the organization (unlimited: true when the plan has no limit). It is computed by the same function the create and upsert cap check blocks on, so a batch that fits in remaining_slots will not be refused for capacity.
PUT /api/agent/v1/reporter/projects/upsert is the preferred write contract. It requires client_id, one exact topic, either an exact platforms array or platform_policy, and an Idempotency-Key header. Send dry_run: true first to receive the planned create, update, or noop, effective platforms, dependency status, configuration hash, and a zero-usage receipt without writing. The real call creates one report or updates the exact client/topic report in place; it never starts a scan and preserves existing history. Optional brand_aliases and gbp_location_name values control mention and Local Pack identity matching; when omitted, the report inherits the linked client’s approved default aliases and connected GBP location name.
{ "client_id": "uuid", "topic": "Mexico residency assistance", "platform_policy": { "all_supported": true, "exclude": ["local_pack", "tiktok_search"] }, "frequency": "weekly", "auto_track_enabled": true, "dry_run": true}If more than one legacy report matches the normalized client/topic identity, the API returns 409 ambiguous_tracker_identity with candidate IDs; retry with project_id. Video platforms accept youtube_channel_url, youtube_channel_name, and tiktok_profile_url, with linked client identities used as safe defaults. Dependency and entitlement failures are returned before a write or scan consumes usage.
Reporter — Create Project
Section titled “Reporter — Create Project”POST /api/agent/v1/reporter/projects
Create a new rank tracking project with keyword(s), domain, and platform configuration.
Scope required: reporter:write
Request body
Section titled “Request body”{ "name": "My SEO Project", "keywords": ["best seo tools"], "target_domain": "example.com", "brand_name": "Example Co", "platforms": ["google_organic", "bing", "chatgpt", "perplexity", "gemini"], "location": "United States", "language": "en", "frequency": "daily", "auto_track_enabled": true}| Field | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Project name |
keywords |
array | Yes | Exactly one keyword string or {keyword, targetDomain} object |
client_id |
string (UUID) | No | Associate with a client |
target_domain |
string | No | Domain to track |
brand_name |
string | No | Brand name for mention tracking |
gbp_location_name |
string | No | Google Business Profile location name |
platforms |
string[] | No | Platforms to track (default: google_organic, bing, chatgpt, perplexity, gemini) |
location |
string | No | Geographic location |
location_lat |
number | No | Latitude for local grid tracking |
location_lng |
number | No | Longitude for local grid tracking |
grid_size |
string | No | Grid size: 3x3, 5x5, or 7x7 (default: 3x3) |
language |
string | No | Language code (default: en) |
frequency |
string | No | Scan frequency: daily, weekly, or monthly (default: daily) |
platform_frequencies |
object | No | Per-platform frequency overrides, e.g., {"chatgpt": "weekly"} |
auto_track_enabled |
boolean | No | Enable automatic scanning (default: true) |
youtube_channel_url |
string | null | No | Required when enabling YouTube Search or Google Video Pack unless the client has a connected YouTube identity |
youtube_channel_name |
string | null | No | Display name for the tracked YouTube channel |
tiktok_profile_url |
string | null | No | Required when enabling TikTok Search unless the client has a saved TikTok profile |
channel_queries |
object | No | Optional AI, traditional, local, and video channel-specific query overrides |
Idempotency: Include an Idempotency-Key header to safely retry requests. The key derives the project identifier, so a retry remains duplicate-safe across process restarts; conflicting reuse returns 409 idempotency_conflict.
Plan limits: Project creation is not capped by a per-plan tracking-keyword limit. A 403 plan_limit_exceeded error is only returned when the request would push the org over its included client allocation. Credit consumption (per scan) still applies normally.
Response (201)
Section titled “Response (201)”{ "id": "uuid", "keyword": "best seo tools", "domain": "example.com", "brand_name": "Example Co", "location": "United States", "language": "en", "platforms": ["google_organic", "bing", "chatgpt", "perplexity", "gemini"], "frequency": "daily", "auto_track_enabled": true, "created_at": "2025-01-15T10:00:00.000Z"}Reporter — Update Project
Section titled “Reporter — Update Project”PATCH /api/agent/v1/reporter/projects/:id
Update an existing rank tracking project. Only provided fields are updated.
Scope required: reporter:write
Request body
Section titled “Request body”All fields are optional. Only include fields you want to change.
{ "brand_name": "New Brand Name", "frequency": "weekly", "auto_track_enabled": false}| Field | Type | Description |
|---|---|---|
name |
string | Project name |
target_domain |
string | Domain to track |
brand_name |
string | null | Brand name |
gbp_location_name |
string | null | GBP location name |
platforms |
string[] | Platforms to track |
location |
string | null | Geographic location |
frequency |
string | Scan frequency: daily, weekly, monthly |
platform_frequencies |
object | Per-platform frequency overrides |
auto_track_enabled |
boolean | Enable/disable automatic scanning |
youtube_channel_url |
string | null | YouTube channel identity for YouTube Search and Google Video Pack |
youtube_channel_name |
string | null | YouTube display name |
tiktok_profile_url |
string | null | TikTok profile identity for TikTok Search |
channel_queries |
object | Channel-specific query overrides |
Response
Section titled “Response”Returns the full updated project object (same shape as create response, with updated_at).
Reporter — Delete Project
Section titled “Reporter — Delete Project”DELETE /api/agent/v1/reporter/projects/:id
Delete a rank tracking project and all associated data (runs, results, history).
Scope required: reporter:write
Response
Section titled “Response”{ "id": "uuid", "deleted": true}