Search Console API

TL;DR — The Search ConsoleA free Google service that reports how a site performs in Google Search and surfaces problems with how Google crawls, indexes, and serves it. It's first-party data straight from Google — but you don't need it to appear in results. API lets you grab your Google Search ConsoleA free Google service that reports how a site performs in Google Search and surfaces problems with how Google crawls, indexes, and serves it. It's first-party data straight from Google — but you don't need it to appear in results. data with code instead of clicking through the interface. It’s how you get more than the UI hands you — the export in the interface tops out around 1,000 rows, while the API gives you up to 25,000 per request. You log in with Google (OAuth, not a simple API key), and you only get data for sites you’ve verified.

What the Search Console API is

Search ConsoleGoogle's free tool for monitoring crawling, indexing, and search performance. shows you how your site does in Google — what queries you rank for, how many clicks and impressions you get, whether your pages are indexedStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed.. The API gives you programmatic access to much of that same data and those same controls, so you can feed it into a spreadsheet, a dashboard, or a script that runs on a schedule. It’s not full UI parity, though — a few things (like live-testing a URL) only exist in the interface, and having API access or automation doesn’t by itself guarantee indexingStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed., rankings, traffic diagnosis, or AI-search visibility.

There are four pieces:

1. Search Analytics API — your Performance reportThe Google Search Console report that shows how your site actually performed in Google Search, built from real impressions and clicks. It reports four metrics — clicks, impressions, average CTR, and average position — and keeps the most recent 16 months of data. numbers (clicks, impressions, CTR, average position), broken down by query, page, country, device, and date.
2. URL InspectionA Google Search Console feature that reports how Google sees one specific URL on a property you own. By default it shows the last-indexed snapshot; a separate \"Test live URL\" mode fetches the current version. API — the index status of a single URL. It reports the version currently in Google’s index; the interface’s URL Inspection toolA Google Search Console feature that reports how Google sees one specific URL on a property you own. By default it shows the last-indexed snapshot; a separate \"Test live URL\" mode fetches the current version. can also run a live test, which the API can’t do.
3. SitemapsA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing. API — list, submit, or delete your sitemapsA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing..
4. Sites API — list, add, or remove the properties on your account.

Why use it instead of the interface

The big one: rows. If you export the Performance reportThe Google Search Console report that shows how your site actually performed in Google Search, built from real impressions and clicks. It reports four metrics — clicks, impressions, average CTR, and average position — and keeps the most recent 16 months of data. from the Search Console interface, you get roughly 1,000 rows. The API returns up to 25,000 rows per request, and you can page through for more. If you’ve got a site with thousands of queries or pages, the interface simply doesn’t show you most of your data.

The other reason is automation. Once it’s an API call, you can run it every morning, dump it into a dashboard, or alert yourself when clicks drop.

The catch

You can only pull data for properties you’ve verified in Search Console. Point the API at a site you don’t own and you get nothing back — that’s the most common beginner stumble.

And the API doesn’t give you everything. It returns the top rows, not the full list, and it never shows you the queries Google anonymizes for privacy. For a big site that wants the complete picture, the better tool is the bulk data export to BigQuery — more on that in the Advanced version.

TL;DR — The Search ConsoleA free Google service that reports how a site performs in Google Search and surfaces problems with how Google crawls, indexes, and serves it. It's first-party data straight from Google — but you don't need it to appear in results. API is four REST APIs under webmaster-tools/v1 — Search Analytics, URL InspectionA Google Search Console feature that reports how Google sees one specific URL on a property you own. By default it shows the last-indexed snapshot; a separate \"Test live URL\" mode fetches the current version., SitemapsA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing., Sites — all OAuth 2.0, all scoped to verified properties only. Search Analytics returns 1–25,000 rows per request (default 1,000) but “does not guarantee to return all data rows but rather top ones,” so for completeness at scale you graduate to the BigQuery bulk data exportGSC BigQuery export (bulk data export) is a Google Search Console feature that schedules a daily, unsampled export of a property's Performance data into a Google Cloud BigQuery project — bypassing the UI's ~1,000-row export cap and its rolling ~16-month retention window. It doesn't backfill and still excludes anonymized queries at the query level.. URL Inspection is hard-capped at 2,000 QPD / 600 QPM per site — that arithmetic is what gates large-scale indexStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed. monitoring.

The four APIs at a glance

Google’s own framing of what the API does: it lets you “view, add, or remove properties and sitemapsA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing., run advanced queries for Google Search results data for the properties that you manage in Search ConsoleGoogle's free tool for monitoring crawling, indexing, and search performance., and test individual pages.” That maps cleanly onto the four resources, all under webmaster-tools/v1:

• Search Analytics API — the Performance reportThe Google Search Console report that shows how your site actually performed in Google Search, built from real impressions and clicks. It reports four metrics — clicks, impressions, average CTR, and average position — and keeps the most recent 16 months of data., programmatically: clicks, impressions, CTR, position by dimension (query, page, country, device, search appearance, date, hour).
• URL Inspection API — the index status of a single URL, the programmatic sibling of the URL Inspection toolA Google Search Console feature that reports how Google sees one specific URL on a property you own. By default it shows the last-indexed snapshot; a separate \"Test live URL\" mode fetches the current version..
• Sitemaps API — list, get, submit, and delete sitemaps.
• Sites API — list, add, and remove verified properties.

It exposes much of what you already use in the interface — the Performance report and the URL Inspection tool — as endpoints you can script against. It isn’t a 1:1 mirror, though: the API doesn’t guarantee full UI parity (URL Inspection’s live test, for instance, is UI-only — see below), and neither API access nor automation on its own guarantees indexingStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed., rankings, traffic diagnosis, or AI-search visibility.

Auth: OAuth 2.0, two scopes, verified properties only

There’s no API key. Every call is OAuth 2.0 — Google is explicit that “all requests to the Google Search ConsoleA free Google service that reports how a site performs in Google Search and surfaces problems with how Google crawls, indexes, and serves it. It's first-party data straight from Google — but you don't need it to appear in results. API must be authorized by an authenticated user.” You register an app in Google Cloud, request a scope, and get a short-lived access tokenA token is the smallest unit of text (or image/audio/video) an LLM processes — roughly 4 characters, or about ¾ of an English word. A context window is the maximum number of tokens (input plus output) a model can hold at once, like its short-term memory.. Two scopes exist:

• https://www.googleapis.com/auth/webmasters — read/write.
• https://www.googleapis.com/auth/webmasters.readonly — read-only.

For server-to-server automation (a nightly reporting job, an index monitor) you grant a service account access to the property and skip the interactive consent flow.

Two property-identifier formats matter here too: a URL-prefix property is passed as a full property URL (Google’s own example is http://www.example.com/), and a Domain property uses the sc-domain:example.com form — you have to pass whichever form matches how the property is verified in Search Console. Either way, the service account (or user) needs to be granted access to that exact property; it’s not a bypass for ownership or a blanket grant across every property on the account.

And the gate that trips everyone up: “You must have appropriate access (owner, full, read) to any Google Search Console account that you wish to access using the API.” Call the API for a property you’re not verified on and it returns nothing — not an error you’ll necessarily notice, just empty data.

Search Analytics API — the Performance report, at scale

Start with the ceiling, not the convenience: Google’s own caveat is that “The API is bounded by internal limitations of Search Console and does not guarantee to return all data rows but rather top ones.” PaginationPagination splits a large set of content — product listings, blog archives, search results — across multiple sequentially numbered URLs. For SEO, each paginated page should be crawlable, indexable, and self-canonical; Google no longer uses rel=prev/next, but Bing still does. extends how far you can page into that top-rows list — it doesn’t remove the ceiling. When you need every row, that’s the cue to reach for BigQuery bulk export (below), not a bigger rowLimit.

Within that ceiling, this is still the one most people come for. The reason it beats the interface is the rowLimit parameter: “[Optional; Valid range is 1–25,000; Default is 1,000].” The interface export caps near 1,000 rows; the API gives you up to 25,000 per request, and you paginate past that with startRow. On a site with a long tail of queries, that’s the difference between seeing the top of your data and seeing more of it — still not all of it.

Two more things shape what comes back. First, dataState controls freshness: final (the default) returns only finalized data, all includes fresh, recently collected data, and hourly_all gives hourly breakdowns that are explicitly partial — the response metadata flags a first_incomplete_date or first_incomplete_hour, and Google notes values after that point can still change. Second, Search Analytics quotas aren’t a single number: the usage limits page splits them into load limits (a resource-based allowance measured in 10-minute and 1-day chunks — wider date ranges, more dimensions, and heavier filtering all draw it down faster) and the QPS/QPM/QPD request-rate limits covered below. You can hit the load ceiling before you hit the request-rate ceiling.

URL Inspection API — and the quota that actually constrains you

The URL Inspection API “view[s] the indexed, or indexable, status of the provided URL. Presently only the status of the version in the Google index is available; you cannot test the indexability of a live URL.” That last clause is a real scope limit, not a technicality: the interface’s URL Inspection tool can run a live test against the page as it exists right now; the API can only report on the version Google already has indexed. Use the API to build index-coverage monitoring across many URLs — not as a substitute for the UI’s live test.

Here’s where the math matters. Per site, you get 2,000 queries per day and 600 per minute. (Per project the ceiling is far higher — 10,000,000/day and 15,000/minute — but the per-site cap is what bites.) If you want to monitor the index status of a 50,000-URL site, you can’t inspect them all in a day; you batch and schedule across days, or you prioritize. Few posts do this arithmetic, and it’s the single biggest planning constraint on large-scale index monitoring.

By contrast, Search Analytics is generous — 1,200 QPM per site and per user — and the other resources (Sitemaps, Sites) sit at 20 QPS / 200 QPM per user. URL Inspection is the tight one.

Sitemaps and Sites APIs

The Sitemaps API is the management layer for your sitemaps: it “submits a sitemap for a site,” “deletes a sitemap from this site,” “retrieves information about a specific sitemap,” and “lists the sitemaps-entries submitted for this site, or included in the sitemap indexA sitemap index is a sitemap of sitemaps — a single file that lists your other sitemap files instead of listing URLs directly. It's how large sites stay under the 50,000-URL / 50MB-per-sitemap limit while submitting just one file. file.” The sitemap resource it returns includes fields like path, lastSubmitted, isPending, isSitemapsIndex, lastDownloaded, warnings, errors, and a contents array — handy for auditing sitemap health at scale.

The Sites API lists, adds, and removes verified properties — useful if you manage many properties and want to provision or audit them programmatically.

When to use BigQuery bulk export instead

For large sites, the API’s 25,000-rows-per-request, top-rows-only model becomes a ceiling. Google’s answer isn’t a fifth API resource that returns the same shape of data — it’s a separate, scheduled export pipeline: the bulk data export to BigQuery. Think of the choice as pull vs. scheduled push, not “API A vs. API B.” Google’s own framing: “Schedule a daily export of your Search Console performance data to BigQuery, where you can run complex queries over your data or export it to an external storage service. Using the bulk data export feature, you’ll see all the performance data available to Search Console for your property, with the exception of anonymized queries.”

That’s the decision rule:

• Interface export — ~1,000 rows, quick one-off look.
• Search Analytics API — up to 25,000 rows/request, paginate, scriptable; great for moderate on-demand pulls and dashboards.
• BigQuery bulk export — all available performance data, daily, no row cap; the right tool once you’ve got tens of thousands of pages or queries.

The one thing none of them give you is anonymized queries — the terms Google hides for privacy. That’s a real gap, not a bug you can work around. I know the scale of it firsthand: as Ahrefs’ Brand Ambassador I helped surface a study where we pulled all the data available from the API across a very large sample of sites and found Google hides the keyword term on a large share of clicks. We later built that into Ahrefs Rank Tracker — full history of your GSC data, the percent of clicks going to anonymized queries, and a custom CTR curve built from your own numbers. When someone tells you the API returns “all your data,” that anonymized slice is the honest asterisk.

Common use cases

• Automated reporting — scheduled pulls into Sheets or a warehouse.
• BI dashboards — Looker Studio or BigQuery on top of the Performance data.
• Large-scale index/coverage monitoring — URL Inspection, batched within the 2,000/day quota.
• CTR curve building — model expected CTR by position from your own data.
• Anomaly alerting — flag click/impression drops automatically.

This is also how third-party tools work: when Ahrefs or a Looker Studio connector “integrates Search Console,” they’re calling these same APIs (and increasingly, the BigQuery export) on your behalf.

AI summary

A condensed take on the Advanced version:

• The Search ConsoleA free Google service that reports how a site performs in Google Search and surfaces problems with how Google crawls, indexes, and serves it. It's first-party data straight from Google — but you don't need it to appear in results. API = four REST APIs under webmaster-tools/v1: Search Analytics (Performance data), URL InspectionA Google Search Console feature that reports how Google sees one specific URL on a property you own. By default it shows the last-indexed snapshot; a separate \"Test live URL\" mode fetches the current version. (indexStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed. status), SitemapsA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing., and Sites. It’s not full UI parity — a few things, like URL Inspection’s live test, only exist in the interface, and API access alone doesn’t guarantee indexingStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed., rankings, or traffic diagnosis.
• Auth is OAuth 2.0, no API key. Two scopes (webmasters, webmasters.readonly); service accounts for server-to-server, but they still need explicit access to the exact property. siteUrl takes either a URL-prefix property or a sc-domain:example.com Domain property — match how it’s verified. The API only returns data for properties you’ve verified — the #1 beginner gotcha.
• Search Analytics returns top rows first, not a complete dump — “does not guarantee to return all data rows but rather top ones,” regardless of paginationPagination splits a large set of content — product listings, blog archives, search results — across multiple sequentially numbered URLs. For SEO, each paginated page should be crawlable, indexable, and self-canonical; Google no longer uses rel=prev/next, but Bing still does.. Within that ceiling: 1–25,000 rows per request (default 1,000), vs ~1,000 in the interface export, and quotas split into load limits and QPS/QPM/QPD request-rate limits.
• URL Inspection: 2,000 queries/day, 600/minute per site, and it reports only the indexed version — it can’t run a live test. That quota is the real constraint on large-scale index monitoring — batch and schedule around it.
• SitemapsA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing. API lists/gets/submits/deletes sitemaps; Sites API lists/adds/removes properties.
• For large sites, use the BigQuery bulk data exportGSC BigQuery export (bulk data export) is a Google Search Console feature that schedules a daily, unsampled export of a property's Performance data into a Google Cloud BigQuery project — bypassing the UI's ~1,000-row export cap and its rolling ~16-month retention window. It doesn't backfill and still excludes anonymized queries at the query level. — a separate scheduled pipeline (not a fifth API resource) giving all available performance data daily, no row cap, except anonymized queries.
• Anonymized queries are a genuine gap no API or export fills — Patrick’s Ahrefs work quantified how large that hidden slice is.

Official documentation

Primary-source documentation from Google.

Search ConsoleA free Google service that reports how a site performs in Google Search and surfaces problems with how Google crawls, indexes, and serves it. It's first-party data straight from Google — but you don't need it to appear in results. API reference

• Search Console API — Overview / about — what the API does and the verified-property requirement.
• Search Analytics: query reference — the rowLimit (1–25,000) and dimension parameters.
• URL Inspection API reference — what indexStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed.-status data the inspect method returns.
• Sitemaps API reference — list, get, submit, delete.
• Sites API reference — list, add, remove verified properties.
• Usage limits — the full per-site, per-user, and per-project quota table.
• Authorizing requests (OAuth 2.0) — scopes and the auth flow.

Bulk data exportGSC BigQuery export (bulk data export) is a Google Search Console feature that schedules a daily, unsampled export of a property's Performance data into a Google Cloud BigQuery project — bypassing the UI's ~1,000-row export cap and its rolling ~16-month retention window. It doesn't backfill and still excludes anonymized queries at the query level.

• About bulk data export (Search Console Help) — schedule a daily BigQuery export of all performance data except anonymized queries.
• Bulk data export announcement (Search Central blog) — the launch post positioning bulk export for large sites.

Quotes from the source

On-the-record statements from Google’s documentation. Each link is a deep link that jumps to the quoted passage on the source page.

Google — what the API does and who can use it

• “view, add, or remove properties and sitemapsA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing., run advanced queries for Google Search results data for the properties that you manage in Search ConsoleA free Google service that reports how a site performs in Google Search and surfaces problems with how Google crawls, indexes, and serves it. It's first-party data straight from Google — but you don't need it to appear in results., and test individual pages.” — Google Search ConsoleA free Google service that reports how a site performs in Google Search and surfaces problems with how Google crawls, indexes, and serves it. It's first-party data straight from Google — but you don't need it to appear in results. API docs (Overview). Jump to quote
• “You must have appropriate access (owner, full, read) to any Google Search ConsoleGoogle's free tool for monitoring crawling, indexing, and search performance. account that you wish to access using the API.” — Google Search Console APIA set of REST APIs that let you programmatically read and manage Google Search Console data for properties you've verified — Performance data, URL index status, sitemaps, and properties — authorized with OAuth 2.0. docs (Overview). Jump to quote
• “All requests to the Google Search Console API must be authorized by an authenticated user.” — Authorizing requests guide. Jump to quote

Google — Search Analytics API

• “[Optional; Valid range is 1–25,000; Default is 1,000]” — the rowLimit parameter. — Search Analytics: query reference. Jump to quote
• “The URL of the property as defined in Search Console.” — the siteUrl parameter, whose examples give both the URL-prefix form (http://www.example.com/) and the Domain-property form (sc-domain:example.com). — Search Analytics: query reference. Jump to quote
• “The API is bounded by internal limitations of Search Console and does not guarantee to return all data rows but rather top ones.” — Search Analytics: query reference. Jump to quote

Google — URL InspectionA Google Search Console feature that reports how Google sees one specific URL on a property you own. By default it shows the last-indexed snapshot; a separate \"Test live URL\" mode fetches the current version. API

• “View the indexedStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed., or indexable, status of the provided URL. Presently only the status of the version in the Google index is available; you cannot test the indexability of a live URL.” — URL Inspection API reference. Jump to quote

Google — SitemapsA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing. API

• “Submits a sitemap for a site.” / “Deletes a sitemap from this site.” / “Lists the sitemaps-entries submitted for this site, or included in the sitemap index fileA sitemap index is a sitemap of sitemaps — a single file that lists your other sitemap files instead of listing URLs directly. It's how large sites stay under the 50,000-URL / 50MB-per-sitemap limit while submitting just one file..” — Sitemaps API reference. Jump to quote

Google — bulk data exportGSC BigQuery export (bulk data export) is a Google Search Console feature that schedules a daily, unsampled export of a property's Performance data into a Google Cloud BigQuery project — bypassing the UI's ~1,000-row export cap and its rolling ~16-month retention window. It doesn't backfill and still excludes anonymized queries at the query level.

• “Schedule a daily export of your Search Console performanceThe Google Search Console report that shows how your site actually performed in Google Search, built from real impressions and clicks. It reports four metrics — clicks, impressions, average CTR, and average position — and keeps the most recent 16 months of data. data to BigQuery… you’ll see all the performance data available to Search Console for your property, with the exception of anonymized queries.” — Search Console Help: About bulk data export. Jump to quote

OAuth setup & first-call checklist

Getting from zero to a working Search ConsoleA free Google service that reports how a site performs in Google Search and surfaces problems with how Google crawls, indexes, and serves it. It's first-party data straight from Google — but you don't need it to appear in results. API call:

• Confirm you have verified access (owner, full, or read) to the property in Search ConsoleGoogle's free tool for monitoring crawling, indexing, and search performance. — the API returns nothing for unverified properties.
• Create a project in the Google Cloud Console.
• Enable the Search Console APIA set of REST APIs that let you programmatically read and manage Google Search Console data for properties you've verified — Performance data, URL index status, sitemaps, and properties — authorized with OAuth 2.0. for that project.
• Create credentials: an OAuth 2.0 client (for interactive/user apps) or a service account (for server-to-server automation).
• If using a service account, grant it access to the property in Search Console settings.
• Request the right scope: webmasters.readonly for reporting, webmasters if you’ll submit sitemapsA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing. or manage properties.
• Obtain an access tokenA token is the smallest unit of text (or image/audio/video) an LLM processes — roughly 4 characters, or about ¾ of an English word. A context window is the maximum number of tokens (input plus output) a model can hold at once, like its short-term memory. via the OAuth flow (or service-account key).
• Confirm the siteUrl format matches how the property is verified: a full URL for a URL-prefix property, or sc-domain:example.com for a Domain property.
• Make a test call to searchAnalytics.query with a small date range and rowLimit: 10 to confirm data comes back.
• Plan around quotas: Search Analytics request rates are generous but also draw down a separate load quota; URL InspectionA Google Search Console feature that reports how Google sees one specific URL on a property you own. By default it shows the last-indexed snapshot; a separate \"Test live URL\" mode fetches the current version. is capped at 2,000/day, 600/min per site — batch accordingly. Don’t expect URL Inspection to run a live test — that’s UI-only.
• For tens of thousands of rows, set up the BigQuery bulk export instead of paginating.

The mental models

1. Four APIs, one auth. Search Analytics (read your Performance data), URL InspectionA Google Search Console feature that reports how Google sees one specific URL on a property you own. By default it shows the last-indexed snapshot; a separate \"Test live URL\" mode fetches the current version. (read a URL’s indexStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed. status), SitemapsA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing. (manage sitemapsA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing.), Sites (manage properties). All four go through the same OAuth 2.0 door and respect the same verified-property rule.

2. The data-scale ladder. Pick the tool by volume:

• Quick look → interface export (~1,000 rows).
• Scriptable, moderate → Search Analytics API (up to 25,000/request, paginate).
• Large site, complete → BigQuery bulk export (all data, daily, no row cap). Move up the ladder when the rung below stops fitting your data.

3. Top rows, not all rows. Internalize that the API returns “top ones,” not everything, and that anonymized queries are excluded from both the API and the export. If completeness matters, BigQuery is closer — but the anonymized slice is gone regardless.

4. Quota arithmetic before you build. Before designing an index monitor, do the math: URL Inspection is 2,000/day per site. A 50k-URL site can’t be inspected daily — so batch, prioritize, or schedule across days. Design around the cap, don’t discover it in production.

Search Console API — cheat sheet

The four APIs and their key limits

Auth

• OAuth 2.0 only — no API key.
• Scopes: webmasters (read/write), webmasters.readonly (read).
• Service accounts for server-to-server (grant them property access).
• Only verified properties return data.

Fast facts

• API returns top rows only — not guaranteed complete — regardless of paginationPagination splits a large set of content — product listings, blog archives, search results — across multiple sequentially numbered URLs. For SEO, each paginated page should be crawlable, indexable, and self-canonical; Google no longer uses rel=prev/next, but Bing still does..
• Interface export caps near 1,000 rows; API gives up to 25,000/request, paginate with startRow.
• Search Analytics quotas split into load limits (resource-based, 10-min / 1-day chunks) and the QPS/QPM/QPD request-rate limits above.
• siteUrl takes a URL-prefix property (http://www.example.com/) or a Domain property (sc-domain:example.com) — match how it’s verified.
• URL Inspection reports the indexed version only — it can’t run a live test; that’s UI-only.
• Anonymized queries are excluded from the API and the BigQuery export.
• For tens of thousands of rows → BigQuery bulk data exportGSC BigQuery export (bulk data export) is a Google Search Console feature that schedules a daily, unsampled export of a property's Performance data into a Google Cloud BigQuery project — bypassing the UI's ~1,000-row export cap and its rolling ~16-month retention window. It doesn't backfill and still excludes anonymized queries at the query level. — a separate scheduled pipeline, not a fifth API resource.
• Exposes much of the Performance reportThe Google Search Console report that shows how your site actually performed in Google Search, built from real impressions and clicks. It reports four metrics — clicks, impressions, average CTR, and average position — and keeps the most recent 16 months of data. (Search Analytics) and the URL Inspection tool, but isn’t full UI parity.

A minimal Search Analytics request

This is illustrative, not copy-paste-ready — you’ll need to wire up your own OAuth credentials and adjust the dates and property. It shows the shape of a searchAnalytics.query call: the request body with a date range, the dimensions you want, and the rowLimit.

The request body (the part that matters)

{
  "startDate": "2026-05-01",
  "endDate": "2026-05-31",
  "dimensions": ["query", "page"],
  "rowLimit": 25000,
  "startRow": 0
}

Sketch in Python (with the google-api-python-client library)

# Illustrative only — assumes you've already built an authorized `service`
# via OAuth 2.0 (scope: webmasters.readonly) or a service account.
from googleapiclient.discovery import build

service = build("searchconsole", "v1", credentials=creds)

request = {
    "startDate": "2026-05-01",
    "endDate": "2026-05-31",
    "dimensions": ["query", "page"],
    "rowLimit": 25000,   # max per request; default is 1000
    "startRow": 0,       # bump by 25000 to paginate
}

response = service.searchanalytics().query(
    siteUrl="https://example.com/",  # URL-prefix property; use "sc-domain:example.com"
                                      # instead for a Domain property — must be verified
    body=request,
).execute()

for row in response.get("rows", []):
    print(row["keys"], row["clicks"], row["impressions"])

To go past 25,000 rows, loop and increment startRow by 25,000 until a request returns no rows. Remember the result is still “top rows,” not a complete dump — for that, use the BigQuery bulk export.

Tools that use (or wrap) the Search Console API

• Google Cloud Console — where you create the project, enable the API, and mint OAuth/service-account credentials.
• Official client libraries — Google API client libraries for Python, Java, JavaScript/Node, PHP, and .NET wrap the REST calls.
• BigQuery — the destination for the bulk data exportGSC BigQuery export (bulk data export) is a Google Search Console feature that schedules a daily, unsampled export of a property's Performance data into a Google Cloud BigQuery project — bypassing the UI's ~1,000-row export cap and its rolling ~16-month retention window. It doesn't backfill and still excludes anonymized queries at the query level.; query all your performance data with SQL.
• Looker Studio — connects to Search ConsoleA free Google service that reports how a site performs in Google Search and surfaces problems with how Google crawls, indexes, and serves it. It's first-party data straight from Google — but you don't need it to appear in results. (and BigQuery) for dashboards built on the same data.
• Ahrefs — integrates the Search Console APIA set of REST APIs that let you programmatically read and manage Google Search Console data for properties you've verified — Performance data, URL index status, sitemaps, and properties — authorized with OAuth 2.0.; its Rank Tracker shows full GSC history, the share of clicks going to anonymized queries, and a custom CTR curve from your own data.
• Search ConsoleGoogle's free tool for monitoring crawling, indexing, and search performance. interface — the Performance reportThe Google Search Console report that shows how your site actually performed in Google Search, built from real impressions and clicks. It reports four metrics — clicks, impressions, average CTR, and average position — and keeps the most recent 16 months of data. and URL Inspection toolA Google Search Console feature that reports how Google sees one specific URL on a property you own. By default it shows the last-indexed snapshot; a separate \"Test live URL\" mode fetches the current version. are the manual counterparts to the Search Analytics and URL Inspection APIs, with one gap the API can’t close: only the interface tool can run a live test on a URL.

Prompts for planning Search Console API work

Use these prompts to shape code or an analysis plan. Keep credentials, refresh tokensA token is the smallest unit of text (or image/audio/video) an LLM processes — roughly 4 characters, or about ¾ of an English word. A context window is the maximum number of tokens (input plus output) a model can hold at once, like its short-term memory., and service-account keys out of any chat input.

Design a Search Analytics request

Paste your property URL, date range, dimensions, filters, and reporting goal.

Design a Google Search Console Search Analytics API request for the following reporting task.

Property: [sc-domain:example.com or exact URL-prefix property]
Date range: [start and end]
Goal: [the question the report must answer]
Dimensions: [date, query, page, country, device, searchAppearance, or hour]
Filters: [include/exclude rules]

Return:
1. The request body, including a rowLimit no higher than 25,000.
2. Pagination logic using startRow.
3. The aggregation and grouping needed after retrieval.
4. Warnings about top-rows-only data and anonymized queries.
5. A small validation query I can run before scheduling the full pull.

Do not invent credentials or assume the result is a complete census.

Plan a quota-safe URL Inspection schedule

Paste a CSV summary or counts by URL priority rather than confidential tokens.

Create a quota-safe sampling and scheduling plan for the Search Console URL Inspection API.

Property: [property]
Total URLs: [count]
Priority groups: [critical templates, new URLs, changed URLs, long-tail sample]
Required revisit cadence: [daily, weekly, monthly]

Constraints from this article:
- 2,000 inspection queries per day per site.
- 600 inspection queries per minute per site.
- The API reports the indexed version, not a live test.

Return a daily allocation by priority group, a rotation method, retry/backoff rules,
and alerts for unexpected index or canonical states. Explain what cannot fit inside
the quota instead of silently dropping it.

Choose API versus BigQuery export

Help me choose between the Search Console interface, Search Analytics API, and BigQuery bulk export.

Reporting need: [one-off analysis, dashboard, warehouse, anomaly alerts]
Expected rows per day: [estimate]
History required: [range]
Refresh cadence: [cadence]
Dimensions needed: [list]
Infrastructure available: [spreadsheet, script runner, BigQuery, BI tool]

Compare setup cost, row/completeness limits, automation, and maintenance. Account for
the API returning top rows and for anonymized queries being absent from every path.
End with one recommendation and the smallest proof-of-concept to validate it.

Resources worth your time

My related work

• Ahrefs blog — my posts — including the work on GSCA free Google service that reports how a site performs in Google Search and surfaces problems with how Google crawls, indexes, and serves it. It's first-party data straight from Google — but you don't need it to appear in results. data at scale and anonymized queries.
• Now in Ahrefs Rank Tracker: full GSC history + anonymized-query share — the CTR-curve and GSC-history feature I announced.

Google’s docs

• Search Console API overview and the usage limits page — the two pages to bookmark first.
• About bulk data export — when and how to move to BigQuery.

From others

• Hidden keywords in GSC — the Ahrefs study (Search Engine Journal coverage) — third-party write-up of the anonymized-query findings.
• Enhanced Search Console analytics with BigQuery (SEJ) — a practical look at the bulk-export path.
• Bulk data export: a new and powerful way to access your Search Console data (Google Search Central blog) — the Feb 2023 launch post from the Search ConsoleGoogle's free tool for monitoring crawling, indexing, and search performance. team positioning bulk export for large sites.
• google-api-python-client (PyPI) — the official Python client library used to call the Search Console APIA set of REST APIs that let you programmatically read and manage Google Search Console data for properties you've verified — Performance data, URL index status, sitemaps, and properties — authorized with OAuth 2.0.; also available for Node, Java, PHP, and .NET via the Google APIs client library family.
• r/TechSEO — the community for API and data-pull troubleshooting.

Stats worth citing

• Search Analytics row limit: 25,000 per request (default 1,000) — versus the interface export’s ~1,000-row cap. This is the core reason to use the API. Source
• URL InspectionA Google Search Console feature that reports how Google sees one specific URL on a property you own. By default it shows the last-indexed snapshot; a separate \"Test live URL\" mode fetches the current version. quota: 2,000 queries/day and 600/minute per site — the hard ceiling on large-scale indexStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed. monitoring (10M/day, 15,000/min per project). Source
• Anonymized queries are excluded from even the most complete path (BigQuery bulk export) — a real, unavoidable gap in your query data. Source
• Google hides the keyword term on a large share of clicks — from the Ahrefs study I helped surface, which pulled all available data from the API across a very large sample of sites. Coverage

Test yourself: Search Console API

Five quick questions on the APIs, authentication, data limits, and scale. Pick an answer for each, then check your result.

Search Console API

A set of REST APIs that let you programmatically read and manage Google Search Console data for properties you've verified — Performance data, URL index status, sitemaps, and properties — authorized with OAuth 2.0.

Related: Google Search Console, Performance report, URL Inspection tool

Search Console API

The Search ConsoleA free Google service that reports how a site performs in Google Search and surfaces problems with how Google crawls, indexes, and serves it. It's first-party data straight from Google — but you don't need it to appear in results. API is how you pull and manage Google Search ConsoleA free Google service that reports how a site performs in Google Search and surfaces problems with how Google crawls, indexes, and serves it. It's first-party data straight from Google — but you don't need it to appear in results. data with code instead of clicking around the interface. It’s made up of four REST APIs: the Search Analytics API (Performance reportThe Google Search Console report that shows how your site actually performed in Google Search, built from real impressions and clicks. It reports four metrics — clicks, impressions, average CTR, and average position — and keeps the most recent 16 months of data. data — clicks, impressions, CTR, position by dimension), the URL InspectionA Google Search Console feature that reports how Google sees one specific URL on a property you own. By default it shows the last-indexed snapshot; a separate \"Test live URL\" mode fetches the current version. API (the Google-indexStoring a crawled page in the search index so it can appear in results. Crawled is not the same as indexed — Google selects what to keep, and indexing isn't guaranteed. status of a single URL), the SitemapsA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing. API (list, get, submit, and delete sitemapsA sitemap is a file that lists the pages, images, videos, and other files on your site so search engines can discover them. It helps discovery, but submitting a sitemap doesn't guarantee crawling or indexing.), and the Sites API (list, add, and remove verified properties).

All access is authorized with OAuth 2.0 using one of two scopes — webmasters for read/write or webmasters.readonly for read-only — and the API only returns data for properties on which you have verified access (owner, full, or read). There’s no simple API key.

The Search Analytics API returns up to 25,000 rows per request (default 1,000), which is far more than the UI’s ~1,000-row export. But it only returns top rows and doesn’t guarantee completeness, so for very large datasets the better path is the bulk data exportGSC BigQuery export (bulk data export) is a Google Search Console feature that schedules a daily, unsampled export of a property's Performance data into a Google Cloud BigQuery project — bypassing the UI's ~1,000-row export cap and its rolling ~16-month retention window. It doesn't backfill and still excludes anonymized queries at the query level. to BigQuery, which gives you all available performance data daily — everything except anonymized queries.

Related: Google Search Console, Performance report, URL Inspection tool

Changelog