> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keywordsai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Create experiment

Creates a new experiment with workflows. Supports three workflow types:

* **Custom**: Submit your own workflow results via API
* **Completion**: Direct LLM completions with custom parameters
* **Prompt**: Load and render Jinja2 prompt templates with dataset variables

For custom workflows, the system creates placeholder traces that you update with your results. For built-in workflows (prompt/completion), execution starts automatically in the background.

## Authentication

All endpoints require API key authentication:

```bash theme={"system"}
Authorization: Bearer YOUR_API_KEY
```

## Parameters

<ParamField body="name" type="string" required>
  The name of the experiment.
</ParamField>

<ParamField body="description" type="string">
  Description of the experiment.
</ParamField>

<ParamField body="dataset_id" type="string" required>
  The ID of the dataset to run the experiment on.
</ParamField>

<ParamField body="workflows" type="array" required>
  List of workflow configurations.

  <Accordion title="Properties">
    <ParamField body="type" type="string" required>
      Type of workflow. Options: `custom`, `completion`, or `prompt`.

      * `custom`: Submit your own workflow results
      * `completion`: Direct LLM completions
      * `prompt`: Load and render Jinja2 prompt templates
    </ParamField>

    <ParamField body="config" type="object">
      Configuration for the workflow. Structure depends on workflow type:

      <Accordion title="Custom Workflow Config">
        <ParamField body="allow_submission" type="boolean">Allow trace updates (default: true).</ParamField>
        <ParamField body="timeout_hours" type="number">Submission timeout in hours.</ParamField>
      </Accordion>

      <Accordion title="Completion Workflow Config">
        <ParamField body="model" type="string" required>Model identifier (e.g., "gpt-4o-mini").</ParamField>
        <ParamField body="temperature" type="number">Sampling temperature (0-2, default: 1.0).</ParamField>
        <ParamField body="max_tokens" type="integer">Maximum completion tokens (default: 150).</ParamField>
        <ParamField body="top_p" type="number">Nucleus sampling (0-1, default: 1.0).</ParamField>
        <ParamField body="frequency_penalty" type="number">Frequency penalty (-2 to 2, default: 0).</ParamField>
        <ParamField body="presence_penalty" type="number">Presence penalty (-2 to 2, default: 0).</ParamField>
        <ParamField body="stop" type="string or array">Stop sequences.</ParamField>
        <ParamField body="response_format" type="object">Response format (e.g., `{"type": "json_object"}`).</ParamField>
        <ParamField body="tools" type="array">Function calling tools.</ParamField>
        <ParamField body="tool_choice" type="string or object">Tool choice strategy.</ParamField>
        <ParamField body="reasoning_effort" type="string">Reasoning effort for o1 models.</ParamField>
      </Accordion>

      <Accordion title="Prompt Workflow Config">
        <ParamField body="prompt_id" type="string" required>Prompt identifier to load and render.</ParamField>
      </Accordion>
    </ParamField>
  </Accordion>
</ParamField>

<ParamField body="evaluator_slugs" type="array">
  List of evaluator slugs to run on the experiment results.
</ParamField>

## Response

```json theme={"system"}
{
  "id": "experiment-123",
  "name": "My Custom Workflow Experiment",
  "description": "Testing custom workflow implementation",
  "dataset_id": "your-dataset-id",
  "workflows": [
    {
      "type": "custom",
      "config": {
        "allow_submission": true,
        "timeout_hours": 24
      }
    }
  ],
  "evaluator_slugs": [
    "response_quality_v1",
    "factual_accuracy"
  ],
  "status": "running",
  "created_at": "2025-11-18T10:00:00Z",
  "updated_at": "2025-11-18T10:00:00Z"
}
```

## Examples

### Custom Workflow

```bash theme={"system"}
curl -X POST "https://api.keywordsai.co/api/v2/experiments/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom Processing Experiment",
    "dataset_id": "dataset-123",
    "workflows": [{"type": "custom", "config": {"allow_submission": true}}],
    "evaluator_slugs": ["response_quality_v1"]
  }'
```

### Completion Workflow

```bash theme={"system"}
curl -X POST "https://api.keywordsai.co/api/v2/experiments/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Completion Experiment",
    "dataset_id": "dataset-123",
    "workflows": [{
      "type": "completion",
      "config": {
        "model": "gpt-4o-mini",
        "temperature": 0.7,
        "max_tokens": 150
      }
    }],
    "evaluator_slugs": ["response_quality_v1"]
  }'
```

### Prompt Workflow

```bash theme={"system"}
curl -X POST "https://api.keywordsai.co/api/v2/experiments/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Prompt Experiment",
    "dataset_id": "dataset-123",
    "workflows": [{
      "type": "prompt",
      "config": {
        "prompt_id": "6caa11b48d4d440986b3eb3b96ae795e"
      }
    }],
    "evaluator_slugs": ["response_quality_v1"]
  }'
```

## Workflow Rules

**✅ Valid Combinations:**

* Single custom workflow
* Single built-in workflow (prompt or completion)
* Multiple built-in workflows chained together

**❌ Invalid Combinations:**

* Multiple custom workflows
* Custom workflow + built-in workflow
* Mixing custom and built-in types

**Chaining (Built-in Only):**
When you configure multiple built-in workflows, they execute in sequence - the output of one becomes the input of the next.