---
title: "Ranked keywords report | SEO Skill"
description: "Review a bounded domain or page keyword footprint with ranking URLs, demand estimates, provider limits and optional matching Search Console query evidence."
canonical: "https://seoskill.dev/docs/reports/ranked-keywords"
language: "en"
---

# Ranked keywords report

Open the keyword rows behind a domain or page footprint. Filters run before paid acquisition, and each optional Search Console match says observed or not found in retained rows instead of inventing a zero.

## Install and run the report

Install the CLI once, then run `seo start` to connect your site and Google data. After setup you can run this report yourself or ask your agent to run it.

Install the SEO CLI globally.

```
npm i -g seo
```

Run setup after installation.

```
seo start
```

Run ranked keyword footprint through the report catalog.

```
seo reports run ranked-keywords --params '{"target":"example.com","site":"sc-domain:example.com","countryCode":"GB","languageCode":"en","maxRank":20,"minSearchVolume":10,"limit":50}' --json
```

## What you get from this report

Review bounded provider keyword, ranking-page, result-type, and estimate rows with an optional matching Search Console comparison.

Best for

You need the keyword rows behind a domain or page footprint.

Needs

Domain or page target and market filters

You get

A bounded ranked-keyword list with ranking URLs, ranks, result types, provider metrics, source state, and stable ordering.

Use next

Inspect live search results

## What you need before you run it

This report uses provider keyword, ranking URL, grouped and absolute rank, result type, estimated traffic, volume, difficulty, intent, and cost fields. optional Search Console query and page rows, aggregated deterministically and matched by normalized query. request filters, pagination, provider totals, invalid rows, cache state, warnings, and local request cost.

### Domain or page target and market filters

Provide a bounded set of estimated keyword, rank, result type, ranking URL, demand, difficulty, intent, and traffic rows.

### Optional matching Search Console property

Adds retained owner-verified query and page evidence for the same site without changing provider metrics.

## How the report finds the opportunity

The report uses existing search and page evidence to build a limited review list. An opportunity is a reason to inspect a page, not a promise of more traffic.

01

Applies rank, demand, wording, result-type, and row limits before acquisition, then validates and deduplicates returned rows deterministically.

02

Labels each first-party comparison as observed, not in retained rows, or not requested.

03

Keeps provider totals, pagination, invalid rows, cache state, warnings, and request cost beside the visible subset.

## Check the evidence behind each opportunity

Start with the query, page and date range behind each suggestion. Thin or partial evidence belongs in the review pile, not the implementation queue.

| Read first | Why it matters |
| --- | --- |
| Result | A bounded ranked-keyword list with ranking URLs, ranks, result types, provider metrics, source state, and stable ordering. |
| More detail | Optional Search Console query and page matches, including conflicts where provider demand is zero but retained first-party impressions exist. |
| Read it with | Treat provider rows as a shortlist. Check the ranking page, current results, and first-party evidence before deciding that a term is a content opportunity. |

## What the result cannot prove

Rank, volume, traffic, difficulty, and intent are provider estimates and may be older than the current result page. Pagination and filters change the visible subset. Anonymised Search Console queries can hide first-party matches.

Treat provider rows as a shortlist. Check the ranking page, current results, and first-party evidence before deciding that a term is a content opportunity. An unmatched row means only that the bounded retained Search Console data did not contain it. Use keyword opportunities for first-party prioritisation and programmatic clusters.

## Use a different report for these jobs

You need a current exact result snapshot rather than a provider database row. You want a missing Search Console row treated as proof that the site had no impressions.

[

### You need owner-verified opportunities for a connected site rather than independent market estimates.

Run keyword opportunities first. It prioritises actual Search Console evidence, then use provider rows as additional market context.

Keyword opportunity report

](https://seoskill.dev/docs/reports/keyword-opportunities)[

### A current result page would change your decision about intent or competition.

Run SERP results for the shortlisted terms with explicit location and device settings before planning content or tracking rank.

Live SERP results report

](https://seoskill.dev/docs/reports/serp-results)

## Use the report with an agent or in code

The command above is enough for most work. These options let an agent, script or application run the same report with explicit input and structured output.

### CLI

Use the report catalog when an agent, script or CI job needs predictable JSON instead of the normal terminal output. Check the current input first, then run the report with the validated parameters.

Check the current input before the agent or script runs the report.

```
seo reports describe ranked-keywords --json
```

Once the input is valid, run the report through the report catalog.

```
seo reports run ranked-keywords --params '{"target":"example.com","site":"sc-domain:example.com","countryCode":"GB","languageCode":"en","maxRank":20,"minSearchVolume":10,"limit":50}' --json
```

### MCP

An MCP agent follows the same two-step flow. It inspects the current schema, fills the required fields and only then runs the report.

Ask the MCP server for the current report input.

```
{
  "id": "ranked-keywords"
}
```

Run the report after the agent has checked and filled the input.

```
{
  "id": "ranked-keywords",
  "params": {
    "target": "example.com",
    "site": "sc-domain:example.com",
    "countryCode": "GB",
    "languageCode": "en",
    "maxRank": 20,
    "minSearchVolume": 10,
    "limit": 50
  }
}
```

### TypeScript

Install the package in a Node 22 project when your application needs to run the report directly. The result includes the same evidence, warnings and limits returned through the CLI and MCP server.

Add the SEO package to your project.

```
npm install seo
```

Run the report from your TypeScript application.

```
import { executeReport } from 'seo/mcp'

const result = await executeReport(
  'ranked-keywords',
  {
  "target": "example.com",
  "site": "sc-domain:example.com",
  "countryCode": "GB",
  "languageCode": "en",
  "maxRank": 20,
  "minSearchVolume": 10,
  "limit": 50
},
)

console.log(result)
```

## What to do next

Shortlist terms whose provider row, ranking page and first-party match state support another look. Check current results before changing a page, and do not treat absence from retained Search Console rows as zero.

1.  01Run SERP results for shortlisted terms whose current intent or rank would change the decision.
2.  02Run ranking pages to inspect repeated page families.
3.  03Use keyword opportunities for first-party prioritisation and programmatic clusters.

## Related reports

[

Inspect one bounded search snapshot with exact retained organic ranks, market context, result features, provider coverage, cache status, and request cost.

Live SERP results report

](https://seoskill.dev/docs/reports/serp-results)[

Find a domain's bounded ranking-page footprint and repeated URL patterns, with optional matching Search Console page evidence.

Organic ranking pages report

](https://seoskill.dev/docs/reports/ranking-pages)[

Build one bounded queue from existing Search Console opportunities, then optionally add market estimates without changing the first-party priority scores.

Keyword opportunity report

](https://seoskill.dev/docs/reports/keyword-opportunities)

## Sources used by this report

These primary sources define the provider data or search controls used by the result.

-   [DataForSEO ranked keywords API reference](https://docs.dataforseo.com/v3/dataforseo_labs-google-ranked_keywords-live/)
-   [Search Console Search Analytics API guidance](https://developers.google.com/webmaster-tools/v1/how-tos/search_analytics)