- The API is read-only for performance data: you call
searchAnalytics/querywith a date range and dimensions and get rows of clicks, impressions, CTR and average position. - Authenticate with OAuth 2.0 and the
webmasters.readonlyscope; usewebmastersonly if you also need to change sitemaps or sites. - A Domain property is addressed as
sc-domain:example.com; a URL-prefix property as its full URL, such ashttps://www.example.com/. - rowLimit tops out at 25,000 rows per request (default 1,000); page with
startRowand expect the API to return top rows, not every row. - Data lags by roughly two to three days, history covers 16 months, and quotas are 1,200 queries per minute per site and per user.
What is the Google Search Console API?
The Google Search Console API is a REST API that returns your Search Console performance data as JSON. You send a date range and a list of dimensions to the searchAnalytics/query method, and it returns rows of clicks, impressions, CTR and average position, grouped the way you asked. It is the same data behind the Performance report in the Search Console UI, exposed for scripts, dashboards and data warehouses.
The API is part of the Search Console API v3, formerly the Webmaster Tools API. It also lists your verified sites and manages sitemaps, but most developers use it for search analytics. Google's searchAnalytics/query reference is the authority for every field below.
How do you authenticate with OAuth 2.0?
Create a Google Cloud project, enable the Search Console API, configure an OAuth 2.0 client, and request the webmasters.readonly scope. The user signs in with the Google account that can access the Search Console property, and your app exchanges the authorization code for an access token.
- Read-only scope:
https://www.googleapis.com/auth/webmasters.readonlyreads performance data, sites and sitemaps. - Read-write scope:
https://www.googleapis.com/auth/webmastersalso lets you add or remove sites and submit or delete sitemaps. Request it only when you need those writes. - Access tokens expire after about an hour. Store the refresh token and exchange it for a new access token instead of asking the user to sign in again.
- Service accounts work only if the service account's email is added as a user on the Search Console property; a Domain property still needs that delegation.
Google's authorization guide covers the OAuth flow and the client libraries. Keep the client secret on the server, never in browser code.
Which property URL do you use?
Use the exact property identifier from Search Console: sc-domain:example.com for a Domain property, or the full URL for a URL-prefix property. The siteUrl path parameter must match the property as Search Console stores it, including the trailing slash on a URL-prefix property.
Property types and their API identifiers
| Property type | Covers | siteUrl value |
|---|---|---|
| Domain | Every subdomain and protocol for the domain | sc-domain:example.com |
| URL-prefix | Only URLs beneath the exact prefix | https://www.example.com/ |
| URL-prefix, subfolder | Only that folder and below | https://example.com/blog/ |
Call GET https://www.googleapis.com/webmasters/v3/sites to list the exact identifiers the authenticated account can read. Do not guess the form; copy it from that response.
Which dimensions and metrics can you query?
Group by any of query, page, country, device, date, searchAppearance and hour, and every row returns clicks, impressions, CTR and position. The order of the dimensions sets the order of the keys in each row.
Search Analytics dimensions and metrics
| Field | Type | What it gives you |
|---|---|---|
query | Dimension | The search query that produced an impression |
page | Dimension | The URL that appeared in results |
country | Dimension | Three-letter ISO 3166-1 alpha-3 country code |
device | Dimension | DESKTOP, MOBILE or TABLET |
date | Dimension | Day in YYYY-MM-DD, in Pacific time |
searchAppearance | Dimension | The result feature, such as a rich result or video |
clicks | Metric | Clicks from Google search results to the property |
impressions | Metric | Times a link to the property appeared |
ctr | Metric | Clicks divided by impressions, from 0 to 1 |
position | Metric | Average position for the row |
Use type to choose the surface: web (the default), image, video, news, discover or googleNews. Use aggregationType to aggregate by property or by page; if you group or filter by page, you cannot aggregate by property.
What are the row limits and how do you page?
rowLimit accepts 1 to 25,000 rows and defaults to 1,000; page through larger results with startRow. The API is bounded by Search Console's own limits and returns the top rows, not a guaranteed complete set. A query grouped or filtered by both page and query is the most expensive kind.
- Default page size: 1,000 rows. Set
rowLimitexplicitly when you need more. - Maximum page size: 25,000 rows per request.
- Paging: increase
startRowby your page size until a response returns fewer rows than requested. - Sorting: results are sorted by clicks descending, or by date ascending when you group by date.
- Missing days: when you group by date, days with no data are omitted, so do not assume a gap means zero.
How fresh is the data?
Search Console data lags by roughly two to three days, and the API keeps about 16 months of history. The most recent days can still change as Google finalises them. Request dataState: "all" to include fresh, incomplete data, or leave it at the default final for settled numbers.
When you request fresh data grouped by date, the response can include a metadata.first_incomplete_date field. Every date after it may still change noticeably, so treat those rows as provisional. For reporting, query final data and state the date range you used.
What are the quotas?
Search Analytics allows 1,200 queries per minute per site and 1,200 per user, with a per-project cap of 40,000 per minute and 30,000,000 per day. Google also enforces short-term and long-term load quotas that count how expensive a query is, not just how many you send.
Search Console API quotas, from Google's limits page
| Resource | Limit |
|---|---|
| Search Analytics, per site | 1,200 queries per minute |
| Search Analytics, per user | 1,200 queries per minute |
| Search Analytics, per project | 40,000 per minute, 30,000,000 per day |
| URL inspection, per site | 600 per minute, 2,000 per day |
| All other resources, per user | 20 per second, 200 per minute |
If you exceed a quota you get a quotaExceeded error. Wait 15 minutes before retrying a short-term limit; if it still fails, you are over the long-term load quota and should reduce grouping, filtering or the date range.
Official request examples
Send a POST to the searchAnalytics/query method with a JSON body containing startDate, endDate and optional dimensions. These examples follow Google's reference; replace the placeholders with your own values.
List the properties you can read
GET https://www.googleapis.com/webmasters/v3/sites
Authorization: Bearer <access_token>
Query clicks and impressions by country and device
POST https://www.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query
Authorization: Bearer <access_token>
Content-Type: application/json
{
"startDate": "2026-10-01",
"endDate": "2026-10-31",
"dimensions": ["country", "device"]
}
Page through query rows with rowLimit and startRow
POST https://www.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query
Authorization: Bearer <access_token>
Content-Type: application/json
{
"startDate": "2026-10-01",
"endDate": "2026-10-31",
"dimensions": ["query"],
"rowLimit": 25000,
"startRow": 0
}
Filter to one page and include fresh data
POST https://www.googleapis.com/webmasters/v3/sites/https%3A%2F%2Fwww.example.com%2F/searchAnalytics/query
Authorization: Bearer <access_token>
Content-Type: application/json
{
"startDate": "2026-11-01",
"endDate": "2026-11-14",
"dimensions": ["query"],
"dimensionFilterGroups": [
{
"filters": [
{ "dimension": "page", "operator": "equals", "expression": "https://www.example.com/pricing" }
]
}
],
"dataState": "all"
}
API vs Search Console UI vs MrKeyword
Use the API when you need the raw data in your own systems, the UI when you want to explore it by hand, and MrKeyword when you want the data stored, tracked and readable by AI tools without building an integration. Each covers a different job.
Google Search Console API compared with the UI and MrKeyword
| Capability | Search Console API | Search Console UI | MrKeyword |
|---|---|---|---|
| Access | OAuth 2.0, your own Google Cloud project | Sign in to Search Console | Connect Search Console once, read-only |
| Data returned | JSON rows: clicks, impressions, CTR, position | Charts and tables you filter by hand | Stored daily copy, plus Bing Webmaster Tools |
| History | About 16 months, same as the UI | About 16 months | Backfills up to 16 months, then keeps its own copy |
| Row limits | 25,000 per request, paged with startRow | UI row caps per table | Up to 2,000 pages and 5,000 queries per site per day |
| Effort | Build and maintain the integration | None, but manual | No code; MCP and API access included |
| Best for | Data warehouses, custom dashboards, automation | Quick checks and one-off investigations | Rank tracking, reporting and AI assistants |
How do you get this data without building an integration?
Connect Search Console to MrKeyword and read the same data through its API or MCP server, with no Google Cloud project to maintain. MrKeyword syncs Search Console and Bing Webmaster Tools daily, stores its own copy, and exposes the data to dashboards and AI clients.
- MrKeyword developer reference: the API and MCP endpoints, tokens, scopes and limits.
- The MrKeyword data API: query your stored Search Console and rank data from your own code.
- Google Search Console MCP: give Claude or Cursor your Search Console data over MCP.
Skip the OAuth plumbing.Connect Search Console once and query the stored data from your own tools.
See the data APIQuestions and answers
Google Search Console API questions
What is the Google Search Console API?
It is a REST API that returns your Search Console performance data as JSON. You call searchAnalytics/query with a date range and dimensions, and it returns rows of clicks, impressions, CTR and average position.
Which OAuth scope does the Search Console API need?
Use https://www.googleapis.com/auth/webmasters.readonly to read performance data, sites and sitemaps. Use https://www.googleapis.com/auth/webmasters only if you also need to add or remove sites or change sitemaps.
What is the row limit on the Search Console API?
rowLimit accepts 1 to 25,000 rows and defaults to 1,000. Page through larger results with startRow, and expect the API to return top rows rather than a guaranteed complete set.
How far back does the Search Console API go?
About 16 months, the same window as the Search Console UI. The most recent two to three days can still change as Google finalises them.
What are the Search Console API quotas?
Search Analytics allows 1,200 queries per minute per site and per user, with a per-project cap of 40,000 per minute and 30,000,000 per day. Google also enforces short-term and long-term load quotas.
Can I get Search Console data without building an API integration?
Yes. MrKeyword connects to Search Console read-only, syncs the data daily, stores its own copy and exposes it through its API and MCP server, so you skip the Google Cloud and OAuth setup.
Sources
- Search Analytics query reference — Google for Developers: dimensions, rowLimit, startRow, dataState, scopes and the JSON POST example
- Search Console API usage limits — Google for Developers: 1,200 QPM per site and per user, project caps, URL inspection limits
- Authorizing requests — Google for Developers: OAuth 2.0 scopes
- Search Console performance data — Google Search Console Help: metrics, 16 months of data and delays
- MrKeyword developer reference — API and MCP endpoints, tokens, scopes and limits


