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.
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 }, })
| Query | Clicks | Impressions | Position |
|---|---|---|---|
| schema validator | 376 | 55,922 | 4.6 |
| sitemap validator | 371 | 2,271 | 2.1 |
| schema checker | 255 | 14,996 | 4.2 |
| nuxt seo | 215 | 6,207 | 20.7 |
| sitemap checker | 126 | 4,668 | 6.6 |
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
createUserYour app signs the customer in with Google and passes the tokens. gscdump provisions their record.
- 2
createSiteRegister the Site the customer picked. gscdump queues the first sync. Add a
webhookUrlto hear back. - 3
site.analytics.readyA signed webhook arrives when data lands.
parseWebhookPayloadverifies the signature. - 4
queryAnalyticsReportYour server reads rows, totals, and sync metadata for that Site.
- Browsers. A single-use realtime ticket brings change notices. The browser then re-reads over HTTP. Read the realtime guide
- Your own Sites. A user API key runs the same reads without a partner key. Compare the keys
Operations your server can run
Each Operation publishes its schema, scopes, and errors. User API keys and partner keys share every read.
Analytics
queryAnalyticsReportqueryAnalyticsReportDetail
Indexing
getSiteIndexinglistSiteIndexingUrlslistSiteIndexingTransitionsinspectSiteUrls
Sitemaps
getSiteSitemapsgetSiteSitemapChangesquerySitemapMembershiplistSitemapUrls
Canned evidence queries
getCtrCurvegetPositionDistributiongetQueryTrendgetPageTrendgetContentVelocity
Bing, in private preview
listSiteBingIndexingEvidencegetSiteBingData
Partner key only
createUsercreateTeamaddTeamMembercreateUserApiKey
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, arequestId, 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": { "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.