Tracking configurations, tracked keywords, and run results — /seo/rank-tracking/configs, /keywords, and /runs.

Rank tracking has three parts: a configuration pairing a domain with a location, language, device set, and schedule; the keywords tracked against it; and the runs that record positions.

Almost everything needs both `projectId` and `configId`

Only GET /seo/rank-tracking/configs works with projectId alone. Every keyword and run call requires configId as well — omitting it returns 400, not a project-wide listing.

List configurations

GET/seo/rank-tracking/configs

Every tracking configuration in the project. This is the entry point — start here to discover configId values. Not rate limited.

Query parameters

projectIdstringqueryrequired

Owning project.

Response fields

configsobject[]

Tracking configurations.

Request

curl "https://api.misar.io/seo/rank-tracking/configs?projectId=5b1c7d2e-…" \
  -H "Authorization: Bearer $MISARSEO_API_KEY"

200 — OK

{
  "configs": [
    {
      "id": "cfg_2a9b4c10",
      "domain": "acme.com",
      "serpDepth": 100,
      "locationCode": 2840,
      "languageCode": "en",
      "devices": "both",
      "isActive": true
    }
  ]
}

Create a configuration

POST/seo/rank-tracking/configs

Request body

projectIdstringbodyrequired

Owning project. Must be a UUID.

domainstringbodyrequired

Domain to track.

serpDepthnumberbodyrequired

How deep to read the results page. An integer between 10 and 100 that is a multiple of 10.

locationCodenumberbodydefault: 2840

Positive integer location code.

languageCodestringbodydefault: en

At most 10 characters.

devicesstringbodydefault: both

desktop, mobile, or both.

scheduleIntervalstringbody

How often the tracker re-checks positions.

Response fields

configIdstring

The new configuration id. Pass it to every keyword and run call.

Request

curl -X POST https://api.misar.io/seo/rank-tracking/configs \
  -H "Authorization: Bearer $MISARSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "5b1c7d2e-…",
    "domain": "acme.com",
    "serpDepth": 100,
    "locationCode": 2840,
    "languageCode": "en",
    "devices": "both"
  }'

201 — Created

{ "configId": "cfg_2a9b4c10" }

400 — Duplicate

{
  "error": "This domain + country combination is already being tracked",
  "code": "VALIDATION_ERROR"
}

Rate limit: 30 requests per 60 s.

`serpDepth` is required and must be a multiple of 10

50 and 100 are valid; 55 is not, and omitting the field entirely fails validation. There is no default.

Duplicates return 400, not 409

A configuration for the same domain and locationCode already exists → 400 VALIDATION_ERROR. A per-project configuration cap also applies.

Update a configuration

PATCH/seo/rank-tracking/configs

Request body

projectIdstringbodyrequired

Owning project. Must be a UUID.

configIdstringbodyrequired

Configuration to update. Must be a UUID.

domainstringbody

New domain.

serpDepthnumberbody

10–100, multiple of 10.

locationCodenumberbody

Positive integer.

languageCodestringbody

At most 10 characters.

devicesstringbody

desktop, mobile, or both.

scheduleIntervalstringbody

Re-check cadence.

isActivebooleanbody

Pause or resume the tracker without deleting it.

Response fields

successboolean

true when the update was written.

Request

curl -X PATCH https://api.misar.io/seo/rank-tracking/configs \
  -H "Authorization: Bearer $MISARSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "projectId": "5b1c7d2e-…", "configId": "cfg_2a9b4c10", "isActive": false }'

200 — OK

{ "success": true }

Rate limit: 30 requests per 60 s.

Delete a configuration

DELETE/seo/rank-tracking/configs

Request body

projectIdstringbodyrequired

Owning project. Must be a UUID.

configIdstringbodyrequired

Configuration to delete. Must be a UUID.

Response fields

successboolean

true when the configuration was deleted.

Request

curl -X DELETE https://api.misar.io/seo/rank-tracking/configs \
  -H "Authorization: Bearer $MISARSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "projectId": "5b1c7d2e-…", "configId": "cfg_2a9b4c10" }'

200 — Deleted

{ "success": true }

Rate limit: 30 requests per 60 s. To stop tracking without losing history, PATCH isActive: false instead.

List tracked keywords

GET/seo/rank-tracking/keywords

Paginated keywords for one configuration. Not rate limited.

Query parameters

projectIdstringqueryrequired

Owning project.

configIdstringqueryrequired

Tracking configuration. Required — this endpoint does not list configurations.

pagenumberquerydefault: 1

1-based page number.

pageSizenumberquerydefault: 50

Snapped to the nearest of 50, 100, or 250.

Response fields

keywordsobject[]

Tracked keyword records.

totalCountnumber

Total keywords on this configuration.

pagenumber

Echo of the requested page.

pageSizenumber

Echo of the resolved page size.

Request

curl "https://api.misar.io/seo/rank-tracking/keywords?projectId=5b1c7d2e-…&configId=cfg_2a9b4c10&page=1&pageSize=100" \
  -H "Authorization: Bearer $MISARSEO_API_KEY"

400 — Missing configId

{ "error": "projectId and configId are required", "code": "VALIDATION_ERROR" }

Add keywords

POST/seo/rank-tracking/keywords

Request body

projectIdstringbodyrequired

Owning project.

configIdstringbodyrequired

Tracking configuration.

keywordsstring[]bodyrequired

Up to 100 entries per request, each at most 500 characters.

Response fields

addednumber

How many keywords were added.

addedIdsstring[]

Ids of the newly tracked keywords.

Request

curl -X POST https://api.misar.io/seo/rank-tracking/keywords \
  -H "Authorization: Bearer $MISARSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "5b1c7d2e-…",
    "configId": "cfg_2a9b4c10",
    "keywords": ["seo audit tool", "rank tracker"]
  }'

201 — Added

{ "added": 2, "addedIds": ["kw_01H…", "kw_01J…"] }

429 — Plan quota

{ "error": "Tracked keyword limit reached for your plan", "code": "PLAN_LIMIT_REACHED" }

Rate limit: 30 requests per 60 s. Your plan's tracked-keyword allowance is enforced here — exceeding it returns 429 PLAN_LIMIT_REACHED, which waiting will not clear.

Remove keywords

DELETE/seo/rank-tracking/keywords

Request body

projectIdstringbodyrequired

Owning project.

configIdstringbodyrequired

Tracking configuration.

keywordIdsstring[]bodyrequired

Up to 1000 keyword ids per request.

Response fields

removednumber

How many ids were submitted for removal.

Request

curl -X DELETE https://api.misar.io/seo/rank-tracking/keywords \
  -H "Authorization: Bearer $MISARSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "5b1c7d2e-…",
    "configId": "cfg_2a9b4c10",
    "keywordIds": ["kw_01H…", "kw_01J…"]
  }'

200 — Removed

{ "removed": 2 }

Rate limit: 30 requests per 60 s.

Latest run

GET/seo/rank-tracking/runs

Latest run only — this is not run history

The endpoint returns a single run: the most recent check for the configuration. There is no pagination and no way to page back through earlier runs via the API.

Query parameters

projectIdstringqueryrequired

Owning project.

configIdstringqueryrequired

Tracking configuration.

Response fields

runobject

The latest run record.

Request

curl "https://api.misar.io/seo/rank-tracking/runs?projectId=5b1c7d2e-…&configId=cfg_2a9b4c10" \
  -H "Authorization: Bearer $MISARSEO_API_KEY"

Rate limit: 60 requests per 60 s.

Status codes

Code	Meaning
`200`	Read, updated, or deleted
`201`	Configuration or keywords created
`400`	`VALIDATION_ERROR` — missing `projectId`/`configId`, bad `serpDepth`, oversized array, or a duplicate domain + location
`401`	`UNAUTHENTICATED`
`404`	`NOT_FOUND` — `Project not found` or `Rank tracking config not found`
`429`	`RATE_LIMITED` or `PLAN_LIMIT_REACHED`
`500`	`INTERNAL_ERROR`

Limits

Limit	Value
`serpDepth`	10–100, multiples of 10
Keywords per add request	100
Keyword length	500 characters
Keyword ids per remove request	1000
Page sizes	50, 100, 250

Rank Tracking

List configurations

Create a configuration

Update a configuration

Delete a configuration

List tracked keywords

Add keywords

Remove keywords

Latest run

Status codes

Limits

On this page