---
title: "Builders · gscdump"
canonical_url: "https://gscdump.com/builders"
last_updated: "2026-10-03T07:15:30.502Z"
meta:
  description: "Add Google Search Console data to your product. gscdump syncs each Site and keeps its history; your server reads it through a typed SDK."
  "og:description": "Add Google Search Console data to your product. gscdump syncs each Site and keeps its history; your server reads it through a typed SDK."
  "og:title": "Builders · gscdump"
---

# 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.

[**Join the waitlist **](https://gscdump.com/#get-access) [**Read the SDK docs **](https://gscdump.com/gscdump-sdk)or

```
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 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 |

*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. 1 `createUser`

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

   Register the Site the customer picked. gscdump queues the first sync. Add a `webhookUrl` to hear back.
3. 3 `site.analytics.ready`

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

   Your 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](https://gscdump.com/gscdump-sdk/guides/build-integrations/realtime)
- **Your own Sites.** A user API key runs the same reads without a partner key. [Compare the keys](https://gscdump.com/gscdump-sdk/guides/operate/keys-and-scopes)

[**Request partner access **](mailto:hello@gscdump.com?subject=Partner%20access)

## 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](https://gscdump.com/gscdump-sdk/api/hosted-http)

## 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](https://github.com/harlan-zw/gscdump/tree/main/packages/sdk)

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](https://nuxtseo.com) reads every Site through these public Operations, with no private API. Start from the guide for your server.

- [Nuxt ](https://gscdump.com/gscdump-sdk/guides/build-integrations/nuxt)
- [Next.js ](https://gscdump.com/gscdump-sdk/guides/build-integrations/nextjs)
- [Hono ](https://gscdump.com/gscdump-sdk/guides/build-integrations/hono-express)
- [Express ](https://gscdump.com/gscdump-sdk/guides/build-integrations/hono-express)

**Built by Harlan Wilton, maintainer of [Nuxt SEO](https://nuxtseo.com).** 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.

Signups open gradually during beta. Leave your email on the home page and an invite follows when a slot opens.

[**Join the waitlist **](https://gscdump.com/#get-access) [**Request partner access **](mailto:hello@gscdump.com?subject=Partner%20access)

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.