Index of every page on this site: llms.txt
Skip to content

A Search Console Primitive for builders

Tokens, quotas, backfills, and storage come before your first Search Console feature. gscdump runs them for every Site, and your server reads the record through a typed SDK.

Continue with Google Read the SDK docs
pnpm add @gscdump/sdk
MIT licensed, on npm.
server.ts
import { createGscdumpV1Client } from '@gscdump/sdk/v1'
import {
  between, clicks, ctr, date, gsc,
  impressions, position, query,
} from 'gscdump/query'

const gscdump = createGscdumpV1Client({
  credential: () => process.env.GSCDUMP_API_KEY!,
})

const state = gsc
  .select(query, clicks, impressions, ctr, position)
  .where(between(date, '2026-08-22', '2026-09-18'))
  .orderBy(clicks, 'desc')
  .limit(5)
  .getState()

const report = await gscdump.queryAnalyticsReport({
  params: { siteId: process.env.GSCDUMP_SITE_ID! },
  body: { state },
})
report.data.rows
Query Clicks Impressions Position
schema validator37655,9224.6
sitemap validator3712,2712.1
schema checker25514,9964.2
nuxt seo2156,20720.7
sitemap checker1264,6686.6
nuxtseo.com, Aug 22 – Sep 18, 2026, captured Sep 22, 2026. The rows this call returns for that window.

The work between Google's API and your feature

Search Console's API answers one narrow question per call, for one Site, inside a quota. gscdump runs this work for every Site your customers connect.

  • Token refresh. Tokens refresh with your Google OAuth client. A revoked grant stops sync and marks the Site for re-auth.
  • Quotas. Sync runs inside Google's API quotas, with retries and backoff.
  • Backfill. A new Site backfills up to 16 months of available history. Sync then adds each day Google reports.
  • Sitemaps and inspection. Sync reads the sitemaps each Site declares and inspects URLs within Google's daily quota.
  • Isolation. Each user's record lives in a database provisioned for that user alone.
  • Open formats. History stays in Parquet and Iceberg after Google deletes it.

How a partner integration runs

A partner key runs these calls for every customer you connect, in this order.

  1. 1createUser

    Your app signs the customer in with Google and passes the tokens. gscdump provisions their record.

  2. 2createSite

    Register the Site the customer picked. gscdump queues the first sync. Add a webhookUrl to hear back.

  3. 3site.analytics.ready

    A signed webhook arrives when data lands. parseWebhookPayload verifies the signature.

  4. 4queryAnalyticsReport

    Your server reads rows, totals, and sync metadata for that Site.

Request partner access

Operations your server can run

Each Operation publishes its schema, scopes, and errors. User API keys and partner keys share every read.

Analytics

  • queryAnalyticsReport
  • queryAnalyticsReportDetail

Indexing

  • getSiteIndexing
  • listSiteIndexingUrls
  • listSiteIndexingTransitions
  • inspectSiteUrls

Sitemaps

  • getSiteSitemaps
  • getSiteSitemapChanges
  • querySitemapMembership
  • listSitemapUrls

Canned evidence queries

  • getCtrCurve
  • getPositionDistribution
  • getQueryTrend
  • getPageTrend
  • getContentVelocity

Bing, in private preview

  • listSiteBingIndexingEvidence
  • getSiteBingData

Partner key only

  • createUser
  • createTeam
  • addTeamMember
  • createUserApiKey

Generate the OpenAPI and AsyncAPI documents with createGscdumpV1Documents(). Read the hosted HTTP reference

A contract you can build on

  • Versioned. Every response carries GSCdump-API-Version: 1.0. An Operation is removed only after a census shows zero use.
  • Typed errors. Each failure names a code, a requestId, and whether a retry can succeed.
  • Safe retries. The SDK retries idempotent Operations with backoff and honors Retry-After. It never retries a non-idempotent mutation.
  • Framework-neutral. The contracts depend on zod alone. No Nuxt, H3, or Cloudflare code crosses the boundary.
  • Open source. The SDK and its contracts are MIT licensed. Read the source
Error envelope, from the v1 contract
{
  "error": {
    "code": "site_not_found",
    "message": "Site not found",
    "requestId": "req_01",
    "retryable": false,
    "details": {}
  }
}

Nuxt SEO Pro runs on it

Nuxt SEO Pro reads every Site through these public Operations, with no private API. Start from the guide for your server.

Built by Harlan Wilton, maintainer of Nuxt SEO. Agents can use Search Console feedback to shape sites and content. That should not require costly SEO software or months of integration work.

Run the sample on your own Site.

Create a user API key in Agent setup, set your Site ID, and run server.ts.