API reference

Everything you see in the Serpfox app is available as JSON over HTTPS, so you can pull your rankings into your own reports and tools. The app itself is built on this API.

Getting a key

Sign in, open Settings, then API, and create a key. The key is shown once, so copy it when you create it. An account can have five keys, and you can revoke any of them at any time. A key has the same access as the account that created it, so keep it out of web pages and public repositories.

Making a request

Send requests to https://api.serpfox.com with your key in the Authorization header.

curl https://api.serpfox.com/urls \
  -H "Authorization: apitoken YOUR_KEY"

Errors

StatusBodyMeaning
401{"message": "API key was invalid"}The key is missing, mistyped or revoked.
400{"keyword": ["Missing data for required field."]}A field in the request is wrong. The body names the field.
403, 404, 429{"message": "…"}Not allowed, not found, or too many requests.

Paging

List endpoints return everything unless you ask for a page. Pass page as a URL-encoded JSON object with an offset and a limit. The total number of items comes back in the X-Total-Count header.

curl -G https://api.serpfox.com/pairs \
  --data-urlencode 'page={"offset": 0, "limit": 50}' \
  -H "Authorization: apitoken YOUR_KEY"

Sites

GET /urls

The sites you track, each with a summary of its keywords.

[
  {
    "url": "example.com",
    "idna_decoded_url": "example.com",
    "title": null,
    "metrics": {
      "pair_count": 4,
      "high": 19, "low": 8,
      "delta_last": 0, "delta_day": 1, "delta_week": 1, "delta_month": 5,
      "increasing_last": 0, "increasing_day": 0, "increasing_week": 1, "increasing_month": 0,
      "decreasing_last": 0, "decreasing_day": 1, "decreasing_week": 1, "decreasing_month": 3
    }
  }
]
FieldMeaning
pair_countKeywords tracked for the site.
low, highThe best and worst current positions among them.
delta_*Total positions moved since the last check, a day, a week and a month ago.
increasing_*, decreasing_*How many keywords moved in each direction over the same periods.

GET /urls/{url}/pairs

The keywords tracked for one site, in the format described under Keywords. URL-encode the site if it contains a path, for example /urls/example.com%2Fblog/pairs.

Keywords

A tracked keyword is called a pair: one keyword, for one site, on one search engine, device and location. The same phrase tracked on desktop and mobile is two pairs.

GET /pairs

Every pair on the account.

ParameterMeaning
pageSee Paging.
searchOnly keywords containing this text.
urlOnly pairs for this site.
starredtrue for starred pairs only.
sortrank, delta_last, delta_day, delta_week or delta_month. Put - in front to reverse it. The default is newest first.
[
  {
    "id": 12783695,
    "created_at": "2026-09-08T01:13:22.579802",
    "starred": false,
    "keyword": {
      "id": 668726,
      "keyword": "rank tracker",
      "search_engine": "www.google.com",
      "platform": "Desktop",
      "language_code": null,
      "location_display": "United States",
      "metrics": { "search_volume": 4400 }
    },
    "match": {
      "url": "example.com",
      "idna_decoded_url": "example.com",
      "exactly": false,
      "title": null
    },
    "rank": {
      "rank": 8,
      "url": "https://example.com/rank-tracker",
      "path": "/rank-tracker",
      "query_string": "",
      "delta_last": 0, "delta_day": 0, "delta_week": 0, "delta_month": 1,
      "created_at": "2026-11-21T23:00:52.337841"
    }
  }
]
FieldMeaning
rank.rankThe position in Google's results, counting from 1. null means the site was not in the first 30 results.
rank.urlThe page that ranked.
rank.delta_*Change in position since the last check, a day, a week and a month ago. A negative number is an improvement: -3 means the site moved up three places.
rank.created_atWhen that check ran.
ranknull until a new keyword has had its first check.
match.exactlytrue if only that exact page counts, false if any page on the site does.
keyword.metrics.search_volumeMonthly searches on Google, where known.

Rank history

GET /pairs/{id}/graph

Every check for one pair, newest first. This is the data behind the chart in the app.

[
  { "created_at": "2026-11-21T23:00:52.337841", "rank": 8 },
  { "created_at": "2026-11-20T22:57:58.716920", "rank": 8 },
  { "created_at": "2026-11-19T22:41:07.118302", "rank": null }
]

GET /pairs/{id}

One pair, with a timeline array holding the full rank object for each check, newest first.

Adding and removing keywords

POST /pairs

Add keywords. Send an array, one object per pair. The response is the pairs that were created, with status 201, or 204 with no body if they all existed already. New keywords count towards your plan's keyword limit.

curl -X POST https://api.serpfox.com/pairs \
  -H "Authorization: apitoken YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "keyword": {
        "keyword": "rank tracker",
        "search_engine": "www.google.com",
        "platform": "Desktop",
        "language_code": "en",
        "location": { "id": 1013617 }
      },
      "match": { "url": "example.com", "exactly": false }
    }
  ]'
FieldMeaning
keyword.keywordThe search phrase.
keyword.search_engineA value from GET /search_engines, for example www.google.co.uk.
keyword.platformDesktop or Mobile.
keyword.language_codeOptional. A code from GET /search_engines/{engine}/languages.
keyword.locationOptional. {"id": …} from GET /search_engines/{engine}/locations/{text}, for city-level results. Without it the search uses the engine's country.
match.urlThe site to look for, without https://.
match.exactlyOptional. true to count only that exact page.

GET /search_engines

The search engines you can track, with their countries.

GET /search_engines/{engine}/languages

Language codes for an engine, as [{"code": "en", "name": "English"}].

GET /search_engines/{engine}/locations/{text}

Locations whose name starts with the text, for example /search_engines/www.google.com/locations/brisbane.

[
  {
    "id": 1013617,
    "name": "Brisbane",
    "canonical_name": "Brisbane,California,United States",
    "display_name": "Brisbane, California, United States"
  }
]

PATCH /pairs/{id}

Star or unstar a pair: {"starred": true}.

DELETE /pairs

Stop tracking pairs. Send their ids in the body: {"pair_ids": [12783695, 12783696]}.

DELETE /urls/{url}

Stop tracking a site and every keyword under it.

Groups

GET /groups

Your groups, each with the same metrics summary as a site.

[
  { "id": 157944, "name": "Competitors", "writeable": true, "metrics": { "pair_count": 4, "high": 19, "low": 8 } }
]

GET /groups/{id}/pairs

The pairs in a group.

POST /groups

Create a group: {"name": "Brand terms"}.

POST /groups/{id}/pairs

Add existing pairs to a group by sending an array of pair ids, [12783695, 12783696], or create new pairs straight into the group by sending the same array of objects as POST /pairs.

DELETE /groups/{id}/pairs

Take pairs out of a group without deleting them: {"pair_ids": [12783695]}.

DELETE /groups/{id}

Delete a group, along with its notifications, scheduled reports and share links. Its keywords stay on the account.

Account and usage

GET /user

Your account. usage is the number of keywords you track and keyword_quota is your plan's limit.

{
  "id": 34290,
  "first_name": "Sam",
  "usage": 412,
  "keyword_quota": 500,
  "default_search_engine": "www.google.com"
}

Something missing, or a call not behaving as described here? Write to support@serpfox.com.