Google Search Console API: access, scopes, limits and a first query

The Search Console API returns the same performance data as the report with far fewer limits on rows, and it is free within a usage quota. To use it you register an application in the Google API Console, activate the Search Console API, ask the user for a scope, authorize with OAuth 2.0 and call searchanalytics.query. Performance data is limited to 50K rows per day per search type per property, and quotas apply. Google documents the access side in Authorize Requests.

Access, scopes and OAuth

Register the application in the Google API Console to get a client ID and a client secret, and activate the Search Console API for the project. Then choose the scope. webmasters.readonly gives read-only access and webmasters gives read and write access; ask for the smallest one you need, and do not request the read/write scope for a reporting script unless you must add sites or submit sitemaps.

Every request must be authorized by an authenticated user. The user sees a consent screen, Google issues a short-lived access token, and a refresh token can obtain new ones.

Your first query

Call searchanalytics.query with a start date, an end date and the dimensions you want. The dates are in Pacific Time. Results come sorted by clicks, and by default only finalized data is returned; dataState “all” includes fresh data. The row limit runs from 1 to 25,000 with a default of 1,000, and startRow moves to the next page (searchanalytics.query). The API supports filtering, sorting and aggregation like the reports, but not free-form SQL; for that, use the bulk export to BigQuery.

It returns more rows than the interface: the report export is truncated to 1,000 rows, while the API returns up to 50K rows per day per search type per property (export data using the API). Days without data are omitted when you group by date, so do not assume a missing day is zero.

Quotas and what “quota exceeded” means

Search Analytics allows 1,200 queries per minute per site and per user, and 40,000 per minute and 30,000,000 per day per project; URL inspection allows 2,000 per day and 600 per minute per site (usage limits). The limits stack. Google’s example: user A can make up to 1,200 queries per minute combined across her three sites, and users A and B can make up to 1,200 per minute combined against their one shared site. The project-level limits apply to everyone using the same Cloud project key.

The “quota exceeded” error looks the same for every quota. If waiting 15 minutes fixes it, you hit the short-term load quota, measured in 10-minute chunks, so spread queries through the day. If one query inside a 10-minute window already fails, you hit the daily load quota. Some queries are simply expensive: grouping or filtering by page or by query is costly, and by page and query together is the most costly, with cost growing with the date range. Drop a grouping, shorten the range and do not ask for the same data again.

A worked example of paging

To pull query-and-page data for 28 days, ask for one day at a time. A day holds at most 50,000 rows, which is 2 requests of 25,000 each (startRow 0 and 25,000), so 28 days take 56 requests. The call rate is far below 1,200 per minute; the binding limit is the load quota, which is why a short range and one day at a time helps. Cache the result: repeating a large query burns load quota for nothing.

Cost and SEOKit

The API itself is free, within the usage quota. The SEOKit export tool and MCP server use this same API and are subject to the same limits; our article on export rows and columns shows what that means in practice.

Go further

How to use the Performance report: Limits and export options in the interface. Docs: default filters and exports: The export tool in the workspace. Playbook: five ways to connect ChatGPT: API, export and BigQuery compared.