Linking Sanity as a source

The Sanity connector imports content documents and asset metadata from a Sanity dataset into the PostHog data warehouse. Sanity is a headless CMS that stores structured content as typed documents. This connector creates one table per document type in your schema, plus tables for image and file asset metadata.

Drafts and release versions are included in every sync.

Prerequisites

You need a Sanity project with a dataset and an API token that has read access. Robot tokens are recommended, but personal tokens also work.

Adding a data source

1. In PostHog, go to the Sources tab of the data pipeline section.
2. Click + New source and click Link next to this source.
3. Enter your credentials (see Configuration below) and click Next.
4. Select the tables you want to sync, choose a sync method and frequency, then click Import.

Once the syncs are complete, you can start querying this data in PostHog.

When linking Sanity, you'll need:

• Project ID — found in your Sanity project settings.
• Dataset — the name of the dataset to import (e.g., production).
• API token — a robot token or personal token with read (Viewer) permissions.

To get these:

1. Log in to Sanity and go to sanity.io/manage.
2. Select your project. The Project ID is shown at the top of the project page.
3. Note the Dataset name you want to import (visible under the Datasets tab).
4. Go to the API tab → Tokens.
5. Click Add API token, give it a name, and select Viewer permissions.
6. Copy the token value — you won't be able to see it again.
7. Paste the Project ID, Dataset, and API token into PostHog.

Sync modes

Each table can be synced in one of several modes, depending on what the source supports:

• Webhook (when available) – the source pushes changes to PostHog in real time. Fastest freshness, lowest ongoing cost, and the only mode that reliably captures updates and deletes.
• Incremental – only new or updated rows are synced on each run, using a cursor field (such as an updated_at timestamp). Cheaper than a full refresh, but deletes aren't captured.
• Append only – new rows are appended using a cursor field; existing rows are never updated. Ideal for immutable, append-only tables like event logs.
• Full refresh – the whole table is reloaded on every sync. Use it when a table has no reliable cursor or when you need deletions reflected.

See sync methods for a full explanation of how each mode works and how to choose between them.

All Sanity tables support incremental sync on the _updatedAt field. How deleted documents are handled depends on the sync mode:

• Full refresh removes deleted documents. Each sync replaces the table contents.
• Incremental sync imports new and updated documents but does not remove deleted documents. Deleted documents remain until the next full refresh.

Configuration

Supported tables

The tables available from this source are discovered from your account when you connect it, so the exact list depends on your data. Once connected, you can pick which tables to sync from the sources tab.

Tables are created dynamically based on the document types in your Sanity schema. For example, if your schema has post, author, and category types, a table is created for each.

Two built-in tables are always available:

• sanity.imageAsset — image metadata (dimensions, URLs, format, etc.)
• sanity.fileAsset — file metadata (URLs, size, format, etc.)

Asset binaries are not imported — only metadata.

Troubleshooting

• 401 — Invalid API token: Sanity rejected the API token. Replace the token and reconnect the source.
• 403 — Insufficient permissions: The Sanity token cannot read this dataset. Give the token read access (Viewer role) and reconnect.
• 404 — Project or dataset not found: The Sanity project or dataset does not exist. Check the Project ID and Dataset in the source settings.
• 410 — API version no longer supported: Sanity no longer supports this API version. Update the source API version.

If your sync is failing or data looks wrong, see the Data warehouse troubleshooting guide. If that doesn't help, contact support – we're happy to help.