Start tracking search ranks for keywords (daily re-rank; idempotent).

POSThttps://api.appgoat.ai/v1/tracked-keywords

FreeMCP tool track_keywordsoperationId trackKeywords

Each (term × store × country) uses one keyword slot of your plan; a request that would exceed it tracks nothing and returns 402 plan_limit.

Request

curl -X POST "https://api.appgoat.ai/v1/tracked-keywords" \
  -H "x-api-key: $APPGOAT_API_KEY" \
  -H "content-type: application/json" \
  -d '{"terms":["photo editor","collage maker"],"store":"both","countries":["us","gb"]}'

const res = await fetch("https://api.appgoat.ai/v1/tracked-keywords", {
  method: 'POST',
  headers: {
    "x-api-key": process.env.APPGOAT_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({"terms":["photo editor","collage maker"],"store":"both","countries":["us","gb"]}),
});
const { data, meta } = await res.json();

import os, requests

res = requests.post(
    "https://api.appgoat.ai/v1/tracked-keywords",
    headers={"x-api-key": os.environ["APPGOAT_API_KEY"]},
    json={"terms":["photo editor","collage maker"],"store":"both","countries":["us","gb"]}
)
body = res.json()

Request body

JSON, required.

termstring

termsstring[]

store"apple" | "play" | "both"

countriesstring[]

depthinteger

How many results to keep per ranking (default 100 Apple / 50 Play).

cadenceMinutesinteger

Minutes between re-ranks (paid plans can go below 1440).

tagsstring[]

Response

201 with data: object[]. See the envelope for meta.

idinteger

storeStore

countrystring

termstring

createdboolean

false = you already tracked it.

Example

{
  "data": [
    {
      "id": 1,
      "store": "apple",
      "country": "us",
      "term": "photo editor",
      "created": false
    }
  ],
  "meta": {
    "credits_used": 0,
    "credits_remaining": 9981,
    "request_id": "req_123"
  }
}

Status codes

201

One row per tracked (store, country, term).

400invalid_param

A parameter is missing or invalid (error.param names it).

401invalid_api_key

Missing or invalid API key.

402insufficient_creditsplan_limit

insufficient_credits (the call costs more than you have left; nothing was done) or plan_limit (a feature of a higher plan).

429rate_limited

Too many requests per second for your plan.