> ## Documentation Index
> Fetch the complete documentation index at: https://snowseo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Keyword Changes

> See which tracked keywords moved up or down in search rankings.

Find out which of your tracked keywords improved or dropped in position. Great for daily or weekly monitoring to catch ranking shifts early.

### Key fields

| Field        | What It Tells You                            |
| ------------ | -------------------------------------------- |
| `rising`     | Keywords that moved closer to position #1    |
| `falling`    | Keywords that dropped in position            |
| `new`        | Keywords that just started ranking           |
| `lost`       | Keywords that fell off the rankings entirely |
| `categories` | Groupings of keyword changes by topic        |

<Tip>
  A positive `positionChange` means the keyword moved closer to position #1 (good). A negative `positionChange` means it dropped.
</Tip>


## OpenAPI

````yaml GET /v3/rank-tracking/keyword-changes
openapi: 3.0.0
info:
  title: SnowSEO API
  description: API documentation for SnowSEO
  version: 1.0.0
servers:
  - url: https://api.snowseo.com
    description: Production server
security: []
tags:
  - name: Keywords
    description: Keyword research and suggestion end-points
  - name: Onboarding
    description: Brand onboarding and strategy end-points
  - name: Brands
    description: Brand management end-points
  - name: Organizations
    description: Organization and member end-points
  - name: Integrations
    description: Google Search Console and other integrations
  - name: Utilities
    description: Common utility end-points like screenshots and uploads
externalDocs:
  url: https://snowseo.com/docs
  description: Find more info here
paths:
  /v3/rank-tracking/keyword-changes:
    get:
      tags:
        - Rank Tracking
      summary: Keyword performance changes
      description: >-
        Returns rising, falling, new, and lost keywords by comparing average
        position across two time periods.
      parameters:
        - schema:
            type: string
          in: query
          name: teamId
          required: false
          description: Team ID
        - schema:
            type: string
          in: query
          name: startDate
          required: false
          description: Start date (YYYY-MM-DD, UTC)
        - schema:
            type: string
          in: query
          name: endDate
          required: false
          description: End date (YYYY-MM-DD, UTC)
        - schema:
            type: integer
          in: query
          name: limit
          required: false
          description: Max results per category
        - schema:
            type: string
          in: query
          name: device
          required: false
          description: Device filter
        - schema:
            type: string
          in: query
          name: type
          required: false
          description: Search type filter
        - schema:
            type: string
          in: query
          name: country
          required: false
          description: Country filter
        - schema:
            type: string
            enum:
              - all
              - ranked
              - tracked
          in: query
          name: scope
          required: false
          description: >-
            Keyword universe: all (GSC + tracked), ranked (GSC only), tracked
            (tracked only). Defaults to all.
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  rising:
                    type: array
                    items:
                      type: object
                      properties:
                        keyword:
                          type: string
                        clicks:
                          type: number
                          nullable: true
                        impressions:
                          type: number
                          nullable: true
                        position:
                          type: number
                        clicksChange:
                          type: number
                        impressionsChange:
                          type: number
                        positionChange:
                          type: number
                        previousPosition:
                          type: number
                        previousClicks:
                          type: number
                        previousImpressions:
                          type: number
                        category:
                          type: string
                          enum:
                            - rising
                            - falling
                            - new
                            - lost
                        pages:
                          type: number
                        rankedPages:
                          type: array
                          items:
                            type: object
                            additionalProperties: true
                            properties:
                              page:
                                type: string
                              clicks:
                                type: number
                              impressions:
                                type: number
                              ctr:
                                type: number
                              position:
                                type: number
                              clicksChange:
                                type: number
                              impressionsChange:
                                type: number
                              ctrChange:
                                type: number
                              positionChange:
                                type: number
                  falling:
                    type: array
                    items:
                      type: object
                      properties:
                        keyword:
                          type: string
                        clicks:
                          type: number
                          nullable: true
                        impressions:
                          type: number
                          nullable: true
                        position:
                          type: number
                        clicksChange:
                          type: number
                        impressionsChange:
                          type: number
                        positionChange:
                          type: number
                        previousPosition:
                          type: number
                        previousClicks:
                          type: number
                        previousImpressions:
                          type: number
                        category:
                          type: string
                          enum:
                            - rising
                            - falling
                            - new
                            - lost
                        pages:
                          type: number
                        rankedPages:
                          type: array
                          items:
                            type: object
                            additionalProperties: true
                            properties:
                              page:
                                type: string
                              clicks:
                                type: number
                              impressions:
                                type: number
                              ctr:
                                type: number
                              position:
                                type: number
                              clicksChange:
                                type: number
                              impressionsChange:
                                type: number
                              ctrChange:
                                type: number
                              positionChange:
                                type: number
                  new:
                    type: array
                    items:
                      type: object
                      properties:
                        keyword:
                          type: string
                        clicks:
                          type: number
                          nullable: true
                        impressions:
                          type: number
                          nullable: true
                        position:
                          type: number
                        clicksChange:
                          type: number
                        impressionsChange:
                          type: number
                        positionChange:
                          type: number
                        previousPosition:
                          type: number
                        previousClicks:
                          type: number
                        previousImpressions:
                          type: number
                        category:
                          type: string
                          enum:
                            - rising
                            - falling
                            - new
                            - lost
                        pages:
                          type: number
                        rankedPages:
                          type: array
                          items:
                            type: object
                            additionalProperties: true
                            properties:
                              page:
                                type: string
                              clicks:
                                type: number
                              impressions:
                                type: number
                              ctr:
                                type: number
                              position:
                                type: number
                              clicksChange:
                                type: number
                              impressionsChange:
                                type: number
                              ctrChange:
                                type: number
                              positionChange:
                                type: number
                  lost:
                    type: array
                    items:
                      type: object
                      properties:
                        keyword:
                          type: string
                        clicks:
                          type: number
                          nullable: true
                        impressions:
                          type: number
                          nullable: true
                        position:
                          type: number
                        clicksChange:
                          type: number
                        impressionsChange:
                          type: number
                        positionChange:
                          type: number
                        previousPosition:
                          type: number
                        previousClicks:
                          type: number
                        previousImpressions:
                          type: number
                        category:
                          type: string
                          enum:
                            - rising
                            - falling
                            - new
                            - lost
                        pages:
                          type: number
                        rankedPages:
                          type: array
                          items:
                            type: object
                            additionalProperties: true
                            properties:
                              page:
                                type: string
                              clicks:
                                type: number
                              impressions:
                                type: number
                              ctr:
                                type: number
                              position:
                                type: number
                              clicksChange:
                                type: number
                              impressionsChange:
                                type: number
                              ctrChange:
                                type: number
                              positionChange:
                                type: number
                  categories:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                        label:
                          type: string
                        count:
                          type: number
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: string

````