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

List the brand's keywords

scope read:seo cost 1 RU

A page of the brand's keyword library: saved (starred) keywords and the rank tracked ones, each with its search volume, difficulty and intent, its last, previous and best position, the brand page that ranked, its opportunity score, the article that targets it and its evidence (Search Console over the last 28 settled days against the 28 before, the site's own ranking, the competitors that rank where it does not, the research seed that suggested it, the prompts mapped to it), plus totals over the rank tracked rows (top 3, top 10, improved, declined), how many keywords each lens holds and the plan's limits. Offset-paginated and filtered and sorted over every row: lens reads another set of the brand's keywords than the library, filter narrows to rank tracked, saved, recommended or starred keywords, status to the article's state, ai_overview to what Google's AI Overview does with the brand, cluster_id to the members of one keyword cluster.

Path parameters

Query parameters

  • limit integer optional

    Page size (1-100).

    default: 20

  • offset integer optional

    Keywords to skip.

    default: 0

  • sort string (enum) optional

    Column the rows are ordered by. Besides the table's columns: clicks, impressions and gsc_position (Search Console), ranked_position (the site's own ranking), gap_position (the best competitor's position) and prompts (prompts mapped to the keyword).

    one of created, keyword, source, page, volume, ai, questions, kd, intent, market, position, best, checked, opportunity, clicks, impressions, gsc_position, ranked_position, gap_position, prompts · default: created

  • order string (enum) optional

    asc or desc.

    one of asc, desc · default: desc

  • filter string (enum) optional

    Narrows the lens read: all, rank_tracked, saved (no rank checks: in the library, the starred ones), recommended (high score, no article yet), starred, or an article state: planned, published, failed.

    one of all, rank_tracked, saved, recommended, starred, planned, published, failed · default: all

  • status string optional

    Only keywords whose newest article is in this state; none for no article.

  • ai_overview string optional

    shows (Google answers with an AI Overview), cites (it cites the brand's site), names (its text names the brand), not_you (shown, without the brand), or any.

  • cluster_id string optional

    Only the keywords of this cluster.

  • lens string optional

    Which of the brand's keywords to read; omitted, the library (rank tracked or starred). tracked, starred, near_page_one (Search Console's position, else the site's own ranking, 11 to 20), zero_click (no click from 100 or more Search Console impressions), competitors (a competitor ranks for it and the site does not), ideas (a research run suggested it in the last 30 days) or all.

  • idea_seed string optional

    Only the ideas a research run of this seed found (POST .../seo/keyword-research), compared as stored: lowercase, spacing collapsed.

  • keyword string optional

    Only the rows of exactly this keyword, compared as stored.

  • 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 the brand's keywords application/json
Type: TrackedKeywordList
  • data array of TrackedKeyword required
  • has_more boolean required
  • limit integer required
  • limits KeywordLimits required
    Show fields
    Type: KeywordLimits
  • offset integer required
  • summary KeywordSummary required
    Show fields
    Type: KeywordSummary
    • checked integer required

      Keywords checked at least once.

    • declined integer required

      Keywords that moved down at the last check.

    • improved integer required

      Keywords that moved up at the last check.

    • ranking integer required

      Keywords the site ranks for in the top 100.

    • top_10 integer required
    • top_3 integer required
    • tracked integer required

      Keywords rank tracked.

    • avg_position number (nullable) nullable
    • last_checked_at string (nullable) nullable

      format: `date-time`

    • saved integer

      Keywords saved without rank checks.

      default: `0`

  • target KeywordTarget required

    The Google market the numbers are for.

    Show fields
    Type: KeywordTarget
    • language_code string required

      Language code of the brand's market.

    • location_code integer required

      Google location code of the brand's market.

    • chosen boolean

      True when this is the market saved with PUT /seo/keyword-market.

      default: `false`

    • language_fallback boolean

      True when keyword data is not available in the brand's language there, so the numbers are for this language_code instead (Catalan in Spain is measured in Spanish).

      default: `false`

    • location_fallback boolean

      True when keyword data is not available for the brand's country, so the numbers are for this location_code instead (Russia is measured in Kazakhstan).

      default: `false`

    • location_name string (nullable) nullable

      The country the numbers are for, when known.

  • total integer required

    Keywords matching the filters, across every page.

  • domain string (nullable) nullable

    The brand's site the positions are for.

  • lenses KeywordLensCounts

    How many keywords each lens holds, whatever the filters.

    Show fields
    Type: KeywordLensCounts
    • all integer

      Every keyword of the brand, in the library or evidence only.

      default: `0`

    • competitors integer

      A competitor ranks for it and the brand's site does not.

      default: `0`

    • ideas integer

      A research run suggested it in the last 30 days.

      default: `0`

    • near_page_one integer

      Search Console's position, else the site's own ranking, between 11 and 20.

      default: `0`

    • starred integer

      Starred (saved).

      default: `0`

    • tracked integer

      Rank tracked.

      default: `0`

    • zero_click integer

      No click from 100 or more Search Console impressions.

      default: `0`

  • object string

    default: `tracked_keyword_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"
}