Skip to main content
POST
/
api
/
dataframer
/
runs
Python
import os
from dataframer import Dataframer

client = Dataframer(
    api_key=os.environ.get("DATAFRAMER_API_KEY"),  # This is the default and can be omitted
)
run = client.dataframer.runs.create(
    number_of_samples=1,
    spec_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(run.id)
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Authorizations

​
Authorization
string
header
required

API Key authentication. Format: "Bearer YOUR_API_KEY"

Body

application/json

Request body for creating a generation run

​
spec_id
string<uuid>
required

ID of the spec to use for generation. Spec must be in SUCCEEDED status.

​
number_of_samples
integer
required

Number of samples to generate

Required range: 1 <= x <= 20000
​
spec_version
integer

Version number to use (optional, defaults to latest)

Required range: x >= 1
​
generation_model
enum<string>
default:gemini/gemini-3-pro-preview-thinking

Model for generation. Use -thinking suffix to enable thinking mode.

Available options:
anthropic/claude-opus-4-5,
anthropic/claude-opus-4-5-thinking,
anthropic/claude-sonnet-4-5,
anthropic/claude-sonnet-4-5-thinking,
anthropic/claude-haiku-4-5,
deepseek-ai/DeepSeek-V3.1,
deepseek-ai/DeepSeek-R1-0528-tput,
Qwen/Qwen2.5-72B-Instruct-Turbo,
moonshotai/Kimi-K2-Instruct,
openai/gpt-oss-120b,
gemini/gemini-3-pro-preview,
gemini/gemini-3-pro-preview-thinking
​
outline_model
enum<string>
default:gemini/gemini-3-pro-preview-thinking

Model for outline generation

Available options:
anthropic/claude-opus-4-5,
anthropic/claude-opus-4-5-thinking,
anthropic/claude-sonnet-4-5,
anthropic/claude-sonnet-4-5-thinking,
anthropic/claude-haiku-4-5,
deepseek-ai/DeepSeek-V3.1,
deepseek-ai/DeepSeek-R1-0528-tput,
Qwen/Qwen2.5-72B-Instruct-Turbo,
moonshotai/Kimi-K2-Instruct,
openai/gpt-oss-120b,
gemini/gemini-3-pro-preview,
gemini/gemini-3-pro-preview-thinking
​
revision_model
enum<string>
default:gemini/gemini-3-pro-preview-thinking

Model for revisions (only used if enable_revisions is true)

Available options:
anthropic/claude-opus-4-5,
anthropic/claude-opus-4-5-thinking,
anthropic/claude-sonnet-4-5,
anthropic/claude-sonnet-4-5-thinking,
anthropic/claude-haiku-4-5,
deepseek-ai/DeepSeek-V3.1,
deepseek-ai/DeepSeek-R1-0528-tput,
Qwen/Qwen2.5-72B-Instruct-Turbo,
moonshotai/Kimi-K2-Instruct,
openai/gpt-oss-120b,
gemini/gemini-3-pro-preview,
gemini/gemini-3-pro-preview-thinking
​
enable_revisions
boolean
default:false

Enable revision cycles

​
max_revision_cycles
integer
default:1

Maximum number of revision cycles

Required range: 1 <= x <= 5
​
seed_shuffling_level
enum<string>
default:none

(advanced) How to shuffle seed examples between samples

Available options:
none,
sample,
field,
prompt
​
max_examples_in_prompt
integer

(advanced) Maximum number of seed examples to include in prompts. By default, only as many seeds as fit in 10K tokens are used. Use this to override the default.

Required range: x >= 1
​
unified_multifield
boolean
default:true

(advanced) Use unified multifield generation. This helps to reduce the generation cost by processing all fields together rather than one by one.

Response

Run created and submitted

​
id
string<uuid>

Run ID for polling status