---
title: "Tracker: AI and search visibility"
description: "Create and update tracking projects, trigger scans and read SPI, citations and results."
canonical_url: "https://developers.rankability.com/guides/tracker"
section: "Guides"
last_updated: 2026-11-14
---

# Tracker: AI and search visibility

Create and update tracking projects, trigger scans and read SPI, citations and results.

## 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.

```json
{
  "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

`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

```json
{
  "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)

```json
{
  "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

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

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

**Scope required**: `reporter:write`

### Request body

All fields are optional. Only include fields you want to change.

```json
{
  "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

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

## 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

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