---
title: "Process Uploaded Dataset"
method: POST
path: "/v1/datasets/upload/process"
tags: ["datasets"]
---

# Process Uploaded Dataset

`POST /v1/datasets/upload/process`

## Request

- Base URL: `https://api.fastino.ai`
- URL: `https://api.fastino.ai/v1/datasets/upload/process`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/fastino-ai/apis/pioneer-inference-api/docs/v1/datasets/upload/process/post.ts> (a function with typed inputs; its response is checked against the schema)

Queues processing for a reserved dataset upload.

## Request body

- DatasetUploadProcessRequest: Request to process uploaded dataset from S3.
  - `dataset_id` string, required: Dataset ID from upload/url response (all metadata stored in DB)

## Response `202`

Successful Response

- DatasetResponse: Response model for a single dataset.
  - `annotation_config` object, nullable
  - `annotation_progress` object, nullable
  - `annotation_status` 'none' | 'in_progress' | 'completed', nullable
  - `column_mapping` object, nullable: Column mapping from original to standard names
  - `created_at` string, required
  - `dataset_name` string, required
  - `dataset_path` string, required
  - `dataset_type` string, required
  - `generation_type` string, nullable: Canonical operation that created this dataset version.
  - `id` string, required
  - `is_competition` boolean: Whether this dataset is a competition benchmark
  - `is_seed` boolean, nullable: Whether this dataset is a seed dataset (small set for review before full expansion)
  - `labels` string[], nullable: Label names (entity types for NER, class labels for classification). A training job accepts at most 250 unique labels across its datasets.
  - `processing_error` string, nullable: Error message if status is failed
  - `project_id` string, nullable
  - `provenance` DatasetProvenance: Record how a dataset was created and which inputs produced it. Attributes: schema_version: Contract version for future migrations. method: Canonical dataset generation type. sources: External source descriptors. fallback: Fallback reason and attempt count, when one was required. source_dataset_ids: Dataset inputs combined or transformed. parent_dataset_id: Immediate dataset version or transform parent. transform_context: Bounded details about a transform. generator_context: Bounded generator configuration or agent context. synthesis_session_id: Synthesis-log session shared with the dataset row.
    - `fallback` DatasetProvenanceFallback: Describe a fallback used after the preferred source or strategy failed. Attributes: reason: Why the preferred path could not be used. attempts: Number of attempts made before the fallback succeeded.
      - `attempts` integer, required
      - `reason` string, required
    - `generator_context` JsonObjectOutput
    - `method` 'synthesize' | 'upload' | 'external' | 'grow' | 'augment' | 'version' | 'merge' | 'auto_relabel' | 'manual_relabel' | 'evaluation_suite' | 'agent_curated', required
    - `parent_dataset_id` string, nullable
    - `schema_version` 1
    - `source_dataset_ids` string[]
    - `sources` DatasetProvenanceSource[]
      - `license` string, nullable
      - `raw_hash` string, nullable
      - `retrieved_at` string, date-time, nullable
      - `revision` string, nullable
      - `url` string, nullable
    - `synthesis_session_id` string, nullable
    - `transform_context` JsonObjectOutput
  - `root_dataset_id` string, nullable
  - `sample_size` integer, nullable
  - `schema` object, nullable
  - `schema_warnings` string[], nullable
  - `size` integer, nullable
  - `status` 'initialized' | 'uploading' | 'converting' | 'validating' | 'ready' | 'failed' | 'generating' | 'queued', nullable: Dataset status: initialized/uploading/converting/validating/ready/failed/generating/queued
  - `synthesis_session_id` string, nullable: UUID of the synthesis log session for this dataset, used to restore creation workflow on resume
  - `train_ratio` number, nullable: Train split ratio for this dataset version. Left-to-right split with no shuffle; validation is the tail.
  - `type` string: Dataset purpose tag: 'training', 'evaluation', or 'benchmark'
  - `updated_at` string, required
  - `user_id` string, required
  - `validation` object, nullable
  - `version_number` string
  - `visibility` string: Dataset visibility: 'private' or 'public'
  - `warnings` DatasetWarning[]: Why this dataset will not train well on its own: too few rows, a single class, or more labels than training accepts. Derived from the processed dataset, so it is empty until the dataset is ready.
    - `code` 'too_few_rows' | 'single_class' | 'too_many_labels', required: Machine-readable warning code
    - `message` string, required: What is wrong, and what training does with it

## Other responses

- `422`: Validation Error
- `503`: The uploaded file could not be verified in storage, or the processing job could not be queued. The upload can be processed again. Retryable.

## Changes

- **2026-10-12** `43d7e06a824b`: 1 info
  - added the non-success response with the status `503`
- **2026-09-28** `b2e46909a0f8`: 1 info
  - added the optional property `warnings` to the response with the `202` status
- **2026-09-28** `54da122a2879`: 1 info
  - api operation id `process_uploaded_dataset_datasets_upload_process_post` removed and replaced with `process_uploaded_dataset_v1_datasets_upload_process_post`
- **2026-09-24** `a6b874d67be7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/fastino-ai/apis/pioneer-inference-api/changes/v1/datasets/upload/process/post.md)

---

[API](https://skmtc.dev/fastino-ai/apis/pioneer-inference-api.md) - [All operations](https://skmtc.dev/fastino-ai/apis/pioneer-inference-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fastino-ai/apis/pioneer-inference-api/revisions/81465e18c1d2?raw)