url inspection api: Setup, Responses, and Quota Planning

Quick Answer

Google's url inspection api lets authorized website owners and developers retrieve Google's stored indexing information for individual URLs through authenticated requests. It reports crawl, indexability, and canonical data but cannot test a live page or request indexing. For bulk checks, teams must manage Search Console property access and Google's API quotas.

Key Takeaways

The API works best as part of a planned monitoring system. Access, response fields, and request limits all affect the value of its reports.

• Google's URL Inspection API returns stored indexing information, not the results of a new live-page test.
• Every request needs an exact inspection URL and a matching Search Console property identifier.
• OAuth authorization and Search Console property access are separate needs that must both be met.
• Returned fields describe crawl, indexing, and canonical evidence, but some values may be unavailable.
• A successful page fetch does not, by itself, prove that Google indexed the inspected URL.
• Google's documented site-level quota is 2,000 requests per day, even when project quotas allow more.
• Live URL testing and indexing notifications use different Google tools and must not be confused with API inspections.

The right design joins accurate requests with careful result handling. A quota-aware queue then turns those results into useful follow-up work.

What the url inspection api Can and Cannot Do

Google's URL Inspection API retrieves indexed-version information for URLs in accessible Search Console properties. It does not test the current page, submit URLs for indexing, or promise search visibility. That boundary should guide the design of every API workflow.

Google's official URL Inspection API method reference defines the index.inspect method. It provides structured information about Google's stored view of a URL. That can include a high-level indexing verdict, fetch details, crawl information, and canonical signals.

Stored information may lag behind a website change. Suppose a developer removes an unwanted noindex directive this morning. An API request made today might still describe Google's earlier crawl. The old report does not prove the new page is faulty.

A successful HTTP response from the API has a different meaning. It confirms that the API handled an authorized inspection request. It does not confirm that Google indexed the page.

Google's Search Console URL Inspection help explains the separate interactive Live Test. That test checks supported conditions on the current page. It is useful after a repair, but it does not guarantee indexing either.

For a deeper manual review, use the existing Search Console inspection results and fixes guide. The API workflow described here serves a different need: gathering structured indexing records across many authorized URLs.

Use the API when you need repeatable reports, dated observations, and a consistent way to group URLs for review. Switch to live testing when a current technical fault needs proof. Keep Google's eventual indexing decision separate from both activities.

Set Up Authentication and Search Console Property Access

An integration needs two forms of access. First, the application must obtain valid OAuth authorization for the Google API. Second, the authorized identity must have access to the Search Console property being inspected. A valid token alone does not grant access to every website.

Start with a Google Cloud project and the supported Search Console API setup. Enable the required API, configure the appropriate OAuth client or authorized service identity, and establish property permissions before sending inspection requests. Keep credentials and tokens out of source code and exported audit reports.

Select the Right OAuth Scope

Google supports two OAuth scopes for the inspection method. Use the read-only scope when the application only needs to retrieve inspection data.

The supported scopes are:

• The Search Console read-only OAuth scope, https://www.googleapis.com/auth/webmasters.readonly, grants supported read-only access.
• The https://www.googleapis.com/auth/webmasters scope provides broader Search Console authorization.

Google's OAuth scope reference lists scopes used by Google APIs. Choose the least access your application needs. Broader access is not a fix for an unrelated property permission problem.

The authorization flow depends on the application. A desktop utility acting for a signed-in user differs from a server process that uses an approved service identity. Both need credentials that match their actual access model.

For a user-based integration, the person granting access should have the needed Search Console permissions. A service account, where supported and configured, also needs suitable access to the target property. Creating that account does not grant it access automatically.

Confirm the Property Identifier

The siteUrl field must match the Search Console property identifier. Do not assume it is simply the site's homepage address.

Two common forms are:

• sc-domain:example.com identifies a Search Console domain property.
• https://www.example.com/ identifies a URL-prefix property, including its trailing slash.

A domain property and a URL-prefix property are not interchangeable strings. The exact identifier matters because Google uses it to determine which property the request addresses.

For example, https://www.example.com/page/ falls within the illustrated domain property. It also falls within the matching https://www.example.com/ URL-prefix property, provided the authorized identity can access that property.

A property restricted to a different host or protocol may not cover the requested URL. Check both values before changing application code.

Check Access Before Debugging the Request

Build and test access in a clear order. Google's Search Console API authorization guide provides the broader authorization context.

A practical setup check follows this sequence:

1. Create or select the intended Google Cloud project and enable the supported API.
2. Configure the OAuth identity and an appropriate supported scope.
3. Obtain a valid access token through the selected authorization flow.
4. Confirm that the identity can access the exact Search Console property.
5. Check that the inspection URL belongs to that property.
6. Send one inspection request before preparing a large batch.

This sequence separates configuration mistakes from URL-specific problems. An API key alone is not enough to retrieve private Search Console inspection information.

If a request fails, save the error response without saving secrets. Check authentication, property access, and field values separately. Avoid granting broader permissions until the actual cause is clear.

Make Your First URL Inspection API Request

Send an authenticated POST request to the Google URL Inspection API endpoint. The body needs an inspectionUrl and a matching siteUrl. The optional languageCode controls the language of translated issue messages. Google's documented default is en-US.

Start with one authorized URL. Confirm that the response has the expected structure before using the same code across a larger site.

Required JSON Fields and Request Example

The following request body is hypothetical. It uses an example domain, not a real inspected property.

``json { "inspectionUrl": "https://www.example.com/page/", "siteUrl": "sc-domain:example.com", "languageCode": "en-US" } ``

Here, inspectionUrl identifies the exact page. siteUrl identifies the authorized Search Console property. The language setting is optional and does not change which URL Google inspects.

The request body does not contain a command to crawl or index the page. It asks Google to return available inspection data.

Send an Authenticated Request

Once the application has a valid OAuth access token, it can send the documented request. The following cURL example shows the required HTTP structure.

``bash curl --request POST \ 'https://searchconsole.googleapis.com/v1/urlInspection/index:inspect' \ --header 'Authorization: Bearer ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "inspectionUrl": "https://www.example.com/page/", "siteUrl": "sc-domain:example.com", "languageCode": "en-US" }' ``

Replace ACCESS_TOKEN with a valid token obtained through the approved OAuth flow. The example is documentation-based and has not been run against an authorized property for this article.

Do not place real credentials in shared scripts, screenshots, or public logs. A token provides access within its granted scope and must be treated as a secret.

Verify the Response Before Processing a Batch

A successful inspection response includes an inspectionResult object. Its available fields depend on the URL and Google's recorded data.

Before parsing the result, check the HTTP outcome. An unsuccessful API response should become an integration error record, not a false indexing verdict.

For a valid result, retain the raw JSON. Add the requested URL, property identifier, and inspection timestamp from your own system. Those details help you compare results across runs.

The returned inspectionResultLink may provide a link to the associated Search Console inspection view. Keep it separate from the indexing verdict.

After the first request, inspect the returned field names and optional values. Confirm that your parser handles absent fields without crashing or inventing positive results. This small test can prevent a larger batch from producing unreliable reports.

Turn API Response Fields Into Useful SEO Decisions

Read the API response as a collection of related observations. No single field can explain every indexing problem. A high-level verdict may identify a concern, while fetch, canonical, and crawl fields help narrow the next check.

The best report records what Google supplied, when it was checked, and which action the evidence supports. It must also preserve uncertainty. Missing values should stay missing instead of becoming false passes or failures.

Read the Indexed-State Fields

Google's URL Inspection result schema defines the main response objects and their fields.

The indexStatusResult object can contain several useful values. verdict gives a high-level result. coverageState adds a description of the recorded coverage condition.

robotsTxtState describes Google's recorded crawler access. indexingState can show whether Google found an indexing restriction, including a robots meta tag or HTTP header directive.

pageFetchState describes the recorded fetch result. Documented outcomes include successful fetches, missing pages, server errors, and redirect problems. A successful fetch is not the same as an indexed result.

lastCrawlTime, when present, helps you assess how old the stored observation may be. googleCanonical names Google's chosen canonical when provided. userCanonical reflects the site's declared canonical when available. crawledAs identifies the crawler type in the recorded data.

The schema also includes optional sitemap and referring URL information. These fields are not complete sitemap discovery records or backlink inventories. Rich-result information may be conditional. The mobile usability result field is deprecated and should not anchor a new monitoring system.

Match Recorded Evidence to the Next Action

A useful triage system joins fields instead of converting every response into one pass-or-fail label. The following matrix uses documented field values and hypothetical combinations. It does not claim these are results from real inspected URLs.

These distinctions prevent premature repairs. For instance, a different canonical does not prove that the declared canonical tag is broken. Google may have selected another representative of similar content.

For current technical checks, the website crawlability testing guide covers a separate diagnostic workflow. An API result can guide that work without replacing it.

Design a Reliable Export Record

A useful export should let an SEO specialist trace each finding back to a specific URL, property, and inspection run. It should also distinguish Google-supplied fields from your application's own labels.

The following JSON record is a hypothetical demonstration of a normalized export. Its dates, values, and triage label are illustrative, not observed Google data.

``json { "inspection_url": "https://www.example.com/page/", "site_property": "sc-domain:example.com", "inspection_timestamp_utc": "2026-10-26T10:00:00Z", "last_crawl_time_utc": null, "verdict": "NEUTRAL", "coverage_state": null, "robots_txt_state": null, "indexing_state": null, "page_fetch_state": null, "google_canonical": null, "user_canonical": null, "crawled_as": null, "inspection_result_link": null, "triage_group": "review_missing_evidence", "next_action": "Review available indexed data and confirm whether another check is needed", "error_type": null } ``

The example uses explicit null values to show how unavailable information should be stored. NEUTRAL is a documented verdict value, but the full record is not a sample retrieved from Google.

For a CSV export, use equivalent columns. Store raw API responses separately when possible. That makes later schema changes easier to handle and preserves details not included in a short report.

Keep two dates distinct. The inspection timestamp records when your system made the request. The last crawl timestamp comes from Google's data, if supplied. Mixing them can make an old indexed assessment look current.

Avoid closing a case based only on a successful API request. A defensible report identifies the recorded condition and the next check needed to assess it.

Calculate URL Inspection API Quotas Before a Bulk Run

Google's published URL Inspection API limits include 2,000 requests per site per day and 600 per site per minute. Separate Google Cloud project limits also apply. The site-level daily limit often controls a large single-property audit, even when the project has ample capacity.

These figures describe API request capacity. They do not describe how fast Google crawls or indexes a website. Confirm current limits before a production run because Google may revise them.

Apply Site-Level and Project-Level Limits

Google's Search Console API usage limits document the following quotas. The research reviewed the reference on October 26, 2026; the retrieved documentation showed an August 28, 2025 update.

Both quota scopes matter. A project that can make millions of requests per day still cannot ignore the documented daily cap for a single site.

Your scheduler should track the relevant property and project usage. It should also reserve capacity for other jobs that share those limits. Do not assume every advertised request is available to a new batch.

Calculate the Minimum Quota Days for 10,000 URLs

Consider an audit of 10,000 distinct URLs from one Search Console property. Each URL needs one inspection request. Assume the site receives the full published daily allowance, quotas remain unchanged, and no other workload consumes capacity.

The theoretical minimum is:

ceil(10,000 / 2,000) = 5 site-quota days

That is a capacity calculation, not a five-calendar-day completion promise. Actual processing may need more time due to errors, other usage, applicable project limits, and quota availability.

The same arithmetic gives a quick planning table for one property. These values assume one successful inspection attempt per URL and full daily quota availability.

This table helps plan audit frequency. A site with 50,000 URLs cannot assume that every page will receive a fresh daily inspection through this API under the stated per-site quota.

Large sites need to choose which URLs matter most. The aim is a useful monitoring sample and a clear queue, not a misleading claim of complete daily coverage.

Schedule Repeat Checks Without Wasting Quota

Group work by exact Search Console property. Remove duplicate URL-and-property pairs within an inspection cycle. Then prioritize pages whose results affect a current decision.

A practical queue can favor recently changed pages, high-value templates, unresolved errors, or URLs selected for a scheduled audit. Record the reason for each check so the same page does not consume repeated requests without a useful purpose.

Before dispatch, check that the authorized identity has the right property access. Track site-level and project-level usage. Set request pacing that stays within every applicable limit.

For each completed request, save the raw response and normalized result. Record unsuccessful attempts separately. If capacity runs out, retain unprocessed jobs for a later quota window rather than marking them inspected.

Use selective rechecks after meaningful website changes or when a later Google observation would help resolve a case. Do not claim that running more requests will make Google crawl or index URLs faster.

Troubleshoot Authentication, Quota, and Data Problems

Classify the failure before retrying. Permission problems, bad request fields, quota exhaustion, and absent response data have different causes. Treating them all as temporary API errors can waste requests and hide the real issue.

Start with the HTTP outcome and the returned error details. Then inspect the exact request body, authorization context, property identifier, and relevant quota state. A single HTTP status may have several causes, so use the full error response rather than guessing.

The following diagnostic matrix separates likely checks from the next sensible action. It is an implementation aid, not a claim that every Google error maps to one fixed cause.

A permission error will not be solved by sending the same request many times. First confirm the identity and property relationship.

An absent field is different from a rejected request. Successful responses may contain only some of the documented values. Your parser should accept that rather than replacing missing data with favorable defaults.

For temporary failures, maintain a retry count and preserve the original job identity. Do not silently duplicate records. A later successful request should be linked to the same URL audit task while keeping its own inspection timestamp.

Finally, keep application errors separate from indexing findings. A failed API call does not mean a page is unindexed. It means the inspection result was not obtained through that call.

URL Inspection API vs Live Test vs Indexing API

Use the URL Inspection API to retrieve Google's stored indexing data. Use Search Console's Live Test to examine supported current-page conditions. Google's separate Indexing API serves specific eligible content notification workflows. These tools solve different problems.

The Indexing API quickstart describes supported use cases involving JobPosting pages and qualifying BroadcastEvent content embedded in VideoObject. It is not a general indexing submission service for ordinary blog pages.

The Indexing API usage guide explains notification methods for that separate service. Its request model and batching behavior should not be attributed to the URL Inspection API.

Use the following comparison to choose the right workflow before building an integration.

A typical SEO team may need more than one method, but not for the same purpose. An API record may reveal an old fetch problem. A live check can then test the current page. Neither action proves that Google has updated its index.

For the separate manual workflow, see how to request indexing in Google Search Console. Keep submission steps outside the inspection automation itself.

Build a Monitoring Report That Leads to Action

A useful monitoring report tells a team what Google last recorded, what remains unknown, and which URLs need attention. It should not turn every successful request into a green indexing status.

Consider a hypothetical agency audit of 300 URLs from one authorized property. The URLs include important guides, product pages, and recently updated content. The agency wants a dated record of Google's indexed-state information, not a promise that all pages will appear in search.

First, the team checks property access and removes duplicate URL entries. Each request uses the appropriate siteUrl and an authorized OAuth token. The system saves the raw API response and a normalized export record.

The report then groups pages by actual returned evidence. URLs with recorded fetch errors go into technical review. Pages with differing canonical values require a comparison of URL signals. Missing crawl timestamps stay marked as unavailable rather than becoming presumed errors.

A simple operational report can contain these groups:

• Recorded index status needs no immediate action based on the current audit objective.
• A recorded technical issue needs a current-page check before repair.
• Canonical evidence needs review of the preferred URL and competing signals.
• Missing information needs a defined follow-up rather than an assumed result.
• A failed API request needs an integration fix or an authorized retry.

The groups are local reporting labels. They are not Google's official status names. Each should link back to the actual recorded fields and inspection date.

This workflow also supports later reviews. A second audit can compare newer Google observations with the first record. A changed verdict is useful evidence, but the team should still inspect the relevant fields before calling an issue resolved.

For deeper content-level diagnosis, the site's blog indexing troubleshooting guide covers a separate problem-solving task.

IndexNowFast also describes bulk indexing and tracking services on its own website. Such services are separate from Google's authenticated URL Inspection API. Their status reports should not be presented as private Search Console API results unless that capability is specifically established.

Frequently Asked Questions

These answers address common implementation decisions and reporting mistakes. The main distinction remains the same: retrieving an inspection record is not the same as running a live test or securing an indexed search result.

Does the URL Inspection API work without Search Console property access?

The API requires appropriate authorization for the property being inspected. A valid Google Cloud project and OAuth token do not grant universal access to websites. The authorized identity must have suitable Search Console property access. Check the exact property identifier and permissions before troubleshooting the URL itself.

Can the URL Inspection API test a page live?

No. The endpoint retrieves Google's stored indexed-version information. It does not expose the interactive Live Test available in Search Console. If a page changed recently, use an appropriate current-page test to assess the correction. A later indexed report is needed to assess Google's updated stored state.

What does a successful API call prove?

It proves that the request returned an API result. It does not prove that the URL is indexed, ranks for a search query, or has been crawled again. Read the indexing verdict, coverage details, and other returned fields. Keep the API's HTTP result separate from the page's recorded condition.

How many URLs can one site inspect per day?

Google's documented per-site limit is 2,000 URL Inspection API requests per day. A single inspection normally uses one request for one URL. Other quota limits and existing consumption still apply. Check the current official limits before scheduling large or repeat audits.

Can I request indexing through this API?

No. The URL Inspection API does not submit general indexing requests. Search Console offers a separate manual request feature. Google's Indexing API is another service with narrower eligible content categories. Do not describe an inspection endpoint call as an indexing submission or a guarantee of Google visibility.

Why are fields missing from my response?

Some inspection fields are conditional. Google may not supply a last crawl date, canonical value, sitemap reference, or rich-result details for every URL. A missing field is not automatically a failed inspection or a healthy page. Preserve its absence in the export and use other evidence for the next decision.

Can I inspect thousands of URLs in one request?

The documented URL Inspection method takes an individual inspectionUrl in its request. A bulk application can queue many calls, but it must obey the relevant site and project quotas. Do not borrow batching rules from Google's separate Indexing API. Plan capacity before promising full audit coverage.

Is the URL Inspection API free to use?

The verified documentation establishes authorization needs and published request quotas, but it does not support an unconditional pricing guarantee here. Review current Google Cloud and API billing terms for your specific project before deployment. Do not treat a quota allowance as proof that all related infrastructure or usage has no cost.

Next Step: Build a Small, Auditable Integration

Start with a few URLs from a Search Console property you can access. Confirm OAuth authorization, the exact siteUrl, and the request body. Save complete responses before building filters, alerts, or dashboards.

Then create a report that keeps Google's recorded fields, your inspection dates, and your own triage labels separate. Test how the application handles missing values, authorization failures, and quota limits. A small, sound integration provides a better base than a large batch with unreliable results.

For wider monitoring, schedule checks by URL priority and available quota. Give unresolved findings a specific next action. Use current-page tests where the stored report cannot answer a technical question.

The goal is not to produce the highest possible request count. It is to build an inspection record that helps developers and SEO teams make sound decisions without confusing API access, technical eligibility, and indexing outcomes.