How this dataset came about. uploaded was supplied by you, combined merges several datasets, invented was generated from a prompt, augmented adds rows retrieved from the curated pool to another dataset, translated / localized add translated copies of another dataset’s rows, and extended adds a next user turn to each of another dataset’s conversations.

One of the following:

"uploaded"

"combined"

"invented"

"augmented"

"translated"

"localized"

"extended"

source_dataset_id: Optional[str]

The dataset this one was derived from. Set when kind is augmented, translated, localized or extended. Null for uploaded and invented, and for combined, which has several sources rather than one.

Human-readable name for the dataset

status: Literal["pending", "running", "succeeded", "failed"]

Lifecycle status: pending, running, succeeded, or failed

One of the following:

"pending"

"running"

"succeeded"

"failed"

created_at: datetime

Timestamp when the dataset was created

formatdate-time

created_by_user_id: Optional[str]

User who created the dataset

formatuuid

updated_at: datetime

Timestamp of the last update

formatdate-time

row_count: Optional[int]

Total number of rows in the dataset

configured_column_mapping: Optional[ConfiguredColumnMapping]

User-configured column mapping. Null if not yet configured.

prompt: Optional[str]

completion: Optional[str]

chat: Optional[str]

context: List[str]

image: Optional[str]

evaluation_summary: Optional[EvaluationSummary]

Compact evaluation summary. Null if evaluation has not completed.

grade_before: Optional[str]

Letter grade (A-E) before adaptation

grade_after: Optional[str]

Letter grade (A-E) after adaptation

score_before: Optional[float]

Quality score before adaptation

score_after: Optional[float]

Quality score after adaptation

improvement_percent: Optional[float]

Relative improvement percentage

run_id: Optional[str]

ID of the currently active run

progress: Optional[Progress]

Processing progress. Null when no run is active.

percent: Optional[int]

Progress percentage (0-100)

processed_rows: Optional[int]

Number of rows processed so far

total_rows: Optional[int]

Total rows to process (samples_to_process or row_count)

error_data: Optional[ErrorData]

Error details if the dataset failed. Null otherwise.

message: Optional[str]

Error message

code: Optional[str]

Stable error code when the failure was structured (e.g. E0100)

level: Optional[Literal["error", "warning"]]

Severity when known

One of the following:

"error"

"warning"

image_column_formats: Optional[Dict[str, Literal["embedded_bytes", "url", "file_reference"]]]

Per-column export encoding for detected image columns (column name → format). Use with GET /datasets/{dataset_id}/download: look up the active image column (mapped image column that is also in configured_column_mapping.context) to determine how each row’s original_image is encoded. Null or empty when no image columns were detected.

One of the following:

"embedded_bytes"

"url"

"file_reference"

class DatasetCreateResponse: …

dataset_id: str

ID of the newly created dataset

status: str

Current dataset status

upload_instructions: Optional[UploadInstructions]

Upload instructions for file sources. PUT your file to the provided URL.

url: str

Pre-signed URL for uploading the file

method: str

HTTP method to use

s3_key: str

S3 object key — pass this back in the complete request if needed for verification

class DatasetListResponse: …

dataset_id: str

Dataset ID

Dataset name

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

Dataset status

One of the following:

"pending"

"running"

"awaiting_input"

"succeeded"

"failed"

updated_at: datetime

Last updated timestamp

formatdate-time

created_at: datetime

Timestamp when the dataset was created

formatdate-time

row_count: Optional[int]

Total number of rows

description: Optional[str]

Auto-generated description of the dataset contents

class DatasetGetStatusResponse: …

dataset_id: str

Dataset ID

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

Current processing status. awaiting_input means the dataset is uploaded but waiting for you to start adaptation via datasets.adapt(column_mapping=…) — it will not progress on its own.

One of the following:

"pending"

"running"

"awaiting_input"

"succeeded"

"failed"

row_count: Optional[int]

Number of rows in the dataset

progress: Optional[Progress]

Processing progress. Null when no run is active.

percent: Optional[int]

Progress percentage (0-100)

processed_rows: Optional[int]

Number of rows processed so far

total_rows: Optional[int]

Total rows to process (samples_to_process or row_count)

error_data: Optional[ErrorData]

Error details if the dataset failed. Null otherwise.

message: Optional[str]

Error message

code: Optional[str]

Stable error code when the failure was structured (e.g. E0100)

level: Optional[Literal["error", "warning"]]

Severity when known

One of the following:

"error"

"warning"

class DatasetPublishResponse: …

publish_id: str

Unique identifier for the publish job

status: str

Status of the publish job

message: Optional[str]

Additional information about the publish request

class DatasetRunResponse: …

run_id: Optional[str]

Unique identifier for this pipeline run. Null for estimate-only requests.

estimated_minutes: float

Estimated processing time in minutes

estimated_credits_consumed: float

Estimated number of credits that will be consumed by this run

estimate: bool

Whether this was an estimate-only request (no run started)

multimodal_pricing_applied: bool

True when an image column is mapped and also listed in context_columns; each output row is billed at a higher rate.

credit_multiplier: Optional[float]

10 credits per 100 output rows when multimodalPricingApplied is true. Omitted for text-only pricing.

class DatasetAdaptResponse: …

run_id: Optional[str]

Unique identifier for this pipeline run. Null for estimate-only requests.

estimated_minutes: float

Estimated processing time in minutes

estimated_credits_consumed: float

Estimated number of credits that will be consumed by this run

estimate: bool

Whether this was an estimate-only request (no run started)

multimodal_pricing_applied: bool

True when an image column is mapped and also listed in context_columns; each output row is billed at a higher rate.

credit_multiplier: Optional[float]

10 credits per 100 output rows when multimodalPricingApplied is true. Omitted for text-only pricing.

class DatasetAugmentResponse: …

dataset_id: Optional[str]

The augmented dataset. It carries this dataset’s rows plus the retrieved ones, and is ready to download once its status reaches succeeded. Null for an estimate, which creates nothing.

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

Status of the augmented dataset at the moment this response was sent, in the same vocabulary GET /datasets/{dataset_id}/status reports. Poll that endpoint until it reaches succeeded or failed. An idempotent replay of a finished run returns its terminal status here.

One of the following:

"pending"

"running"

"awaiting_input"

"succeeded"

"failed"

domain_rows: float

Rows this run retrieves from topics matching the dataset, or the recommended fill an estimate priced.

general_rows: float

Rows this run retrieves from other topics, to broaden the dataset, or the recommended fill an estimate priced.

estimated_credits_consumed: float

Credits this run consumes, charged against the requested rows.

estimate: bool

Whether this was an estimate-only request (no run started).

class DatasetTranslateResponse: …

dataset_id: Optional[str]

The expanded dataset. It carries this dataset’s rows plus the new ones, and is ready to download once its status reaches succeeded. Null for an estimate, which creates nothing.

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

Status of the expanded dataset at the moment this response was sent, in the same vocabulary GET /datasets/{dataset_id}/status reports. Poll that endpoint until it reaches succeeded or failed. An idempotent replay of a finished run returns its terminal status here.

One of the following:

"pending"

"running"

"awaiting_input"

"succeeded"

"failed"

estimated_credits_consumed: float

Credits this run consumes, charged against the rows it adds. Zero on an idempotent replay: the earlier run reserved the credits, and this call charges nothing.

estimate: bool

Whether this was an estimate-only request (no run started).

estimated_new_rows: float

Rows this run adds, which is what the credit cost is charged against. Zero on an idempotent replay, which adds none.

class DatasetLocalizeResponse: …

dataset_id: Optional[str]

The expanded dataset. It carries this dataset’s rows plus the new ones, and is ready to download once its status reaches succeeded. Null for an estimate, which creates nothing.

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

One of the following:

"pending"

"running"

"awaiting_input"

"succeeded"

"failed"

estimated_credits_consumed: float

Credits this run consumes, charged against the rows it adds. Zero on an idempotent replay: the earlier run reserved the credits, and this call charges nothing.

estimate: bool

Whether this was an estimate-only request (no run started).

estimated_new_rows: float

Rows this run adds, which is what the credit cost is charged against. Zero on an idempotent replay, which adds none.

class DatasetExtendTrajectoriesResponse: …

run_id: Optional[str]

Unique identifier for this pipeline run. Null for estimate-only requests.

estimated_minutes: float

Estimated processing time in minutes

estimated_credits_consumed: float

Estimated number of credits that will be consumed by this run

estimate: bool

Whether this was an estimate-only request (no run started)

multimodal_pricing_applied: bool

True when an image column is mapped and also listed in context_columns; each output row is billed at a higher rate.

credit_multiplier: Optional[float]

10 credits per 100 output rows when multimodalPricingApplied is true. Omitted for text-only pricing.

dataset_id: Optional[str]

The new dataset holding the extended trajectories. Poll GET /datasets/{dataset_id}/status and download from GET /datasets/{dataset_id}/download with this id, not the source dataset’s. Null for estimate-only requests.

formatuuid

class DatasetGetEvaluationResponse: …

dataset_id: str

Dataset ID

status: Optional[str]

Evaluation pipeline status: pending | running | succeeded | failed | skipped

quality: Optional[Quality]

Structured quality metrics. Null until evaluation completes.

grade_before: Optional[str]

Letter grade (A-E) before adaptation

grade_after: Optional[str]

Letter grade (A-E) after adaptation

score_before: Optional[float]

Quality score (0-10) before adaptation

score_after: Optional[float]

Quality score (0-10) after adaptation

percentile_after: Optional[float]

Percentile rank (0-100) after adaptation

improvement_percent: Optional[float]

Relative quality improvement as a percentage

raw_results: Optional[Dict[str, object]]

Raw evaluation results payload for advanced use. Null until evaluation completes.

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.

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.

class DatasetInventDomainsResponse: …

domains: List[Domain]

code: str

Code to send in domains.

title: str

Human-readable name.

subdomains: List[DomainSubdomain]

Subdomains available within this domain. Empty when the domain has no subdivision — send the domain code alone.

code: str

Qualified code to send in subdomains — copy it as-is rather than assembling it.

title: str

Human-readable name.

class DatasetDeleteResponse: …

message: str

class DatasetGetExportLinksResponse: …

huggingface: Optional[str]

URL of the dataset on Hugging Face, if a successful export exists

kaggle: Optional[str]

URL of the dataset on Kaggle, if a successful export exists

google_sheets: Optional[str]

URL of the Google Spreadsheet, if a successful export exists

class DatasetGetBestLaunchConfigResponse: …

best_job_config: Optional[BestJobConfig]

Launch-parity snapshot for the experiment best job (terminal experiment with best_finetune_job_id) or, when no experiment exists, the newest succeeded standalone job (training_experiment_id null). Null while an experiment is non-terminal, when no best job was chosen yet, or when no qualifying job exists.

finetune_job_id: str

Fine-tune job whose config is shown (experiment best or standalone).

formatuuid

training_experiment_id: Optional[str]

Training experiment when this snapshot is the AutoScientist best job; null for a standalone job.

formatuuid

original_model_name: Optional[str]

Base model id the job was launched with.

trained_model_name: Optional[str]

Output label / suffix for the trained model. Taken from the value recorded at launch when present; otherwise derived from the current dataset name, in which case it can differ from the label the job was submitted with if the dataset was renamed. Null only when no label was recorded and the dataset is unavailable.

training_method: Optional[Literal["sft", "dpo"]]

One of the following:

"sft"

"dpo"

training_type: Optional[Literal["lora", "full"]]

One of the following:

"lora"

"full"

data_format: Optional[Literal["chat", "instruction", "preference"]]

One of the following:

"chat"

"instruction"

"preference"

hyperparams: Optional[Dict[str, object]]

Hyperparameters the job was launched with.

DatasetsUpload

Initiate a dataset upload

datasets.upload.initiate() -> UploadInitiateResponse

POST/api/v1/datasets/upload/initiate

Complete a dataset upload and trigger processing

datasets.upload.complete() -> UploadCompleteResponse

POST/api/v1/datasets/upload/complete

Complete a file upload and trigger processing

datasets.upload.complete_by_id(, ) -> UploadCompleteByIDResponse

POST/api/v1/datasets/{dataset_id}/upload/complete

Initiate a batch upload

datasets.upload.initiate_batch() -> UploadInitiateBatchResponse

POST/api/v1/datasets/upload/initiate-batch

Complete a batch upload and trigger processing

datasets.upload.complete_batch() -> UploadCompleteBatchResponse

POST/api/v1/datasets/upload/complete-batch

ModelsExpand Collapse

class UploadInitiateResponse: …

upload_url: str

Pre-signed S3 URL — upload the file directly to this URL via HTTP PUT

class UploadCompleteResponse: …

dataset_id: str

ID of the newly created dataset

class UploadCompleteByIDResponse: …

dataset_id: str

ID of the dataset

status: str

Current status of the dataset after completing upload

class UploadInitiateBatchResponse: …

dataset_id: str

Dataset ID

uploads: List[Upload]

file_name: str

Original file name

upload_url: str

Presigned S3 upload URL

s3_key: str

S3 key for the uploaded file

class UploadCompleteBatchResponse: …

dataset_id: str

Dataset ID

status: str

Current dataset status

DatasetsCombine

Combine multiple Datasets into a single new merged Dataset

datasets.combine.create() -> CombineCreateResponse

POST/api/v1/datasets/combine

Validate that a set of Datasets can be combined

datasets.combine.validate() -> CombineValidateResponse

POST/api/v1/datasets/combine/validate

ModelsExpand Collapse

class CombineCreateResponse: …

dataset_id: str

The newly created merged Dataset’s ID. Returns existing ID on idempotent replay.

class CombineValidateResponse: …

compatible: bool

Whether the proposed merge can proceed.

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

Resolved training type for a compatible merge. Homogeneous source sets inherit their shared type; mixed instruction + preference sets resolve to instruction_dataset.

One of the following:

"instruction_dataset"

"preference_pairs"

total_estimated_rows: Optional[float]

Sum of processed_rows across all sources for a compatible merge.

issues: List[Issue]

Validation diagnostics. Errors block the merge; warnings describe reconciliation the merge performs automatically.

code: Literal["too_few_sources", "too_many_sources", "duplicate_source_ids", 9 more]

Stable machine-readable validation issue code.

One of the following:

"too_few_sources"

"too_many_sources"

"duplicate_source_ids"

"dataset_not_found"

"wrong_organization"

"dataset_not_ready"

"missing_run_id"

"mixed_multimodal_sources"

"all_preference_sources_missing_dpo_columns"

"incompatible_column_types"

"preference_source_missing_ranked_generations"

"mixed_training_types_resolved_to_sft"

level: Literal["error", "warning"]

error blocks the merge; warning describes automatic reconciliation.

One of the following:

"error"

"warning"

message: str

Preformed user-facing message.

limit: Optional[float]

dataset_id: Optional[str]

status: Optional[str]

dataset_ids: Optional[List[str]]

multimodal_dataset_ids: Optional[List[str]]

text_dataset_ids: Optional[List[str]]

columns: Optional[List[IssueColumn]]

column: str

Column whose source types do not agree.

types: List[IssueColumnType]

dataset_id: str

Source Dataset ID.

type: str

DuckDB type observed for this Dataset.

cast_to: str

Common DuckDB type used by the merge.

types: Optional[List[IssueType]]

dataset_id: str

Source Dataset ID.

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

Training type resolved for this source Dataset.

One of the following:

"instruction_dataset"

"preference_pairs"