Skip to main content
GET
Keyword performance changes
Find out which keywords improved or dropped in position between a period and the one before it. Great for daily or weekly monitoring to catch ranking shifts early. endDate is required; the request returns 400 without it. Send endDate without startDate for All Time: the four lists come back empty, because All Time has no previous period to compare against. The default scope=all includes Search Console queries alongside your tracked keywords.

Limit and paging

  • Default mode: when page is not sent and pageSize is not all, limit (default 50) caps the Search Console queries fetched for each period and trims each of the four lists (rising, falling, new, lost) to that many. categories counts reflect these trimmed lists.
  • pageSize=all without page: Search Console queries are fetched uncapped and the four lists are returned in full.
  • With page: Search Console queries are fetched uncapped and the response is { items, page, pageSize, total, totalPages, categories }, with no rising or falling lists. items mixes all four categories unless you pass category. categories counts come from the full lists (respecting search).

Key fields

Keyword fields

Each keyword in a list (or in items) has: For tracked keywords with no Search Console data, clicks and impressions are null, and the change and previous click and impression fields are 0.
A positive positionChange means the keyword moved closer to position #1 (good). A negative positionChange means it dropped. For lost keywords it is the negative of the previous position.

Authorizations

Authorization
string
header
required

Your SnowSEO API key (sk_...).

Query Parameters

page
integer
Required range: x >= 1
sortBy
enum<string>
Available options:
kw,
pos,
imp,
clicks,
pages,
posDelta
sortDir
enum<string>
Available options:
asc,
desc
category
enum<string>
Available options:
rising,
falling,
new,
lost
teamId
string

Team ID

startDate
string

Start date (YYYY-MM-DD, UTC). Omit with endDate set for All Time: the lists come back empty, as All Time has no previous period.

endDate
string

End date (YYYY-MM-DD, UTC)

limit
integer

Max keywords returned per category (default 50). Category counts always cover every keyword.

pageSize
string

Rows per category, or all.

includePages
enum<string>

'true' adds each keyword's ranking pages (pages, rankedPages). Slower; defaults to 'false'.

Available options:
true,
false
device
string

Device filter

type
string

Search type filter

country
string

Country filter

scope
enum<string>

Keyword universe: all (GSC + tracked), ranked (GSC only), tracked (tracked only). Defaults to all.

Available options:
all,
ranked,
tracked

Response

Default Response

page
integer
pageSize
integer
total
integer
totalPages
integer
items
object[]
rising
object[]
falling
object[]
new
object[]
lost
object[]
categories
object[]