> ## Documentation Index > Fetch the complete documentation index at: https://www.dataframer.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Start a new generation run > Start a new data generation run **Async operation**: This endpoint returns immediately with a run ID. Poll `GET /api/dataframer/runs/{id}/` until status changes from `PENDING`/`IN_PROGRESS` to `SUCCEEDED` or `FAILED`. ## OpenAPI ````yaml POST /api/dataframer/runs/ openapi: 3.0.0 info: title: DataFramer API version: 0.1.0 description: '' termsOfService: https://www.aimon.ai/docs/privacy-policy.pdf contact: name: DataFramer Support email: info@dataframer.ai license: name: Proprietary x-logo: url: https://dataframer.ai/logo.png altText: DataFramer AI x-stainless: package-name: aimon-dataframer namespace: - aimon - dataframer servers: - url: https://df-api.dataframer.ai description: Production server security: - BearerAuth: [] externalDocs: description: Complete API Guide url: https://docs.dataframer.ai/dataframer paths: /api/dataframer/runs/: post: summary: Start a new generation run description: >- Start a new data generation run. **Async operation**: This endpoint returns immediately with a run ID. Poll `GET /api/dataframer/runs/{id}/` until status changes from `PENDING`/`PROCESSING` to `SUCCEEDED` or `FAILED`. operationId: api_dataframer_runs_create requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RunCreate' responses: '202': description: >- Run created and submitted. Returns the full run resource including server-applied defaults (generation_model, outline_model, revision_model, max_revision_cycles, seed_shuffling_level, unified_multifield, skip_outline, tools) and the resolved spec_version, so callers can confirm how the run was created without a follow-up GET. content: application/json: schema: $ref: '#/components/schemas/Run' '400': description: Bad request - validation error '401': description: Unauthorized '402': description: Payment required - subscription inactive '404': description: Spec or version not found x-codeSamples: - lang: Python source: |- 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) - lang: cURL source: |- curl https://df-api.dataframer.ai/api/dataframer/runs/ \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $DATAFRAMER_API_KEY" \ -d '{ "number_of_samples": 1, "spec_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e" }' components: schemas: RunCreate: type: object description: Request body for creating a generation run required: - spec_id - number_of_samples properties: spec_id: type: string format: uuid description: >- ID of the spec to use for generation. Spec must be in SUCCEEDED status. spec_version: type: integer minimum: 1 description: Version number to use (optional, defaults to latest) number_of_samples: type: integer minimum: 1 maximum: 20000 description: Number of samples to generate generation_model: type: string default: anthropic/claude-sonnet-5 enum: - anthropic/claude-fable-5-thinking - anthropic/claude-opus-5 - anthropic/claude-opus-5-thinking - anthropic/claude-sonnet-5 - anthropic/claude-sonnet-5-thinking - anthropic/claude-haiku-4-5 - anthropic/claude-haiku-4-5-thinking - gemini/gemini-3.1-pro-preview - gemini/gemini-3.1-pro-preview-thinking - openai/gpt-oss-120b - deepseek-ai/DeepSeek-V4-Pro-0813 - moonshotai/Kimi-K3 - moonshotai/Kimi-K2.6 - openai/gpt-5.6-sol - openai/gpt-5.6-sol-thinking - openai/gpt-5.6-terra - openai/gpt-5.6-terra-thinking - openai/gpt-5.6-luna - openai/gpt-5.6-luna-thinking - databricks/databricks-claude-haiku-4-5 - databricks/databricks-claude-haiku-4-5-thinking - databricks/databricks-claude-opus-5 - databricks/databricks-claude-opus-5-thinking - databricks/databricks-claude-sonnet-5 - databricks/databricks-claude-sonnet-5-thinking - databricks/databricks-gemini-3-1-pro - databricks/databricks-gemini-3-1-pro-thinking - databricks/databricks-gpt-5-6-terra - databricks/databricks-gpt-5-6-terra-thinking description: >- Model for generation. Use -thinking suffix to enable thinking mode. For databricks/ models, you must also provide databricks_client_id, databricks_client_secret, and databricks_api_base. outline_model: type: string default: anthropic/claude-sonnet-5-thinking enum: - anthropic/claude-fable-5-thinking - anthropic/claude-opus-5 - anthropic/claude-opus-5-thinking - anthropic/claude-sonnet-5 - anthropic/claude-sonnet-5-thinking - anthropic/claude-haiku-4-5 - anthropic/claude-haiku-4-5-thinking - gemini/gemini-3.1-pro-preview - gemini/gemini-3.1-pro-preview-thinking - openai/gpt-oss-120b - deepseek-ai/DeepSeek-V4-Pro-0813 - moonshotai/Kimi-K3 - moonshotai/Kimi-K2.6 - openai/gpt-5.6-sol - openai/gpt-5.6-sol-thinking - openai/gpt-5.6-terra - openai/gpt-5.6-terra-thinking - openai/gpt-5.6-luna - openai/gpt-5.6-luna-thinking - databricks/databricks-claude-haiku-4-5 - databricks/databricks-claude-haiku-4-5-thinking - databricks/databricks-claude-opus-5 - databricks/databricks-claude-opus-5-thinking - databricks/databricks-claude-sonnet-5 - databricks/databricks-claude-sonnet-5-thinking - databricks/databricks-gemini-3-1-pro - databricks/databricks-gemini-3-1-pro-thinking - databricks/databricks-gpt-5-6-terra - databricks/databricks-gpt-5-6-terra-thinking description: Model for outline generation revision_model: type: string default: anthropic/claude-sonnet-5-thinking enum: - anthropic/claude-fable-5-thinking - anthropic/claude-opus-5 - anthropic/claude-opus-5-thinking - anthropic/claude-sonnet-5 - anthropic/claude-sonnet-5-thinking - anthropic/claude-haiku-4-5 - anthropic/claude-haiku-4-5-thinking - gemini/gemini-3.1-pro-preview - gemini/gemini-3.1-pro-preview-thinking - openai/gpt-oss-120b - deepseek-ai/DeepSeek-V4-Pro-0813 - moonshotai/Kimi-K3 - moonshotai/Kimi-K2.6 - openai/gpt-5.6-sol - openai/gpt-5.6-sol-thinking - openai/gpt-5.6-terra - openai/gpt-5.6-terra-thinking - openai/gpt-5.6-luna - openai/gpt-5.6-luna-thinking - databricks/databricks-claude-haiku-4-5 - databricks/databricks-claude-haiku-4-5-thinking - databricks/databricks-claude-opus-5 - databricks/databricks-claude-opus-5-thinking - databricks/databricks-claude-sonnet-5 - databricks/databricks-claude-sonnet-5-thinking - databricks/databricks-gemini-3-1-pro - databricks/databricks-gemini-3-1-pro-thinking - databricks/databricks-gpt-5-6-terra - databricks/databricks-gpt-5-6-terra-thinking description: >- Model for revisions and filtering (only used if revision_types or filtering_types is set) revision_types: type: array items: type: string enum: - coherence_flow - consistency - distinguishability - conformance default: [] description: >- List of revision types to apply. Valid values: 'coherence_flow' (fix formatting/flow issues), 'consistency' (fix internal contradictions), 'distinguishability' (seeded only — blend with seed style), 'conformance' (verify property compliance). Defaults to empty (no revisions). filtering_types: type: array items: type: string enum: - structural - conformance default: [] description: >- List of filtering quality gates. Valid values: 'structural' (reject severe format issues), 'conformance' (reject property violations). Documents that fail are regenerated. Defaults to empty (no filtering). max_revision_cycles: type: integer minimum: 1 maximum: 5 default: 1 description: >- Maximum number of revision cycles. 2-3 is a solid pick for complex documents requiring internal consistency, e.g. financial reports, invoices, etc.; increase to 3-5 for highest quality or when generated data has issues. seed_shuffling_level: type: string enum: - none - sample - field - prompt default: none description: (advanced) How to shuffle seed examples between samples max_examples_in_prompt: type: integer minimum: 1 description: >- (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. unified_multifield: type: boolean default: true description: >- (advanced) Use unified multifield generation. This helps to reduce the generation cost by processing all fields together rather than one by one. generation_thinking_budget: type: integer minimum: 1024 default: 1024 description: >- Token budget for extended thinking during generation. Only applies to models with -thinking suffix. outline_thinking_budget: type: integer minimum: 1024 default: 1024 description: >- Token budget for extended thinking during outline generation. Only applies to models with -thinking suffix. revision_thinking_budget: type: integer minimum: 1024 default: 1024 description: >- Token budget for extended thinking during revisions. Only applies to models with -thinking suffix. databricks_client_id: type: string description: >- Databricks service principal application (client) ID. Required when using databricks/models. databricks_client_secret: type: string description: >- Databricks service principal secret. Required when using databricks/models. databricks_api_base: type: string description: >- Databricks Model Serving endpoint URL (e.g. https://adb-xxx.azuredatabricks.net/serving-endpoints). Required when using databricks/models. skip_outline: type: boolean default: true description: >- Skip outline and part-by-part generation. Generates a document draft directly in a single call. Faster and cheaper but not suitable for very long documents. tools: type: array items: type: string default: [] description: >- List of tools available to the LLM during generation. Currently supported: 'calculator' (sandboxed Python for numerical verification). Roughly doubles cost and time. Defaults to empty. enable_revisions: type: boolean default: false deprecated: true description: >- Use revision_types and filtering_types instead. When set to true without those fields, enables all revision types and structural filtering. Run: type: object properties: id: type: string format: uuid description: Unique identifier for the run status: type: string enum: - PENDING - PROCESSING - SUCCEEDED - FAILED - CANCELED description: Current status of the run spec_id: type: string format: uuid description: ID of the spec used spec_name: type: string description: Name of the spec spec_version: type: integer description: Version number of the spec used dataset_id: type: string format: uuid nullable: true description: ID of the seed dataset (null for seedless specs) dataset_name: type: string nullable: true description: Name of the seed dataset (null for seedless specs) dataset_type: type: string enum: - SINGLE_FILE - MULTI_FILE - MULTI_FOLDER description: Type of dataset samples_completed: type: integer description: Number of samples successfully generated samples_failed: type: integer description: Number of samples that failed to generate total_cost: type: number nullable: true description: Total cost of the run in dollars created_at: type: string format: date-time description: When the run was created created_by_email: type: string description: Email of the user who created the run completed_at: type: string format: date-time nullable: true description: When the run completed (null if not finished) runtime_params: $ref: '#/components/schemas/RunRuntimeParams' generated_files: type: array description: List of generated files (populated when run completes) items: $ref: '#/components/schemas/GeneratedFile' RunRuntimeParams: type: object description: Generation parameters used for the run properties: number_of_samples: type: integer description: Number of samples requested generation_model: type: string description: Model used for generation outline_model: type: string description: Model used for outline generation revision_model: type: string nullable: true description: Model used for revisions (null if revisions disabled) revision_types: type: array items: type: string description: Revision types that were applied filtering_types: type: array items: type: string description: Filtering types that were applied max_revision_cycles: type: integer nullable: true description: Max revision cycles (null if revisions disabled) seed_shuffling_level: type: string enum: - none - sample - field - prompt description: Seed shuffling level used max_examples_in_prompt: type: integer nullable: true description: Max examples in prompt (null if not set) unified_multifield: type: boolean description: Whether unified multifield generation was used generation_thinking_budget: type: integer nullable: true description: >- Thinking budget used for generation model (null if not a thinking model) outline_thinking_budget: type: integer nullable: true description: >- Thinking budget used for outline model (null if not a thinking model) revision_thinking_budget: type: integer nullable: true description: >- Thinking budget used for revision model (null if not a thinking model) skip_outline: type: boolean nullable: true description: Whether outline and part-by-part generation was skipped tools: type: array items: type: string nullable: true description: Tools that were available to the LLM during generation GeneratedFile: type: object description: A generated file from a run properties: id: type: string description: File identifier for download path: type: string description: File path within the run output file_type: type: string description: MIME type of the file size_bytes: type: integer description: File size in bytes securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key description: 'API Key authentication. Format: "Bearer YOUR_API_KEY"' ````