API docs v1
GET /v1/brands/{brand_id}/seo/keywords/{keyword_id}/history

Get a keyword's rank history

scope read:seo cost 1 RU

One keyword with its rank checks, newest first, a page at a time, with who held the top of the results page each time.

Path parameters

Query parameters

  • limit integer optional

    Page size (default 20, max 100).

    default: 20

  • cursor string optional

    Continuation token from a previous response's next_cursor.

  • dry_run boolean optional

    Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns 200 with a dry_run object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns 422.

    default: false

Responses

Returned a keyword's rank history application/json
Type: KeywordHistory
  • data array of RankCheck required
  • has_more boolean required
  • keyword TrackedKeyword required

    A keyword of the brand, in the library or (through a lens) evidence only; its last position when tracked.

    Show fields
    Type: TrackedKeyword
    • id string required
    • keyword string required
    • source enum required

      Where the keyword first came from.

    • article KeywordArticle (nullable) nullable

      The newest article targeting it.

    • best_position integer (nullable) nullable

      Best position ever seen.

    • change integer (nullable) nullable

      Positions gained since the previous check; positive is better.

    • checking boolean

      A rank check is queued and has not landed yet.

      default: `false`

    • cluster KeywordClusterRef (nullable) nullable

      The topic cluster it sits in; null when it stands alone or clusters were never built.

    • created_at string (nullable) nullable

      format: `date-time`

    • gap_best_position integer (nullable) nullable

      The best position among gap_domains.

    • gap_domains array of string (nullable) nullable

      Competitor sites that rank for it where the brand's site does not.

    • gap_synced_at string (nullable) nullable

      When the competitors' rankings were read.

      format: `date-time`

    • gsc_clicks integer (nullable) nullable

      Search Console clicks over the last 28 settled days; null when the query is not among the ones kept (10 or more impressions, the 10,000 most seen).

    • gsc_impressions integer (nullable) nullable

      Search Console impressions over the same 28 days.

    • gsc_position number (nullable) nullable

      Search Console average position over the 28 days.

    • gsc_prev_position number (nullable) nullable

      Search Console average position over the 28 days before; null without impressions.

    • gsc_synced_at string (nullable) nullable

      When the Search Console numbers were read.

      format: `date-time`

    • gsc_url string (nullable) nullable

      The page Search Console shows most for the query.

    • idea_at string (nullable) nullable

      When a research run last suggested it; ideas older than 30 days are cleared.

      format: `date-time`

    • idea_seed string (nullable) nullable

      The research seed that last suggested it.

    • last_check_failed_at string (nullable) nullable

      Set when the provider could not answer the last check.

      format: `date-time`

    • last_checked_at string (nullable) nullable

      format: `date-time`

    • last_position integer (nullable) nullable

      Google position at the last check; null when outside the top 100, or never checked.

    • last_url string (nullable) nullable

      The brand's page Google ranked at the last check; null when Google hid the page behind its own redirect.

    • metrics KeywordMetrics (nullable) nullable
    • object string

      Always tracked_keyword.

      default: `tracked_keyword`

    • opportunity_score integer (nullable) nullable

      The keyword's 0 to 100 score (volume, difficulty against what the site already ranks for, position, intent, AI Overview), halved once an article targets the keyword; content opportunities rank the keyword by the same score. Null until scored.

    • opportunity_tier enum (nullable) nullable

      high from 65, medium from 40, else low.

    • previous_position integer (nullable) nullable

      Position at the check before.

    • prompt_count integer

      The brand's prompts mapped to this keyword.

      default: `0`

    • rank_tracked boolean

      Rank checks run for it and it counts against the plan's tracking cap. false with starred is a saved keyword, free and uncapped; false without it is evidence only, outside the library.

      default: `true`

    • ranked_etv number (nullable) nullable

      Estimated monthly traffic that ranking brings.

    • ranked_position integer (nullable) nullable

      The site's best position in its ranking keywords; null when it does not rank.

    • ranked_synced_at string (nullable) nullable

      When the ranking was read.

      format: `date-time`

    • ranked_url string (nullable) nullable

      The site's page that ranks at ranked_position.

    • serp KeywordSerp (nullable) nullable

      The Google page around the keyword, shared by every brand tracking it in this market; null until any rank check there has read it. checked_at says when.

    • starred boolean

      On the brand's shortlist; a saved keyword is starred. With rank_tracked, what puts a keyword in the library.

      default: `false`

    • target_url string (nullable) nullable

      The page that should rank for it.

  • next_cursor string (nullable) nullable

    Opaque continuation token. Pass back as ?cursor= to fetch the next page. null when has_more is false.

  • object string

    default: `list`

Request validation failed application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Missing or invalid credentials application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid credentials"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
You do not have permission to access this resource application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "forbidden",
    "message": "You do not have permission to access this resource"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Resource not found application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Resource conflict application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "conflict",
    "message": "Resource conflict"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Per-minute rate limit exceeded application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Per-minute rate limit exceeded"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
An unexpected error occurred application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Service temporarily unavailable, please retry application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "service_unavailable",
    "message": "Service temporarily unavailable, please retry"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}