Google Search Console API with Python: a working script, and where it stops
A copy-paste Python script that pulls Search Console performance data into a CSV: service account setup, searchAnalytics.query, paging past 25,000 rows, and the limits the script still leaves you with.
To pull Google Search Console data with Python, create a service account, add it as a user on your Search Console property, and call searchanalytics().query() from Google's google-api-python-client, paging with startRow in steps of 25,000. The script below does exactly that and writes the rows to a CSV. It is about 50 lines, and the parts people get wrong are the setup and the paging, not the request.
TL;DR:
- Install
google-api-python-clientandgoogle-auth. - A service account needs to be added as a user on the Search Console property, or every call returns a permission error.
- One request returns at most 25,000 rows. Re-run it with
startRowraised by 25,000 until a page comes back short. - Google says the API exposes at most 50,000 rows a day per search type, and that adding
pageorqueryas a dimension can drop rows. Totals come from date-only queries. - The script gives you the last 16 months, the same as the web interface. Anything older is gone.
What you need before you run it
- A Google Cloud project with the Search Console API enabled. In the Cloud Console, open APIs and Services, search for "Google Search Console API" and enable it.
- A service account and its JSON key. Create one under IAM and Admin, then Service accounts, and download a key. Save it next to the script as
service-account.json, and keep it out of your repo. - The service account added to your property. In Search Console, open Settings, then Users and permissions, and add the service account's email address (it ends in
iam.gserviceaccount.com). - The two libraries:
pip install google-api-python-client google-auth
A service account suits a script that runs on a schedule. For a one-off run on your own machine, an OAuth login with google-auth-oauthlib works too and skips step 3, at the cost of a browser prompt.
The script
"""Pull Search Console performance rows for one property into a CSV.
Usage:
python gsc_export.py sc-domain:example.com 2026-10-01 2026-10-28 out.csv
"""
import csv
import sys
from google.oauth2 import service_account
from googleapiclient.discovery import build
SCOPES = ["https://www.googleapis.com/auth/webmasters.readonly"]
KEY_FILE = "service-account.json"
PAGE_SIZE = 25000 # the API's maximum rowLimit
def get_service():
creds = service_account.Credentials.from_service_account_file(KEY_FILE, scopes=SCOPES)
return build("searchconsole", "v1", credentials=creds)
def fetch_all(service, site, start, end, dimensions):
"""Page through results with startRow until a page comes back short."""
rows, start_row = [], 0
while True:
body = {
"startDate": start,
"endDate": end,
"dimensions": dimensions,
"rowLimit": PAGE_SIZE,
"startRow": start_row,
"type": "web",
"dataState": "final",
}
resp = service.searchanalytics().query(siteUrl=site, body=body).execute()
page = resp.get("rows", [])
rows.extend(page)
if len(page) < PAGE_SIZE:
return rows
start_row += PAGE_SIZE
def main(site, start, end, out_path):
service = get_service()
dimensions = ["date", "page"]
rows = fetch_all(service, site, start, end, dimensions)
with open(out_path, "w", newline="", encoding="utf-8") as f:
writer = csv.writer(f)
writer.writerow(dimensions + ["clicks", "impressions", "ctr", "position"])
for r in rows:
writer.writerow(r["keys"] + [r["clicks"], r["impressions"], r["ctr"], r["position"]])
print(f"{len(rows)} rows written to {out_path}")
if __name__ == "__main__":
main(*sys.argv[1:5])
Run it with your property exactly as Search Console names it: sc-domain:example.com for a domain property, or the full URL with its trailing slash (https://example.com/) for a URL-prefix property.
How we checked it: we ran the paging and CSV code against a stand-in for the API at 0, 10, 25,000, 25,001 and 60,000 rows, and confirmed Google's own client turns the call into the documented request: a POST to the property's searchAnalytics/query endpoint. We have not run it against a live property for this post, because that needs a key on a real account. If it fails for you with a permission error, check step 3 first.
Try it
Point an SEO agent at your own site, not just an essay about one.
QueryScope holds the plan for your site, reads your real Search Console, and hands the coding agent you already have one change at a time to rank for the searches you decided to win. From $49/month, everything included.
What each part of the request does
All of these are documented on Google's searchAnalytics.query reference:
dimensionsgroups the rows. You can usedate,hour,country,device,page,queryandsearchAppearance, but not the same one twice.["date", "page"]gives one row per page per day.rowLimitis 1 to 25,000, default 1,000. Always ask for the maximum and page.startRowis the zero-based index of the first row. It is how you page.dataStatedefaults tofinal, finalized data only.alladds fresh data that can still change.typeis the search type:webby default, orimage,video,news,discover,googleNews.- Scope:
webmasters.readonlyis enough to read. Only ask forwebmastersif you also manage sitemaps or properties.
Why paging matters, and where it stops
Google's guide to getting all your data says to "page through results by re-running the same query, increasing the startRow value by 25,000" until a response comes back empty. The script stops one call earlier, on the first page shorter than 25,000 rows, which saves one empty request.
Two limits paging cannot get past, both from the same guide:
- A daily ceiling. The API "exposes a maximum of 50K rows of data per day per search type", sorted by clicks. On a large site, the long tail beyond that never comes back.
- Detail costs completeness. "For accurate counts, you must omit the page and query dimensions." A
date, pagepull is close to complete. Addqueryand rows go missing, because Search Console also withholds rare searches for privacy (more on that in anonymized queries). So never add up query rows and call it your total. Take totals from a date-only query, and read queries for what people searched.
The API also has request quotas of its own, covered in Search Console API limits.
What the script still leaves you to build
A CSV is a snapshot. Three things it does not give you:
- History past 16 months. The API reads the same store as the web interface, which keeps 16 months and deletes the oldest day every day. To keep more, run the script daily and keep every file. Why the 16-month wall matters.
- A record of what you changed. The numbers move, and the CSV does not know you rewrote a title on the 12th.
- A way to read a change. Comparing two exports by eye mixes your change with whatever the rest of the site did those weeks.
That is the part QueryScope does without a script. It connects to your Search Console over a read-only grant, stores a daily snapshot from the day you connect, and serves the data to your coding agent over MCP. Your agent records each change it ships, and QueryScope measures it from the day Google recrawls the page.
Sources
- Google for Developers, Search Analytics: query (request URL, dimensions, rowLimit 1 to 25,000, startRow, dataState, type, scopes).
- Google for Developers, Getting all your data (paging with startRow in steps of 25,000; at most 50,000 rows per day per search type; omit page and query for accurate counts).
Try it
Put an SEO agent in your editor.
Ask your coding agent what to work on. QueryScope reads your real Search Console, holds the searches you decided to win, and hands back one move at a time with the proof it worked. From $49/month, everything included. 1, 3 or 10 sites.