Conventions

These rules hold across the whole surface. Learning them once saves reading 217 operation descriptions.

Path shape

Workspace and domain are always path segments, in the same position:

/api/public/v1/workspaces
/api/public/v1/workspaces/{workspace_id}
/api/public/v1/domains
/api/public/v1/domains/{domain_id}
/api/public/v1/domains/{domain_id}/uptime/timeline
/api/public/v1/domains/{domain_id}/gsc/performance

Search Console hangs off the domain its property is linked to, rather than exposing an internal property identifier.

The dashboard's own API accumulated several path-shape inconsistencies over the years. None of them is inherited here: a frozen public contract is the wrong place to preserve drift.

Pagination

Two forms. Check which one an endpoint uses before you write the loop, because they are not interchangeable.

Cursor, on 26 endpoints

The default, and the one to expect on anything reading a continuously-inserted table. LIMIT 100 OFFSET 200 silently returns duplicate and skipped rows there as new data lands between page fetches, and both pages look well-formed, so a client has no way to notice.

{
  "items": [ ... ],
  "next_cursor": "eyJ0IjoxNzUw...",
  "has_more": true,
  "total": null
}

limit defaults to 50 and clamps at 1000. It clamps rather than rejects, so an agent asking for 5,000 rows gets 1,000 back with an accurate has_more, rather than a 400 in the middle of a paging loop.

A few endpoints clamp lower than 1000, because they delegate to an internal handler with a tighter ceiling of its own. /rum/pages and /rum/pageviews cap at 500. Others cap at 500 or 100. Check the OpenAPI document for the maximum on the endpoint you are calling before you hard-code a page size, rather than assuming 1000 everywhere. Both RUM endpoints above used to advertise 1000 and then answer 400 when you asked for it; the published maximum is now the one the endpoint actually honors.

A correct loop:

cursor = None
while True:
    page = get("/domains/{id}/robots/changes", cursor=cursor, limit=200)
    for row in page["items"]:
        handle(row)
    if not page["has_more"]:
        break
    cursor = page["next_cursor"]

Offset, on 8 endpoints

Search Console and a few analytics reads page by limit and offset instead, because they sit on a stable stored result rather than a live insert stream. They return an exact total (total_pages, total_queries) rather than has_more, and there is no cursor to pass back:

GET /domains/{domain_id}/gsc/queries
GET /domains/{domain_id}/gsc/pages
GET /domains/{domain_id}/gsc/countries
GET /domains/{domain_id}/gsc/new-rankings
GET /domains/{domain_id}/gsc/reports/runs/{run_id}/rows
GET /domains/{domain_id}/analytics/pages
GET /domains/{domain_id}/analytics/ecommerce/products
GET /domains/{domain_id}/analytics/reports/runs/{run_id}/rows

A client that assumes a cursor everywhere will loop forever on these, because next_cursor never appears. Branch on which fields come back, or check the OpenAPI document per endpoint.

Time ranges

Four forms, depending on the endpoint:

Defaults differ per endpoint and are worth reading rather than assuming. Search Console endpoints default end_date to two days ago, not today, because Google's own data lags roughly that far. Ask for yesterday there and you will correctly get nothing.

The OpenAPI document is authoritative per endpoint, and this is the parameter set most worth checking there before writing a query.

A range that predates your plan's data retention is clamped, not rejected. The response reports meta.clamped_from when that happens, so a client charting "last 12 months" on a three-month plan sees why the chart is short, instead of reading nine months of flat zero as a traffic collapse. Check for that field before you draw a conclusion from a long window.

Named periods

Nineteen endpoints accept period, which names a reporting window instead of asking you to calculate its edges. Seven values are accepted:

last_month is the last complete calendar month, not the trailing 30 days. Those are two different questions with two different answers, and the gap is large enough to change a conversation: on one monitored domain the trailing 30 days read 96.74% uptime while the calendar month of July read 98.89%. A report headed "last month" that quietly sends a trailing 30-day window is wrong by that much.

Trailing windows remain the default on every endpoint, so a named period is opt-in. A client that never sends one behaves exactly as it did before.

period cannot be combined with start_date or end_date. Sending both is a 400, not a precedence rule, because silently picking one of two windows the caller asked for is how a report ends up covering days nobody chose.

The resolved boundaries are always echoed in the response, so you can label a chart with the days that were actually counted rather than with the name you sent.

Comparing against a previous window

Four endpoints pair compare_previous=true with compare_mode, which decides what "previous" means:

Omit compare_mode and it resolves to calendar_month when period named a calendar month (this_month or last_month), and to previous_period otherwise. That default is what people mean by "compared to last month": the baseline for a calendar month is the previous calendar month, not an equal-length run of days that is not a month at all.

compare_mode exists on /analytics/overview, /gsc/overview, /gsc/pages, and /uptime/availability, and nowhere else. Other endpoints that accept compare_previous, such as /gsc/queries, /rum/overview, and /rum/pages, always compare against the immediately preceding window of equal length.

Idempotency keys are mandatory on run: endpoints

Every run:-class endpoint requires an Idempotency-Key header. This is not optional polish:

curl -sS -X POST \
  "https://app.vitalsentinel.com/api/public/v1/domains/$DOMAIN_ID/reports/$TEMPLATE_ID/generate" \
  -H "Authorization: Bearer $VITALSENTINEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: report-$(echo -n "$TEMPLATE_ID$BODY" | shasum -a 256 | cut -c1-32)" \
  -d "$BODY"

One write:-class endpoint has the same requirement: POST /domains/{domain_id}/robots/sitemap-conflicts/recompute is write:robots-scoped rather than run:, and still rejects a call that arrives without a key, because a retry would otherwise queue a second recompute of the same domain.

This matters most for automated callers. Agents and job runners retry aggressively, on a timeout, on a transport hiccup, or on their own uncertainty about whether a call succeeded. Without an idempotency key, one retried report run is billed a second time and the customer sees a credit balance they cannot account for.

A POST does not always mean a mutation

A handful of endpoints are POSTs that take a body and change nothing. They exist because the input does not fit in a query string: a batch of URLs to test, a candidate robots.txt to simulate.

They are recognizable three ways: they live under a /query-style sub-path, they require only a read: scope, and their OpenAPI description says so explicitly.

POST /domains/{domain_id}/robots/test-urls/query
POST /domains/{domain_id}/robots/simulate/query
POST /domains/{domain_id}/robots/overlapping-rules/query
POST /domains/{domain_id}/reports/data/{template_id}

None of these needs an Idempotency-Key, and none of them costs a dispatch price.

Response headers

Every response carries these:

Null is not zero

Reading a response means telling three states apart: measured and genuinely zero, not measured, and not measurable. The API keeps them separate rather than flattening them all to 0, because a fabricated zero charts identically to a real one.

• A metric an endpoint did not measure is null, never 0. GET /analytics/pages?type=entry reports entry data, so exits and the bounce fields come back null there rather than as zeros you might plot. The same applies to entries under type=exit and to chain_valid on a domain that was never scanned.
• A percentage change with nothing to compare against is null, not a fabricated 100.0 or 0.0. That covers visitors_change_pct and its siblings on /analytics/overview, revenue_change and orders_change on /analytics/ecommerce/overview, and actual_ctr on /gsc/ctr-benchmark. bounce_rate_change_pp is the exception: a percentage-point difference is always defined, so it stays a plain number that is always present.
• A zero the endpoint could not have counted is absent, not 0. GET /uptime/incidents fetches at most the 2,000 most recent incidents, so it zero-fills class_counts only when window_truncated is false. A missing key means unknown. A present 0 means genuinely none.
• A date on which nothing was recorded is null, not a placeholder like 1970-01-01.

RUM is stricter here than the dashboard

Every RUM response on the public API is redacted unconditionally. There is no scope that widens this, and no plan that changes it.

If you are wondering why the API hides a query string your dashboard shows you, this is why. The query string is where personal data hides in a real-user error URL, and an API credential could extract it at a scale a human browsing the dashboard cannot. This is a deliberate difference, not an oversight to be reconciled later by loosening the API.

Aggregate and page-level RUM metrics are unaffected. Everything you need to rank pages by 75th-percentile LCP, break down INP subparts, or count error groups is still there.

An explicit end_date now ends the window

A public RUM route given an explicit end_date used to include the following day's events. It inherited a whole-day pad from the dashboard handler underneath it, so end_date=2026-07-31 genuinely counted events from August 1. That is fixed. The window ends where end_date says it ends, and window_end on the response states the exact window that was queried, so you can confirm it rather than infer it.

The dashboard still pads, deliberately and unchanged. A dashboard figure and an API figure quoting the same end_date can therefore differ by one day of traffic, and the API is the one reporting the window you asked for. If you have a stored RUM total from before this change, it covered one more day than its label claimed.

Kill switches are not deprecations

Two 503 responses are operational levers rather than contract changes:

Neither means an endpoint is going away. See Versioning and stability for what an actual retirement looks like.

Five habits that keep a client working

The compatibility promise is written against clients that do these five things. A client that does not is not covered:

1. Ignore unknown fields. New fields ship inside v1 without a version bump.
2. Tolerate unknown enum values. New enum members are additive.
3. Branch on the error type URI, never on the prose in detail.
4. Treat cursors as opaque.
5. Honor Retry-After.