---
title: "Expand dataset with synthetic samples"
method: POST
path: "/v1/private/datasets/{id}/expansions"
tags: ["Datasets"]
---

# Expand dataset with synthetic samples

`POST /v1/private/datasets/{id}/expansions`

Generate synthetic dataset samples using LLM based on existing data patterns

## Path parameters

- `id` string, uuid, required

## Request body

- DatasetExpansionWrite
  - `model` string, required — The model to use for synthetic data generation
  - `sample_count` integer — Number of synthetic samples to generate
  - `preserve_fields` string[] — Fields to preserve patterns from original data
  - `variation_instructions` string — Additional instructions for data variation
  - `custom_prompt` string — Custom prompt to use for generation instead of auto-generated one
  - `max_completion_tokens` integer — Maximum number of tokens for the LLM response. Required by Anthropic, used as maxOutputTokens for Gemini. If not provided, defaults to 4000 for Anthropic models only.

## Response `200`

Generated synthetic samples

- DatasetExpansionResponse
  - `generated_samples` DatasetItem[] — List of generated synthetic dataset items
    - `id` string, uuid — Stable item identifier. On write, used as the upsert key. If omitted, a new ID is generated. Remains the same across dataset versions
    - `dataset_item_id` string, uuid — Deprecated. Always equals 'id'. Retained for backward compatibility and will be removed in a future version
    - `trace_id` string, uuid
    - `span_id` string, uuid
    - `source` 'manual' | 'trace' | 'span' | 'sdk', required
    - `data` JsonNode, required
    - `description` string
    - `tags` string[]
    - `evaluators` EvaluatorItem[]
      - `name` string, required
      - `type` 'llm_judge' | 'code_metric', required
      - `config` JsonNode, required
    - `execution_policy` ExecutionPolicy
      - `runs_per_item` integer
      - `pass_threshold` integer
    - `experiment_items` ExperimentItem[]
      - `id` string, uuid
      - `experiment_id` string, uuid, required
      - `dataset_item_id` string, uuid, required
      - `trace_id` string, uuid, required
      - `project_id` string, uuid
      - `project_name` string
      - `input` JsonListString
      - `output` JsonListString
      - `trace_metadata` JsonListString
      - `feedback_scores` FeedbackScore[]
        - `name` string, required
        - `category_name` string
        - `value` number, required
        - `reason` string
        - `source` 'ui' | 'sdk' | 'online_scoring', required
        - `source_queue_id` string, uuid
        - `created_at` string, date-time
        - `last_updated_at` string, date-time
        - `created_by` string
        - `last_updated_by` string
        - `value_by_author` object
      - `comments` Comment[]
        - `id` string, uuid
        - `text` string, required
        - `source_queue_id` string, uuid
        - `created_at` string, date-time
        - `last_updated_at` string, date-time
        - `created_by` string
        - `last_updated_by` string
      - `total_estimated_cost` number
      - `duration` number, double
      - `usage` object
      - `created_at` string, date-time
      - `last_updated_at` string, date-time
      - `created_by` string
      - `last_updated_by` string
      - `trace_visibility_mode` 'default' | 'hidden'
      - `description` string
      - `execution_policy` ExecutionPolicy
        - `runs_per_item` integer
        - `pass_threshold` integer
      - `assertion_results` AssertionResult[]
        - `value` string
        - `passed` boolean
        - `reason` string
      - `status` 'passed' | 'failed'
    - `run_summaries_by_experiment` object
    - `dataset_id` string, uuid
    - `created_at` string, date-time
    - `last_updated_at` string, date-time
    - `created_by` string
    - `last_updated_by` string
  - `model` string — Model used for generation
  - `total_generated` integer — Total number of samples generated
  - `generation_time` string, date-time — Generation timestamp

---

[API](https://skmtc.net/comet-ml/apis/opik-rest-api.md) · [All operations](https://skmtc.net/comet-ml/apis/opik-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/comet-ml/opik-rest-api/versions/4ed2fbc97cc3/schema)