Build a dataset

A dataset holds examples whose answers you know. Evaluations and fine-tuning read from it. This request makes a tiny format example with two distinct contexts:

from sqwishai import OneHot

refund = {"id": "refund", "kind": "binary", "question": "Is a refund requested?"}

client = OneHot()
dataset = client.datasets.create("Refund format example", [
    {"context": "Please refund the duplicate charge on order 4471.",
     "decisions": [refund], "targets": {"refund": {"yes": 1, "no": 0}}},
    {"context": "Where is the parcel for order 2280?",
     "decisions": [refund], "targets": {"refund": {"yes": 0, "no": 1}}},
], idempotency_key="refund-format-example-v1")

import { OneHot, type Decision } from "sqwishai";

const refund: Decision = { id: "refund", kind: "binary", question: "Is a refund requested?" };

const client = new OneHot();
const dataset = await client.datasets.create("Refund format example", [
  { context: "Please refund the duplicate charge on order 4471.",
    decisions: [refund], targets: { refund: { yes: 1, no: 0 } } },
  { context: "Where is the parcel for order 2280?",
    decisions: [refund], targets: { refund: { yes: 0, no: 1 } } },
], { idempotencyKey: "refund-format-example-v1" });

curl --fail-with-body https://api.sqwish.ai/v1/datasets \
  -H "Authorization: Bearer $SQWISH_API_KEY" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: refund-format-example-v1' \
  --data-binary @- <<'JSON'
{
  "name": "Refund format example",
  "examples": [
    {"context":"Please refund the duplicate charge on order 4471.",
     "decisions":[{"id":"refund","kind":"binary","question":"Is a refund requested?"}],
     "targets":{"refund":{"yes":1,"no":0}}},
    {"context":"Where is the parcel for order 2280?",
     "decisions":[{"id":"refund","kind":"binary","question":"Is a refund requested?"}],
     "targets":{"refund":{"yes":0,"no":1}}}
  ]
}
JSON

Save the returned dataset id. Then inspect rows, contexts, duplicates_removed, method and sha256. Two rows show the format, but they are not enough for a useful evaluation or fine-tune. Choose a different idempotency key for your next dataset.

Expected answers and outcome scores

Each row has a context and decisions, plus one of these fields:

Field	Gives each labelled decision
`targets`, expected answers	A probability distribution over every outcome. A one-hot label encodes a single reviewed outcome. A soft label can encode disagreement
`rewards`, outcome scores	A score from -100 to 100 for every outcome, for `method: "reward"` fine-tuning

A dataset uses one of them throughout.
Rows must not carry model or fallback. A fine-tune or an evaluation names its model.
Rows must not carry action policy fields, such as weights, costs or abstention. Those policies belong to inference.
A training dataset needs at least two distinct contexts, so that a held-out split is possible.
Identical examples are deduplicated.
Two rows that label one decision about one context differently are rejected with conflicting_labels. They are not averaged.

Decision IDs

Within a dataset, a decision ID names one decision. Every row that asks it must give the same kind, question and rubric. It must also give the same outcomes, in the same order, with the same descriptions. Repeating a decision unchanged is fine. A row that defines an ID another way is rejected with conflicting_decision. The message names both rows, by JSONL line for an upload. Give a different question its own ID.

Choose the evaluation set

Some contexts are held out to evaluate models, and never train them. You choose them in one of two ways:

Send the rows as examples. A hash of each context picks its side.
Send training and evaluation. Each row takes the side of its part.

One request uses one mode. The console offers the same choice.

You send	The dataset
`examples`, with `evaluation_fraction` from `0.1` to below `1`. It is `0.2` by default	Mixed. It needs at least two distinct contexts, and keeps at least one on each side
`training` and `evaluation`	Mixed, on your split. A context in both parts is refused with `side_conflict`. The dataset’s `evaluation_fraction` is the share of contexts you put in evaluation
`examples` with `evaluation_fraction` `1`, or `evaluation` alone	Evaluation only. Every valid row is evaluated, and one context is enough. Fine-tuning needs training rows, so it can’t use it

training without evaluation is refused with insufficient_contexts.
A row never names its side. A row with side is refused. The code is invalid_request in a JSON body, and invalid_example in a file.
The fraction applies to groups of distinct contexts. Related examples stay together, so the actual share of examples can differ. The response’s split gives the actual train_rows and evaluation_rows.

The split is fixed across evaluations, training jobs and worker recovery. Changing a training seed doesn’t change it. Rows you add later keep each context on its side (add rows). The dataset’s evaluation_fraction says how its first version was split. Rows you add later have their own share. To choose another split, create another dataset. To score models on the evaluation rows, see Compare models.

Send files

For larger sets, save one example per line and send the file as a form:

refunds = client.datasets.create("Refunds", "examples.jsonl", evaluation_fraction=0.2,
                                 idempotency_key="refunds-upload-v1")

import { readFile } from "node:fs/promises";

const refunds = await client.datasets.create("Refunds", await readFile("examples.jsonl", "utf8"),
  { evaluationFraction: 0.2, idempotencyKey: "refunds-upload-v1" });

curl --fail-with-body https://api.sqwish.ai/v1/datasets \
  -H "Authorization: Bearer $SQWISH_API_KEY" -H 'Idempotency-Key: refunds-upload-v1' \
  -F name=Refunds -F evaluation_fraction=0.2 -F examples=@examples.jsonl

To choose the evaluation rows yourself, send -F training=@training.jsonl -F evaluation=@evaluation.jsonl in place of examples and evaluation_fraction. The clients take them as training= and evaluation= in Python, and { training, evaluation } in TypeScript.

Limit	Size	Over it
A JSON body	1 MiB	`413 request_too_large`
A form	Your tier’s `upload_bytes`. `/v1/onehot` gives it as `dataset_bytes` in `limits` (tiers)	`413 request_too_large`, naming the tier that takes it
A dataset, across its versions	100,000 rows. `/v1/onehot` gives it as `dataset_rows` in `limits`	`413 too_many_rows`

Keep the files and their operation key for retries. The dataset’s input records the body’s format, json or multipart, with its byte count and its hash. The dataset’s hash identifies its validated content.

Upload errors

Error	Why
`invalid_multipart`	A part has a name other than `name`, `examples`, `training`, `evaluation`, `evaluation_fraction`, `max_price_usd` or `allow_new_decision_ids`. Or a part comes twice. A part from that list that the route doesn’t take, such as `name` when adding rows, gets `invalid_request`
`invalid_example`	A line isn’t a valid example. The message names the part and the line, such as `Training line 12`
`no_rows`	A file holds no rows. Leave out a part you have no rows for
`413 too_many_rows`, `too_many_lines`	The files have more than 100,000 rows, or too many blank lines
`413 request_too_large`	The form is over your tier’s `upload_bytes`
`410 route_gone`	The request went to `/v1/datasets/upload` or `/v1/datasets/{dataset_id}/versions/upload`. Send the file as the `examples` part instead

Inspect the saved rows

Request	Returns
`GET /v1/datasets/{dataset_id}/rows`	A page of rows. Add `partition=training` or `partition=evaluation` for one partition. Pagination and `total` then apply to it
`GET /v1/datasets/{dataset_id}/download?partition=training`	One side’s validated JSONL, `training` or `evaluation`. The file is named after the dataset, its version and the side, such as `refunds-v2-train.jsonl`

A version is the whole dataset at that point, so both files name it. The rows name no side, so the two files go back up as training and evaluation. Downloads are rate limited separately.

Add rows

A dataset grows in versions. Add rows, in either mode, to make its next version:

refunds = client.datasets.add_rows("ds_...", "more.jsonl", idempotency_key="refunds-more-v1")

const added = await client.datasets.addRows("ds_...", await readFile("more.jsonl", "utf8"),
  { idempotencyKey: "refunds-more-v1" });

curl --fail-with-body https://api.sqwish.ai/v1/datasets/ds_.../versions \
  -H "Authorization: Bearer $SQWISH_API_KEY" -H 'Idempotency-Key: refunds-more-v1' \
  -F examples=@more.jsonl

A JSON body takes the same fields: {"examples": [...]}, or {"training": [...], "evaluation": [...]}. Either part may be left out. The response is the dataset, with its new version, rows and split. You don’t need to know every decision ID when you start a dataset. Set allow_new_decision_ids to true, and an add may ask decisions the dataset doesn’t ask yet. Later adds then ask them as the dataset’s own. With examples, evaluation_fraction is the share of the new contexts held out for evaluation. It goes from 0.1 to 1, as a field or a form part. It is 0.2 when left out, whatever share the dataset was made with. So each add splits about 80/20 unless you choose otherwise.

Rule	Otherwise
Added rows ask the dataset’s own decisions, worded exactly as it words them. To ask another decision too, set `allow_new_decision_ids` to `true`, as a field or a form part. A decision the dataset already asks must still be worded its way	`task_mismatch`
They use the dataset’s supervision: expected answers or outcome scores	`supervision_mismatch`
A row that labels a decision about a context the dataset already labels gives the same label	`conflicting_labels`
A context the dataset holds goes in the part of its side	`side_conflict`
An evaluation-only dataset takes no `training` rows, and no `evaluation_fraction` below `1`. Every row it gets is evaluated	`evaluation_only`
At least one row is new	`no_new_rows`
The dataset stays within 100,000 rows	`413 too_many_rows`
No other version was added while yours was read. Send it again	`409 dataset_changed`

How added rows are split

A row the dataset already holds is left out, and counted in duplicates_removed.
A row whose decisions come in another order is another row.
A context the dataset holds keeps its side of the split. So an evaluation row is never trained on.
A new context sent as training or evaluation takes that side.
For a new context sent in examples, a hash of the context picks its side, at the add’s evaluation_fraction.
Either way, its side is decided when it is added, and never moves.

Earlier versions never change. Fine-tunes and evaluations keep to the version they read. Each family that grows on the dataset can then continue on the new version, however many families share it. To compare models on the new version, start new evaluations (what is reused). GET /v1/datasets/{dataset_id}/versions lists the versions, newest first, with the rows each added. To read an earlier version, add version=N to /rows or /download.

Storage

Rows that take a dataset past pricing.dataset_free_rows examples (on GET /v1/onehot) hold its first day of storage. To cap that price, send max_price_usd in the JSON body or as a part of the form (cap a price).

Curate before training

Collect real cases that you have permission to use. Remove identifying data you don’t need. Agree on the labelling rule before you assign labels. Include difficult negatives, rare outcomes and unclear cases. Resolve disagreements, rather than treating a teacher’s answer as ground truth. The split keeps identical contexts together, but it can’t detect every semantic duplicate. Remove near-duplicates yourself, so they don’t leak across the split. Keep a separate evaluation set that represents future traffic. Compare against a simple baseline, such as the majority class.

Rename, delete and restore

A version’s rows never change, and each context keeps its side of the split. Add rows as a new version. Create another dataset when labels or wording change.

Request	Does
`PATCH /v1/datasets/{dataset_id}` with `{"name": "Reviewed support tickets"}`	Renames it. Names are trimmed, can’t be empty, and are at most 120 characters. No other field can change
`DELETE /v1/datasets/{dataset_id}`	Deletes it for good. Delete on the dataset does the same in the console
`POST /v1/datasets/{dataset_id}/restore`	Restores an archived dataset, without copying its data. Restoring is idempotent and scoped to your account. One past the free size holds a new day of storage, capped by `max_price_usd` in the body
`GET /v1/datasets?archived=true`	Lists the archive. `archived=false`, the default, lists the library. Each listing has its own pagination

Delete a dataset

Deleting a dataset removes every version, your original uploads and the copies your fine-tunes kept of its rows. It can’t be undone.

Fine-tuned models and their metrics stay. A family that grows on the dataset keeps answering, but can’t continue (delete a family).
The answer is {"id": "…", "deleted": true}. Deleting again changes nothing.
The dataset is then in no list. Its reads, rows, download, rename and new work return 410 dataset_deleted. So do its fine-tunes’ held-out records.
While a fine-tune, evaluation or accepted prompt-tuning job that reads the dataset is queued, running or cancelling, deleting returns 409 in_use and changes nothing. A job that reads a copy of its rows counts too.
An upload retried with the same Idempotency-Key returns the dataset it made. Once you deleted that dataset, the retry returns 410 dataset_deleted. It never brings the dataset back.

Archived datasets

We archive a dataset ourselves when its next day of storage can’t be held. On a suspension, we archive every dataset that pays for storage (keep warm and storage). An archived dataset keeps its data, results and history. It starts no new work, which gets 409 dataset_archived. Next, label with teacher models, compare models, tune the wording or fine-tune a model.

Get started

Make decisions

Improve accuracy

Use the API

Account and billing

Privacy and security

Integrations