Cookbook: Track rankings across countries

Goal: track how a set of keywords ranks for your domain in, say, the US, UK, and Germany — refreshed automatically every week — and see which keywords moved.

You’ll need

• An organization with the SERP Position Tracker feature and available token balance.
• The keywords you want to track and the domain you’re tracking for.
• To automate it: an API key with the Search permission, or an MCP client.

The approach

One campaign tracks one country’s SERP. To cover three countries you create one campaign per country with the same keywords, each on a weekly schedule. Then you read each campaign’s latest run to compare positions.

Steps

In the app

Create the first campaign

In app.isearchfrom.com, open Position Tracker → New campaign. Name it clearly, e.g. Brand keywords — US. Set the domain, add your keywords, and choose country US, your language, device, and engine.

Add a schedule

Turn on a schedule and pick weekly at a time that suits you. See Schedules & alerts for cron and timezone details.

Duplicate for each country

Create two more campaigns — … — UK (country GB) and … — DE (country DE) — with the same keywords but the matching country and language.

Read the results

Each run produces per-keyword positions. Open a campaign to see current ranks, and compare across your three campaigns. See Reading tracker results.

With the API

Create one campaign per country. The body is the same except country and language:

BASE_URL="https://api.isearchfrom.com/v1"

for pair in "US:en" "GB:en" "DE:de"; do
  country="${pair%%:*}"; lang="${pair##*:}"
  curl -s -X POST "$BASE_URL/tools/serp/position-tracker/campaigns" \
    -H "X-API-Key: $ISEARCHFROM_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{
      \"name\": \"Brand keywords — $country\",
      \"domain\": \"example.com\",
      \"keywords\": [\"best crm software\", \"crm for startups\"],
      \"country\": \"$country\",
      \"language\": \"$lang\",
      \"device\": \"desktop\",
      \"engine\": \"google\",
      \"schedule\": { \"cron\": \"0 8 * * 1\", \"timezone\": \"UTC\" }
    }"
done

Confirm the exact field names

Campaign fields and their constraints are defined by the API’s schema. Check the interactive API reference for the exact request body — it’s generated from the live API, so it’s always current.

Trigger an immediate first run (optional — schedules run on their own):

curl -X POST "$BASE_URL/tools/serp/position-tracker/campaigns/$CAMPAIGN_ID/runs" \
  -H "X-API-Key: $ISEARCHFROM_API_KEY"

Read the latest run and its per-keyword positions:

curl "$BASE_URL/tools/serp/position-tracker/campaigns/$CAMPAIGN_ID/runs?limit=1" \
  -H "X-API-Key: $ISEARCHFROM_API_KEY"

With an AI agent (MCP)

Once you’ve connected a client, ask in natural language:

Using iSearchFrom, create three position-tracking campaigns for example.com with the
keywords "best crm software" and "crm for startups" — one for the US (en), one for the
UK (en), and one for Germany (de) — each on a weekly Monday 08:00 schedule. Then trigger
a first run for each and tell me the starting positions.

The agent calls create_position_campaign three times, trigger_position_run for each, and reads the results with get_position_run. See the tool catalog.

Verify

• Each campaign shows a completed run with a position for every keyword.
• Re-running next week, the campaign shows movement (up/down) per keyword.
• Token balance dropped by roughly keywords × countries per run — that’s expected; each keyword check costs tokens. See Token usage.

Variations

• Get notified on big moves — add alert rules and a webhook, then relay them to Slack. See Send alerts to Slack.
• Cities, not just countries — set a city for hyper-local SERPs (great for local SEO). See Local SEO.
• Track competitors too — add competitor domains to the campaign to see where they rank for the same terms.

Related

SERP Position TrackerThe tracker in depth.

Schedules & alertsCron, timezones, and alert rules.

Reading tracker resultsInterpreting positions and movement.