Skip to main content
POST
/
api
/
v2
/
experiments
/
Create Experiment
curl --request POST \
  --url https://api.keywordsai.co/api/v2/experiments/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "description": "<string>",
  "dataset_id": "<string>",
  "workflows": [
    {
      "type": "<string>",
      "config": {
        "name": "<string>",
        "description": "<string>"
      }
    }
  ],
  "evaluator_slugs": [
    {}
  ]
}'
Creates a new experiment with custom workflows. The system will create placeholder traces for each dataset entry, which you can then update with your custom workflow results.

​
Authentication

All endpoints require API key authentication: 
Authorization: Bearer YOUR_API_KEY

​
Parameters

​
name
string
required
The name of the experiment.
​
description
string
Description of the experiment.
​
dataset_id
string
required
The ID of the dataset to run the experiment on.
​
workflows
array
required
List of workflow configurations.
​
type
string
Type of workflow. Set to custom for custom workflows.
​
config
object
Configuration for the workflow.
​
name
string
Name of the workflow step.
​
description
string
Description of the workflow step.
​
evaluator_slugs
array
List of evaluator slugs to run on the experiment results.

​
Response

{
  "id": "experiment-123",
  "name": "My Custom Workflow Experiment",
  "description": "Testing custom workflow implementation",
  "dataset_id": "your-dataset-id",
  "workflows": [
    {
      "type": "custom",
      "config": {
        "name": "Custom Processing Workflow",
        "description": "User-defined workflow for custom processing"
      }
    }
  ],
  "evaluator_slugs": [
    "response_quality_v1",
    "factual_accuracy"
  ],
  "status": "running",
  "created_at": "2025-11-18T10:00:00Z",
  "updated_at": "2025-11-18T10:00:00Z"
}

​
Example

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": {"name": "My Custom Workflow"}}],
    "evaluator_slugs": ["response_quality_v1"]
  }'