How to use the Search Console URL Inspection API

The Search Console URL Inspection API lets you check how Google sees a specific URL, programmatically, without opening Search Console. It returns the same indexed data as the URL Inspection tool: whether the page is indexed, when Google last crawled it, which canonical Google chose, and any rich result issues.

Checking one page at a time in the Search Console interface is fine for spot checks. It’s slow when you need to confirm the indexing status of 500 product pages after a migration, or watch a set of key URLs every week. The API does that work in a script.

It’s free and Google launched it in January 2022. The main limits are a daily quota per property and the fact that it only reads Google’s stored data. It can’t request indexing or run a live test.

What the URL Inspection API returns

Each request returns an inspection result for one URL. The most useful part is the index status, which includes:

• Verdict: a top-level pass, neutral or fail for the URL
• Coverage state: the same wording you see in Search Console, such as “Submitted and indexed” or “Crawled, currently not indexed”
• Robots.txt state: whether robots.txt allowed or blocked the crawl
• Indexing state: whether a noindex rule blocked indexing
• Last crawl time and crawled as (mobile or desktop Googlebot)
• Page fetch state: whether the fetch succeeded or hit an error such as a 404 or a server error
• Google canonical and user canonical: the canonical Google picked and the one you declared
• Sitemaps and referring URLs where Google found the page

The response can also include a rich results section, listing detected structured data types and any errors, and a link to open the same inspection in Search Console.

The canonical fields are the ones we check most often. When the Google canonical differs from the user canonical, Google has decided another URL should represent the page, and that’s usually worth investigating. Our guide to indexability explains the signals behind those decisions.

Quotas and limits

Google sets the URL Inspection API quota per Search Console property:

Limit	Value
Queries per day, per property	2,000
Queries per minute, per property	600

Two thousand checks a day is plenty for monitoring key pages, but not enough to inspect every URL on a large ecommerce site in one go. For big sites, pick a sample: top landing pages, new pages, pages that changed recently, and a rotating slice of the rest.

A few other limits matter in practice:

• The URL must belong to the property you name in the request, and the account calling the API needs access to that property.
• It reports the indexed version of the page, not a live fetch. If you fixed something an hour ago, the API won’t show it until Google recrawls.
• There’s no way to request indexing through this API.

How to set up access

You need a Google Cloud project with the Search Console API enabled, and credentials that have access to the property. The setup takes about 15 minutes:

1. Create or choose a project in Google Cloud Console.
2. Enable the Google Search Console API for that project.
3. Create a service account and download its key file. Store it somewhere private, never in a public code repository.
4. In Search Console, add the service account’s email address as a user on the property. Restricted access is enough for inspection.
5. Use the read-only Search Console scope in your script, so the credentials can’t change anything.

The property identifier must match exactly how it’s set up in Search Console. A URL-prefix property looks like “https://www.example.com/” with the trailing slash. A domain property looks like “sc-domain:example.com”.

A short, safe example in Python

This example uses Google’s API client library for Python. It checks a short list of URLs, uses a read-only scope, pauses between calls to stay well inside the per-minute limit, and prints the key fields.

import time
from google.oauth2 import service_account
from googleapiclient.discovery import build

SCOPES = ["https://www.googleapis.com/auth/webmasters.readonly"]
creds = service_account.Credentials.from_service_account_file(
    "service-account.json", scopes=SCOPES)
service = build("searchconsole", "v1", credentials=creds)

site = "sc-domain:example.com"
urls = [
    "https://www.example.com/",
    "https://www.example.com/services/",
]

for url in urls:
    body = {"inspectionUrl": url, "siteUrl": site}
    result = service.urlInspection().index().inspect(body=body).execute()
    status = result["inspectionResult"]["indexStatusResult"]
    print(url, status.get("coverageState"),
          status.get("lastCrawlTime"), status.get("googleCanonical"))
    time.sleep(1)

Swap in your own property and URLs, and keep the key file name out of anything you share. From here it’s easy to write results to a spreadsheet and compare them week to week.

Practical uses for SEO teams

The API earns its keep on jobs that would take hours by hand:

• Migration checks: confirm new URLs are indexed and old ones are being dropped after a redirect project.
• Canonical audits: find pages where Google ignored your declared canonical.
• Indexing monitoring: track whether new content gets crawled and indexed, and how long it takes.
• Crawl data enrichment: add Google’s index status to the output of a site crawl, so you can see which crawlable pages Google still hasn’t indexed.

Several crawlers can call the API for you if you connect Search Console, which saves writing code at all. Pair it with a full site crawl and log file analysis and you get a clear view of what Google can reach, what it actually visits and what it chooses to keep.

If you’d like help building indexing checks into your reporting, our technical SEO team sets this up for clients as part of ongoing work. Book a free strategy session to talk it through.

Related reading: our guides to technical SEO and robots.txt.

Common questions