gsc

Ask for a client PDF of a site's Search figures

Ask for a client PDF of one site's Search figures: a finished month (month) or a range of finished Pacific days (start, end), with the sections chosen, branded with the workspace's name and logo. Every figure reads final days only. The answer is the PDF with its state: queued or building, waiting (a prerequisite that can return, with its sentence and next_try_at), ready, failed or invalidated. An identical request answers the existing PDF rather than making a second. Nothing is sent to anyone. Paid (reports, and ga4, audit_joins, index or alerts for those sections): BILLING_REQUIRED on a site without them. Next: call gsc_pdfs_get until it is ready; a ready PDF carries its download link.

post/v1/sites/{site}/search/pdfs

Request

  • Base URL: https://frontshelf.io/api
  • URL: https://frontshelf.io/api/v1/sites/{site}/search/pdfs
  • Auth: HTTP bearer

Path parameters

sitestring required

Site ID (site_…), origin (https://example.com), or bare domain, resolved server-side; the response carries the canonical ID.

Request body

monthstring

A finished calendar month, YYYY-MM (Pacific days). Give month, or start and end, never both.

startstring

With end: the first day of a range of finished Pacific days, YYYY-MM-DD.

endstring

With start: the last day of the range.

sectionsstring[]

The sections, each one or two pages: summary (always: clicks, impressions, CTR and position against the period before and a year earlier, the chart), movers (the queries and pages whose clicks rose and fell most), groups (page groups and keyword clusters), notes (notes and Google updates with their verdicts), indexing, audit (the newest crawl's scores and its ten issues with the most clicks), analytics (Google Analytics organic and both AI figures), alerts (the falls alerted in the period). Default: summary, movers, groups, notes, audit.

dry_runboolean

true: check the call and say what it would do, without doing it.

confirmboolean

true: go ahead with a change that asks for confirmation.

Response

Ask for a client PDF of a site's Search figures

summarystring required

The answer in one or two sentences, with the numbers it rests on.

warningsstring[] required

What limits this answer (a cap, a read that was cut short). Empty when nothing does.

idstring required

The PDF's id (spdf_…): what gsc_pdfs_get takes.

site_idstring required

The site's canonical id.

sectionsstring[] required
state'queued' | 'building' | 'waiting' | 'ready' | 'failed' | 'invalidated' required

queued or building (the renderer makes it), waiting (a prerequisite that can return), ready, failed, or invalidated (withdrawn: data it held was erased).

reason'no_blob_store' | 'not_final' | 'not_connected' | 'gated' | 'render_failed' | 'store_failed' | 'expired' | 'source_erased' | 'analytics_erased'

Why it waits, failed or was withdrawn.

next_try_atstring

A waiting PDF: when Frontshelf tries again.

ready_atstring

An instant, ISO 8601.

bytesinteger

A ready PDF's size.

atstring

A withdrawn PDF: when it was withdrawn.

sentencestring nullable required

The state in words: what a waiting PDF waits for and when it tries again, why one failed, when and why one was withdrawn; null for queued, building and ready.

download_urlstring nullable required

A ready PDF's signed download link, good for 15 minutes with no Authorization header; null in every other state. A secret: hand it to your human, never anywhere else.

Changes

No recorded changes to this operation across all 1 revision of this API.