Keyword research and saved keyword sets — /seo/keywords/research and /seo/keywords/saved.

Two surfaces: research fetches live metrics for a keyword list, and saved persists a curated set against a project.

Research keywords

POST/seo/keywords/research

Fetches metrics and expansions for up to 100 keywords.

Request body

projectIdstringbodyrequired

Owning project.

keywordsstring[]bodyrequired

Between 1 and 100 entries, each at most 500 characters.

locationCodenumberbodydefault: 2840

Numeric location code. 2840 is the United States.

languageCodestringbodydefault: en

Two-letter language code.

resultLimitnumberbodydefault: 150

Snapped to the nearest of 150, 300, or 500.

modestringbodydefault: auto

One of auto, related, suggestions, ideas. An unrecognised value silently falls back to auto.

clickstreambooleanbodydefault: true

Include clickstream-derived signals where available.

Response

The service result is returned unwrapped — the response body is the research payload, not { data: … }.

Request

curl -X POST https://api.misar.io/seo/keywords/research \
  -H "Authorization: Bearer $MISARSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "5b1c7d2e-…",
    "keywords": ["seo audit tool", "rank tracker"],
    "locationCode": 2840,
    "languageCode": "en",
    "mode": "auto",
    "resultLimit": 150
  }'

501 — No honest data source

{ "error": "No honest data source for this metric", "code": "SEO_DATA_UNAVAILABLE" }

Rate limit: 10 requests per 60 s.

Expect 501 in free data mode

When the deployment runs on free providers and a requested metric has no honest public source, the response is 501 SEO_DATA_UNAVAILABLE rather than an invented number. Handle it as "unavailable here", not as a server fault.

Status codes

Code	Meaning
`200`	Research result
`400`	`VALIDATION_ERROR` — missing `projectId`, empty or oversized `keywords`, or an over-long entry
`401`	`UNAUTHENTICATED`
`402`	Billing code — see Errors
`404`	`NOT_FOUND` — project not found
`429`	`RATE_LIMITED`
`501`	`SEO_DATA_UNAVAILABLE`

List saved keywords

GET/seo/keywords/saved

Paginated read of a project's saved keyword set. Not rate limited.

Query parameters

projectIdstringqueryrequired

Owning project.

pagenumberquerydefault: 1

1-based page number.

pageSizenumberquerydefault: 50

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

searchstringquery

Substring filter on the keyword text.

sortstringquerydefault: createdAt

One of createdAt, keyword, searchVolume, cpc, competition, keywordDifficulty, fetchedAt.

orderstringquerydefault: desc

asc or desc.

Request

curl "https://api.misar.io/seo/keywords/saved?projectId=5b1c7d2e-…&page=1&pageSize=50&sort=searchVolume&order=desc" \
  -H "Authorization: Bearer $MISARSEO_API_KEY"

Save keywords

POST/seo/keywords/saved

Request body

projectIdstringbodyrequired

Owning project.

keywordsstring[]bodyrequired

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

locationCodenumberbodydefault: 2840

Numeric location code.

languageCodestringbodydefault: en

Two-letter language code.

tagsstring[]body

Labels applied to every keyword in this batch.

Request

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

Rate limit: 30 requests per 60 s. Returns 201 on success.

There is no delete endpoint

/seo/keywords/saved supports GET and POST only. Saved keywords cannot be removed through the API — remove them from the MisarSEO dashboard. Rank-tracked keywords are a separate set and do have a delete endpoint; see Rank Tracking.

Limits

Limit	Value
Keywords per research request	100
Keywords per save request	1000
Keyword length	500 characters
Research rate limit	10 / 60 s
Save rate limit	30 / 60 s
Page sizes	50, 100, 250

Keywords

Research keywords

Status codes

List saved keywords

Save keywords

Limits

On this page