Skip to content

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.

POST /api/agent/v1/reporter/projects

Create a new rank tracking project with keyword(s), domain, and platform configuration.

Scope required: reporter:write

{
"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.

{
"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"
}

PATCH /api/agent/v1/reporter/projects/:id

Update an existing rank tracking project. Only provided fields are updated.

Scope required: reporter:write

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

Returns the full updated project object (same shape as create response, with updated_at).

DELETE /api/agent/v1/reporter/projects/:id

Delete a rank tracking project and all associated data (runs, results, history).

Scope required: reporter:write

{
"id": "uuid",
"deleted": true
}