Generate a dataset from scratch

datasets.invent() -> DatasetInventResponse

POST/api/v1/datasets/invent

Creates a dataset and starts generating it from your domain selections. Returns immediately — poll GET /datasets/{id} for the status and GET /datasets/{id}/download once it reports succeeded. Set Set estimate: true to price a request without generating anything.

ParametersExpand Collapse

name: Optional[str]

Display name for the invented dataset.

training_type: Optional[Literal["instruction_dataset", "preference_pairs"]]

Shape of the generated data — the same field and values as datasets.run. instruction_dataset produces prompt/completion rows; preference_pairs produces ranked completion pairs. Note this is the shape of the DATA, not the training method (elsewhere training_type means LoRA vs full fine-tuning). Defaults to instruction_dataset. The download carries the generated text in enhanced_prompt / enhanced_completion; original_* are null, since invented data has no source rows it was derived from.

One of the following:

"instruction_dataset"

"preference_pairs"

domains: Optional[Sequence[str]]

Domain codes to generate from, e.g. medical. Supply at least one of domains or subdomains — omit this and the domains are inferred from the parents of your subdomains. When you do supply it, it is authoritative: a subdomain naming a domain that is not listed here is rejected rather than silently added. Retrieve the valid codes from GET /datasets/invent/domains.

subdomains: Optional[Sequence[str]]

Narrow generation to specific subdomains, as domain.subdomain codes e.g. medical.symptoms_diagnosis. Qualified by their domain because a bare code can belong to more than one (wildlife sits under both agriculture and animal nature). Requested domains with no subdomain listed here are generated across all of theirs. Supply at least one of domains or subdomains. Retrieve the valid codes from GET /datasets/invent/domains.

rows: int

Number of rows to generate, subject to your plan’s per-launch row cap. Treat it as a target: the delivered count can land slightly either side of it, so read row_count on the finished dataset for what was actually produced.

minimum1

language_expansion: Optional[LanguageExpansion]

Optionally translate or localize the generated rows into further languages. Credits are billed on the POST-expansion row count, so setting this quotes and charges above rows. sample_rate (0-1) is the share of rows expanded.

type: Literal["translate", "localize"]

Expansion mode. translate produces one new row variant per target language; localize produces one new row variant per country/language pair.

One of the following:

"translate"

"localize"

languages: Optional[Sequence[str]]

Target ISO 639-1 language codes (required when type=translate, forbidden when type=localize). Validated against the supported language list at request time; unknown values return 400 with a sample of supported codes.

pairs: Optional[Iterable[LanguageExpansionPair]]

Country/language pairs (required when type=localize, forbidden when type=translate). Each pair is validated against the supported country/language pair list at request time.

country: str

ISO 3166-1 alpha-2 country code.

language: str

ISO 639-1 language code.

sample_rate: float

Fraction (0.01–1) of input rows that are expanded per target. Output rows ≈ input × (1 + sample_rate × target_count). Required. Credits are billed on the expanded output row count.

minimum0.01

maximum1

prompt: Optional[str]

Free-text description of the data you want, in your own words — the wizard shows this as “Dataset Details”. Drives the semantic search that selects rows, so a specific prompt yields more relevant data, and it is woven into the generation instructions. Written for you from your domain selections when omitted.

maxLength10000

estimate: Optional[bool]

Price the request without creating or charging anything. Mirrors datasets.run — the response carries the same fields either way, with the dataset fields null when this is set.

idempotency_key: Optional[str]

Client-supplied key making retries safe. Repeating a request with the same key returns the original dataset instead of generating again.

maxLength255

ReturnsExpand Collapse

class DatasetInventResponse: …

estimate: bool

True when this response priced the request without running it.

id: Optional[str]

Dataset id, or null on an estimate. Pass it straight to finetune_jobs.create or autoscientist.create once the status is succeeded.

name: str

Display name, echoed from the request or the default applied for you.

training_type: Literal["instruction_dataset", "preference_pairs"]

Shape of the generated data, echoed from the request.

One of the following:

"instruction_dataset"

"preference_pairs"

domains: List[str]

Domain codes the generation covers, echoed from the request — including any inferred from subdomains.

subdomains: List[str]

Subdomain codes the generation is narrowed to, if any.

rows: Optional[int]

Number of rows requested.

status: Optional[Literal["pending", "running", "awaiting_input", 2 more]]

Lifecycle status, or null on an estimate. A fresh generation is always running; poll GET /datasets/{dataset_id} until it reports succeeded or failed.

One of the following:

"pending"

"running"

"awaiting_input"

"succeeded"

"failed"

created_at: Optional[datetime]

When the dataset was created, or null on an estimate.

formatdate-time

estimated_credits: float

Credits this generation consumes. Billed on the post-expansion row count, so a translated request quotes above its rows. Invent pricing is still provisional, so treat the figure as indicative.

available_credits: float

Credits currently available to your team.

Generate a dataset from scratch

import os
from adaption import Adaption

client = Adaption(
    api_key=os.environ.get("ADAPTION_API_KEY"),  # This is the default and can be omitted
)
response = client.datasets.invent(
    rows=1000,
)
print(response.id)

{
  "estimate": false,
  "id": "3f1b9c62-6f3e-4a1e-9a5c-0b7d2f8e4a10",
  "name": "Clinical Q&A",
  "training_type": "instruction_dataset",
  "domains": [
    "medical"
  ],
  "subdomains": [
    "medical.symptoms_diagnosis"
  ],
  "rows": 1000,
  "status": "running",
  "created_at": "2026-08-03T16:12:04.000Z",
  "estimated_credits": 800,
  "available_credits": 5000
}

Returns Examples

{
  "estimate": false,
  "id": "3f1b9c62-6f3e-4a1e-9a5c-0b7d2f8e4a10",
  "name": "Clinical Q&A",
  "training_type": "instruction_dataset",
  "domains": [
    "medical"
  ],
  "subdomains": [
    "medical.symptoms_diagnosis"
  ],
  "rows": 1000,
  "status": "running",
  "created_at": "2026-08-03T16:12:04.000Z",
  "estimated_credits": 800,
  "available_credits": 5000
}