# Dataset sync

> Read the cited dataset incrementally — cursors, updated_since, per-cell citations


`GET /v1/blueprints/{blueprint_id}/entities/{entity_key}` is the canonical
read: the **cross-run, canonical rows** of one entity, with citations. Entity
keys come from `GET /v1/blueprints/{blueprint_id}`, and the ids from
`GET /v1/blueprints` ([discover, don't
guess](/developers/blueprints-and-data)).

```bash
curl -s "$BASE_URL/v1/blueprints/$BP/entities/companies?limit=50&receipts=true" \
  -H "Authorization: Bearer $DEEPSIEVE_API_KEY"
```

```json-response
{"data": [{"id": "…", "updated_at": "2026-08-03T11:02:44+00:00",
           "name": "Acme KK", "hq_city": "Osaka",
           "citations": {"hq_city": {"value": "Osaka", "confidence": 0.93,
                                     "evidence_id": "…",
                                     "source_urls": ["https://…"],
                                     "retrieved_at": "2026-08-01T…"}}}],
 "has_more": true, "next_cursor": "MjAyNi0wOC0wMy4uLg",
 "entity": {"key": "companies", "columns": [{"name": "name", "type": "text"}]},
 "blueprint": {"domain_name": "…", "entities": ["companies"]}}
```

Parameters:

- `limit` (≤200) + `cursor` — keyset pagination ordered by `(updated_at, id)`
  ascending. Stable while rows are inserted.
- `updated_since=<iso-timestamp>` — **the sync primitive**: only rows changed
  since your last sync. Store your high-water mark (or the final cursor) and
  poll on your own schedule — or let the `dataset.updated` webhook tell you when.
- `fields=name,hq_city` — column subset.
- `receipts=true` — nest per-cell citations. This is the differentiator; use it.

## Reading a citation honestly

Each cell carries the same verdict the app shows, not just a number:

| Field | Meaning |
|---|---|
| `verdict` | `supported` · `leans-supported` · `uncertain` · `corrected` · `contradicted` · `unverifiable` · `not checked` |
| `confidence` | 0–1 float, or `null` when the cell was never graded |
| `cited` | `false` when the cell has no source URL — never present it as sourced |
| `verdict_note` | the QA agent's short justification |
| `source_urls`, `evidence_id`, `retrieved_at` | provenance |

A `contradicted` or `cited: false` cell is a signal to surface to a human, not
a fact to act on.

## Preview caps (unsubscribed workspaces)

Free-preview workspaces receive only the first 10 rows per entity. The response
says so explicitly — `"truncated": true`, `"preview_row_cap": 10`, plus
`has_more: true` — and paging past the cap requires a subscription. **Never
report a truncated preview as the complete dataset.**

## Bulk export

`GET /v1/export?format=ndjson|json|csv[&entity=][&workspace_id=]` — NDJSON is
the agent default: line 1 is a metadata record with the Blueprint schema, then
one record per line with citations. CSV is per-entity and **drops citations**.
`workspace_id` exports a specific Blueprint by id (leaves the active workspace
unchanged); omitted, it exports the active one.

Free-preview (unsubscribed) workspaces are capped to the first rows of each
table on both surfaces — flagged by `truncated` + `preview_row_cap`.