> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verial.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Datasets

> Synthetic data loaded into simulator sandboxes at rollout time.

A **dataset** is the synthetic data that populates a [Sandbox](/guides/concepts/sandboxes) when a [Playground](/guides/concepts/playgrounds) is provisioned. FHIR patient panels, SFTP file manifests, payer rosters: anything an [Environment](/guides/concepts/environments) needs in place before an agent can drive a rollout. You either author dataset contents by hand or ask Verial to generate them from a prompt.

## Two Formats

Datasets come in one of two formats, set via the `type` field.

| Format    | Storage                                                                                        | Typical use                                                                  |
| --------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **FHIR**  | Bundle JSON stored in the `data` / `config` column                                             | Patients, Conditions, Encounters, Appointments, Coverage, Observations, etc. |
| **Files** | Manifest in `config`, actual file bytes in GCS under `datasets/{datasetId}/files/{ulid}.{ext}` | Inbound/outbound fax documents, referral PDFs, SFTP drops, X12 payloads      |

FHIR datasets are synthesized into a FHIR R4 Bundle at provisioning time and loaded into the sandbox's FHIR store. Files datasets are copied into the sandbox's own object storage so the agent can read from and write to the SFTP or fax endpoints.

## How Datasets Attach to Sandboxes

Datasets do not live inside a sandbox directly. They are linked to a sandbox, and the link drives provisioning:

```mermaid theme={null}
graph LR
  D["Dataset<br/>(original, reusable)"]:::input --> L["Link to Sandbox"]:::engine
  L --> B["Branch: child Dataset<br/>(parentId set, config + files copied)"]:::state
  B --> C["Baseline Checkpoint<br/>(snapshot of config)"]:::state
  C --> S["Sandbox operates on child"]:::output

  classDef input fill:#e0f2fe,color:#1e3a5f,stroke:#3b82f6
  classDef state fill:#fef3c7,color:#78350f,stroke:#f59e0b
  classDef engine fill:#2563eb,color:#fff,stroke:#1d4ed8
  classDef output fill:#f0fdf4,color:#166534,stroke:#22c55e
```

When a dataset is linked to a sandbox, Verial creates a **child dataset** (`parentId` points back to the original) with copied config and copied GCS files. The sandbox operates on the child, so anything the agent does (adding a Patient, dropping a fax, updating a prior auth record) stays isolated to that sandbox. The original dataset is preserved and can be reused across many runs.

At branch time Verial also writes a baseline **checkpoint**, a snapshot of the child's config at that moment. Checkpoints give you a known-good state to reset to.

## Creating a Dataset

```typescript theme={null}
const dataset = await verial.datasets.create({
  name: 'Diabetes patient panel',
  description: '50 patients with Type 2 diabetes and pending auths',
})
```

At this point the dataset is a container. Populate it by setting `data` directly, or by asking Verial to generate contents from a prompt.

### Hand-authored contents

```typescript theme={null}
await verial.datasets.update({
  id: dataset.id,
  data: {
    resourceType: 'Bundle',
    type: 'collection',
    entry: [
      { resource: { resourceType: 'Patient', id: 'pt-1', name: [{ family: 'Smith', given: ['John'] }] } },
      // ...
    ],
  },
})
```

### Generated from a prompt

```typescript theme={null}
await verial.datasets.generate({
  id: dataset.id,
  prompt: '10 patients with pending prior auth requests for lumbar MRI',
})
```

## Linking a Dataset to a Sandbox

Datasets are attached to a sandbox via the sandbox API. The link triggers the branch-and-checkpoint flow described above:

```bash theme={null}
curl -X POST "https://api.verial.ai/sandboxes/$SANDBOX_ID/datasets/$DATASET_ID" \
  -H "Authorization: Bearer $VERIAL_API_KEY"
```

You can remove the link later with `DELETE /sandboxes/{id}/datasets/{dataset_id}`. Inside a [benchmark run](/guides/concepts/runs), datasets are linked automatically based on the environment's configuration, so you rarely call these directly during a rollout.

## Scoping Criteria to Specific Entities

A dataset can contain many entities (patients, referrals, auth requests). A [Criterion](/guides/concepts/criteria) can scope itself to one of them via `input_entity_id`, so the same task can be reused across many dataset rows without rewriting assertions.

## Next Steps

<CardGroup cols={2}>
  <Card title="Sandboxes" icon="box" href="/guides/concepts/sandboxes">
    How datasets are loaded into running simulator instances.
  </Card>

  <Card title="Datasets API" icon="code" href="/api-reference/resources/datasets">
    REST endpoints and full object reference.
  </Card>
</CardGroup>