← Back to overview

Experiments

Experiments execute a matrix of journeys, personas, and browser types. The system computes the cartesian product and spawns one agent per combination, letting you compare results across all dimensions in a single run.

Experiment Matrix

The experiment matrix is the cartesian product of three dimensions: journeys, personas, and browser types. For each combination, the system spawns one agent.

For example, 2 journeys × 3 personas × 2 browsers = 12 agents in a single run. Each agent gets its own isolated browser session and runs independently.

After a run completes, use the comparison endpoint to get aggregate results across all combinations.

Paste your API key to use the Try it panels below. Don't have one? Create an account.

POST /api/v1/experiments Create a new experiment
ParameterTypeInRequiredDescription
project_iduuidbodyYesID of the project
namestringbodyYesExperiment name
descriptionstringbodyNoExperiment description
modestringbodyNoExperiment mode
matrixjsonbodyNoMatrix configuration defining the test combinations
configjsonbodyNoAdditional experiment configuration
event_schema_iduuidbodyNoEvent schema for analytics tracking
cURL 
Response 
GET /api/v1/experiments List experiments
ParameterTypeInRequiredDescription
 
limitintegerqueryNoNumber of results to return (default: 20)
cursoruuidqueryNoCursor for pagination 
projectuuidqueryNoFilter by project ID 
 
 
 
cURL 
Response 
GET /api/v1/experiments/{id} Get experiment by ID
ParameterTypeInRequiredDescription
 
iduuidpathYesExperiment ID 
 
cURL 
Response 
PATCH /api/v1/experiments/{id} Update an experiment
ParameterTypeInRequiredDescription
 
iduuidpathYesExperiment ID 
namestringbodyNoExperiment name 
descriptionstringbodyNoExperiment description 
modestringbodyNoExperiment mode 
matrixjsonbodyNoMatrix configuration 
configjsonbodyNoAdditional configuration 
event_schema_iduuidbodyNoEvent schema ID 
 
 
 
 
 
 
 
cURL 
Response 
DELETE /api/v1/experiments/{id} Delete an experiment
ParameterTypeInRequiredDescription
 
iduuidpathYesExperiment ID 
 
cURL 
Response 
POST /api/v1/experiments/{id}/run Run an experiment
Creates a new experiment run, spawning agents for each combination in the matrix.
ParameterTypeInRequiredDescription
 
iduuidpathYesExperiment ID 
filesarraybodyNoInitial files for agent workspaces 
 
 
cURL 
Response 
GET /api/v1/experiments/{id}/runs List experiment runs
ParameterTypeInRequiredDescription
 
iduuidpathYesExperiment ID 
limitintegerqueryNoNumber of results to return (default: 20)
cursoruuidqueryNoCursor for pagination 
 
 
 
cURL 
Response 
GET /api/v1/experiments/{id}/runs/{run_id} Get a specific experiment run
ParameterTypeInRequiredDescription
 
iduuidpathYesExperiment ID 
run_iduuidpathYesRun ID 
 
 
cURL 
Response 
GET /api/v1/experiments/{id}/runs/{run_id}/agents List agents in an experiment run
ParameterTypeInRequiredDescription
 
iduuidpathYesExperiment ID 
run_iduuidpathYesRun ID 
 
 
cURL 
Response 
GET /api/v1/experiments/{id}/runs/{run_id}/comparison Get comparison report for an experiment run
Returns a detailed comparison of agent results across personas, including aggregate statistics and optional analytics tracking health.
ParameterTypeInRequiredDescription
 
iduuidpathYesExperiment ID 
run_iduuidpathYesRun ID 
summarizebooleanqueryNoAuto-generate missing agent summaries (default: false)
resummarizebooleanqueryNoForce regenerate all summaries (default: false)
 
 
 
 
cURL 
Response