API docs v1
PATCH /v1/brands/{brand_id}/seo/keywords/{keyword_id}

Update a tracked keyword

scope write:seo cost 1 RU idempotent optional

Set the page that should rank for the keyword (target_url), or clear it with null; star or unstar it (starred).

Path parameters

Query parameters

  • 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

Header parameters

  • Idempotency-Key string optional

    Optional. A retry with the same key and body within 24 hours replays the first response.

Request body

application/json required
Type: KeywordUpdate
  • starred boolean (nullable) nullable

    Star or unstar the keyword.

  • target_url string (nullable) nullable

    The page that should rank for the keyword; null clears it.

Responses

Updated a tracked keyword application/json
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.

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"
}
Request body did not match the expected schema 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": "body_validation_error",
    "message": "Request body did not match the expected schema"
  },
  "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"
}