caches5

creditTransactions2

dashboard21

datasets17

evaluators13

experiments12

gateway2

health1

models14

multimodal4

openAiBatch10

prompts14

scores12

spans6

temporaryApiKeys5

testsets14

threads1

traces8

users4

workflows12

experiments

Create an experiment

Create an experiment and start asynchronous workflow execution over a dataset.

post/api/v2/experiments/

Headers

Authorizationstring required

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, OpenAI or Azure OpenAI provider credentials go in Settings -> Providers or the request body credential_override field, not in this auth field.

Request body

dataset_idstring required

Dataset ID to process.

evaluator_idsstring[]

Preferred evaluator identifiers for scoring. Mutually exclusive with evaluator_workflow_ids.

evaluator_slugsstring[]

Backward-compatible alias for evaluator_ids. If both are provided, evaluator_ids takes precedence.

evaluator_workflow_idsstring[]

WorkflowVersion IDs configured for eval-only scoring. Mutually exclusive with evaluator IDs/slugs.

experiment_idstring

Optional client-provided experiment ID. The backend generates one when omitted.

namestring

Experiment name.

descriptionstring

Experiment description.

span_workflow_namestring

Root workflow span name.

enable_tracingboolean

Whether to create trace logs.

batch_sizeinteger

Batch size for processing.

concurrencyinteger

Number of concurrent workers.

generation_methodstring

Optional evaluation generation method override.

Response

Created experiment.

idstring required

Experiment ID.

namestring required

Experiment name.

descriptionstring nullable

Experiment description.

datasetstring nullable

Dataset ID associated with the experiment.

dataset_idstring nullable

Dataset ID associated with the experiment.

dataset_namestring nullable

Dataset name, when available.

workflow_countinteger

Number of workflow steps.

statusstring required

Experiment execution status.

progressnumber double

Execution progress percentage.

created_atstring date-time required

started_atstring date-time nullable

completed_atstring date-time nullable

tagsobject[]

Tags attached to the experiment.

evaluator_idsstring[]

Evaluator IDs used for scoring.

evaluator_slugsstring[]

Backward-compatible evaluator identifiers stored by the backend.

evaluator_workflow_idsstring[]

Eval-only workflow versions used for scoring.