API & integrations

One REST API, and the exports you already use.

Start runs, read results and get a webhook when a run finishes. Or skip the code and send rows to a sheet or a bucket.

REST

Plain HTTPS and JSON.

Every dataset is an endpoint. Start a run with input, poll or wait for a webhook, then page through items.

Bearer token auth, one key per workspace

Cursor pagination, up to 1,000 items a page

Rate limit headers on every response

Idempotency keys for safe retries

BASE

https://api.gristmill.example/v1

1# Placeholder API. Replace with your own.
2curl -X POST \
3  https://api.gristmill.example/v1/datasets/price-watch/runs \
4  -H "Authorization: Bearer $GRISTMILL_TOKEN" \
5  -H "Content-Type: application/json" \
6  -d '{"urls": ["https://shop.example.com/p/123"], "max_items": 100}'

Endpoints

v1 · placeholder

GET

/datasets

List datasets and their schemas

POST

/datasets/{slug}/runs

Start a run with input and limits

GET

/runs/{id}

Run status, counts and cost so far

GET

/runs/{id}/items

Page through results as JSON or CSV

POST

/webhooks

Subscribe a URL to run events

Webhooks

Know the moment a run lands.

We POST a signed JSON event to your URL. Failed deliveries retry with backoff for 24 hours.

run.succeeded

Items are ready to read

run.failed

With the error and the pages affected

dataset.schema_changed

Sent before a field is added

POST https://your-app.example/hooks/gristmill

1{
2  "type": "run.succeeded",
3  "created_at": "2026-10-24T09:12:03Z",
4  "data": {
5    "run_id": "run_7Hc2Qm9x",
6    "dataset": "price-watch",
7    "items": 1840,
8    "billable_items": 1832,
9    "items_url": "https://api.gristmill.example/v1/runs/run_7Hc2Qm9x/items"
10  }
11}

Header: Gristmill-Signature: t=…, v1=… (HMAC SHA-256)

SDKs

Typed clients, thin on purpose.

Each SDK wraps the same REST calls with retries and pagination. Package names below are placeholders.

Node / TypeScript

Async iterators for items, typed schemas per dataset.

$ npm install @gristmill/sdk

Python

Sync and async clients, pandas helper for DataFrames.

$ pip install gristmill

Go

Context-aware client, streaming item reader.

$ go get gristmill.example/go

Exports

Send rows where they get used.

Pick a destination per dataset. Every run writes there automatically.

.csv

CSV

Download from a run or a stable URL that always holds the latest run.

.json

JSON & JSONL

Nested fields kept intact. JSONL for streaming large runs.

Sheets

Google Sheets

Append or replace a tab after each run. Good for small teams.

s3://

Amazon S3

Write to your bucket with a path template and your own credentials.

Also works with

Zapier

Make

n8n

Airtable

BigQuery

Snowflake

PostgreSQL

Slack

Google Drive

Azure Blob

Names are listed as text examples of where webhooks and exports can go. They are trademarks of their owners; no partnership is implied.

Get a sandbox key in a minute.

1k free results a month. No card.

Get API key

Browse datasets