---
name: ranktrack
description: Track Apple App Store + Google Play keyword rankings via the Ranktrack API. Manage tracked keywords, add/remove countries, fetch latest ranks and history.
homepage: https://useranktrack.com/
api_base: https://useranktrack.com/api/v1
docs: https://useranktrack.com/dashboard/api
auth: bearer
plan_required: pro_or_power
---

# Ranktrack — Agent Skill

You're an AI agent connected to a Ranktrack user's account via API. Use this
surface to read what they track and to add or remove tracked keywords and
countries on their behalf. Never fabricate rank numbers — if the API
returns null or no row, say so.

## Authentication

Every request must include:

```
Authorization: Bearer rt_live_<key>
```

Keys are created at `https://useranktrack.com/dashboard/api`. Pro = 60 req/min/key. Power =
300 req/min/key. A 401 means the key is invalid or revoked; a 429 means
you've hit the per-minute ceiling; back off for ~60 seconds.

## Base URL

```
https://useranktrack.com/api/v1
```

## Endpoints

### List apps the user tracks
`GET /apps`
Response:
```json
{ "apps": [
  { "id": "uuid", "platform": "iphone", "name": "Notion",
    "identifier": "1232780281", "isCompetitor": false, ... }
] }
```

### Get one app
`GET /apps/{appId}` — adds `keywordCount` to the row above.

### List keywords on an app
`GET /apps/{appId}/keywords`
Response: `{ "keywords": [{ "id": "uuid", "term": "vpn", "countries": ["us","gb"] }] }`

### Add a keyword (or extend an existing one with new countries)
`POST /apps/{appId}/keywords`
Body: `{ "term": "vpn", "countries": ["us", "gb"] }`
Idempotent: if the term already exists on that app, the response just adds
missing countries. Each cell is queued for rank checking immediately.
Counts against the plan's tracked-keyword budget (one keyword × country =
one). Pro caps at 300; if the add would exceed it the call returns `402`.
Re-adding a country you already track is free — only net-new cells count.

### Remove a keyword (cascades countries + history)
`DELETE /keywords/{keywordId}`

### Add country to an existing keyword
`POST /keywords/{keywordId}/countries`
Body: `{ "country": "de" }` or `{ "countries": ["de", "fr"] }`

### Drop a country
`DELETE /keywords/{keywordId}/countries/{country}`

### Latest stored rank per country (no live refresh)
`GET /keywords/{keywordId}/ranks`
Optional: `?country=us` to scope.
Response: `{ "keyword": {...}, "ranks": [{ "country": "us", "rank": 4,
"returnedCount": 200, "checkedAt": "ISO" }] }`

If `rank` is `null`, the app is outside the visible top-200 for that
search.

### Rank history for a country
`GET /keywords/{keywordId}/history?country=us&days=30`
`days`: 1–365. Returns every `rank_check` row in chronological order.

## Reading vs. writing

- **Reads** (`GET`) return what the cron has stored. They do NOT trigger a
  live refresh — there is no way for the API to force a fresh check on a
  cell. The user controls refresh cadence via their plan.
- **Writes** (`POST` / `DELETE`) take effect immediately. A new cell is
  queued so the cron picks it up within minutes.

## Errors

All errors return `{ "error": "human-readable string" }` with one of:

- `400` — malformed body / bad query
- `401` — invalid or missing key
- `402` — tracked-keyword budget exceeded (the `error` string says how many are in use and the cap); tell the user to remove some keywords/countries or upgrade
- `404` — resource not found OR not owned by the caller
- `429` — rate limited
- `500` — internal

## Recommended workflow for an agent

1. `GET /apps` to confirm which app the user is asking about.
2. `GET /apps/{id}/keywords` to see what's already tracked.
3. Before adding a new keyword, check the list — `POST` is idempotent but
   the user benefits from you flagging "already tracked in those
   countries".
4. After `POST /apps/{id}/keywords`, wait 1–2 minutes before calling
   `GET /keywords/{id}/ranks` — fresh cells haven't been checked yet.

## What this skill cannot do

- Trigger live rank refresh (cron-driven, plan-paced)
- Create or delete apps (users do this in the dashboard)
- Manage notification rules
- Generate API keys

Anything outside the endpoints above requires the user to act in the
dashboard at `https://useranktrack.com/dashboard`.