Update Experiment - Retab Docs

from retab import Retab

client = Retab()

# Bump consensus from 5 to 7
client.workflows.experiments.update(
    experiment_id="exp_abc",
    n_consensus=7,
)

# Or rename only
client.workflows.experiments.update(
    experiment_id="exp_abc",
    name="Q1 invoices — v2",
)

import { Retab } from "@retab/node";

const client = new Retab({ apiKey: process.env.RETAB_API_KEY });

await client.workflows.experiments.update("exp_abc", undefined, undefined, 7);

package main

import (
	"context"
	"fmt"
	"log"

	retab "github.com/retab-dev/retab/clients/go"
)

func ptr[T any](v T) *T { return &v }

func main() {
	ctx := context.Background()
	nConsensus := retab.UpdateExperimentRequestNConsensus(retab.CreateExperimentRequestNConsensus7)

	client, err := retab.NewClient("")
	if err != nil {
		log.Fatal(err)
	}

	experiment, err := client.Workflows.Experiments.Update(
		ctx,
		"exp_abc",
		&retab.WorkflowExperimentsUpdateParams{NConsensus: &nConsensus},
	)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(experiment.ID, experiment.NConsensus)
}

require 'retab'

client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])

# Bump consensus from 5 to 7
client.workflow_experiments.update(
  experiment_id: 'exp_abc',
  n_consensus: 7,
)

# Or rename only
client.workflow_experiments.update(
  experiment_id: 'exp_abc',
  name: 'Q1 invoices — v2',
)

use retab::enums::UpdateExperimentRequestNConsensus;
use retab::models::UpdateExperimentRequest;
use retab::resources::workflow_experiments::UpdateParams;
use retab::Retab;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Retab::new(std::env::var("RETAB_API_KEY")?);

    let body = UpdateExperimentRequest {
        n_consensus: Some(UpdateExperimentRequestNConsensus::V7),
        ..Default::default()
    };
    let experiment = client
        .workflows()
        .experiments()
        .update("exp_abc", UpdateParams::new(body))
        .await?;
    println!("{}", experiment.id);
    Ok(())
}

<?php
require 'vendor/autoload.php';

use Retab\Client;

$client = new Client(apiKey: getenv('RETAB_API_KEY'));

$result = $client->workflowExperiments()->update(
    experimentId: 'exp_abc123',
);
print_r($result);

using Retab;
using RetabClient = Retab.Retab;

var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);

var result = await client.Workflows.Experiments.UpdateAsync("exp_abc123", new WorkflowExperimentsUpdateOptions());
Console.WriteLine(result);

import com.retab.RetabClient;

public final class Example {
  public static void main(String[] args) throws Exception {
    RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));

    var result = client.workflows().experiments().update("exp_abc123", null, null, null, "Invoice Processing");
    System.out.println(result);
  }
}

curl -X 'PATCH' \
  'https://api.retab.com/v1/workflows/experiments/exp_abc' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your-api-key>' \
  -d '{"n_consensus": 7}'

{
  "id": "exp_abc",
  "workflow_id": "wf_abc123",
  "block_id": "extract-invoice",
  "block_kind": "extract",
  "n_consensus": 7,
  "document_count": 12,
  "name": "Q1 invoices",
  "last_run_id": "exprun_1",
  "status": "completed",
  "score": 0.87,
  "is_stale": true,
  "schema_drift": "none",
  "schema_drift_detail": null,
  "created_at": "2026-05-01T14:30:00Z",
  "updated_at": "2026-05-02T11:00:00Z"
}

{
  "detail": "No fields to update."
}

PATCH

workflows

experiments

{experiment_id}

from retab import Retab

client = Retab()

# Bump consensus from 5 to 7
client.workflows.experiments.update(
    experiment_id="exp_abc",
    n_consensus=7,
)

# Or rename only
client.workflows.experiments.update(
    experiment_id="exp_abc",
    name="Q1 invoices — v2",
)

import { Retab } from "@retab/node";

const client = new Retab({ apiKey: process.env.RETAB_API_KEY });

await client.workflows.experiments.update("exp_abc", undefined, undefined, 7);

package main

import (
	"context"
	"fmt"
	"log"

	retab "github.com/retab-dev/retab/clients/go"
)

func ptr[T any](v T) *T { return &v }

func main() {
	ctx := context.Background()
	nConsensus := retab.UpdateExperimentRequestNConsensus(retab.CreateExperimentRequestNConsensus7)

	client, err := retab.NewClient("")
	if err != nil {
		log.Fatal(err)
	}

	experiment, err := client.Workflows.Experiments.Update(
		ctx,
		"exp_abc",
		&retab.WorkflowExperimentsUpdateParams{NConsensus: &nConsensus},
	)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(experiment.ID, experiment.NConsensus)
}

require 'retab'

client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])

# Bump consensus from 5 to 7
client.workflow_experiments.update(
  experiment_id: 'exp_abc',
  n_consensus: 7,
)

# Or rename only
client.workflow_experiments.update(
  experiment_id: 'exp_abc',
  name: 'Q1 invoices — v2',
)

use retab::enums::UpdateExperimentRequestNConsensus;
use retab::models::UpdateExperimentRequest;
use retab::resources::workflow_experiments::UpdateParams;
use retab::Retab;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Retab::new(std::env::var("RETAB_API_KEY")?);

    let body = UpdateExperimentRequest {
        n_consensus: Some(UpdateExperimentRequestNConsensus::V7),
        ..Default::default()
    };
    let experiment = client
        .workflows()
        .experiments()
        .update("exp_abc", UpdateParams::new(body))
        .await?;
    println!("{}", experiment.id);
    Ok(())
}

<?php
require 'vendor/autoload.php';

use Retab\Client;

$client = new Client(apiKey: getenv('RETAB_API_KEY'));

$result = $client->workflowExperiments()->update(
    experimentId: 'exp_abc123',
);
print_r($result);

using Retab;
using RetabClient = Retab.Retab;

var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);

var result = await client.Workflows.Experiments.UpdateAsync("exp_abc123", new WorkflowExperimentsUpdateOptions());
Console.WriteLine(result);

import com.retab.RetabClient;

public final class Example {
  public static void main(String[] args) throws Exception {
    RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));

    var result = client.workflows().experiments().update("exp_abc123", null, null, null, "Invoice Processing");
    System.out.println(result);
  }
}

curl -X 'PATCH' \
  'https://api.retab.com/v1/workflows/experiments/exp_abc' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your-api-key>' \
  -d '{"n_consensus": 7}'

{
  "id": "exp_abc",
  "workflow_id": "wf_abc123",
  "block_id": "extract-invoice",
  "block_kind": "extract",
  "n_consensus": 7,
  "document_count": 12,
  "name": "Q1 invoices",
  "last_run_id": "exprun_1",
  "status": "completed",
  "score": 0.87,
  "is_stale": true,
  "schema_drift": "none",
  "schema_drift_detail": null,
  "created_at": "2026-05-01T14:30:00Z",
  "updated_at": "2026-05-02T11:00:00Z"
}

{
  "detail": "No fields to update."
}

Patch the name, document set, or n_consensus of an experiment. Only fields included in the body are updated — omit a field to leave it untouched.

Changing the document set (document_captures / documents) or n_consensus invalidates existing metrics. Call Run Experiment afterwards to recompute.

from retab import Retab

client = Retab()

# Bump consensus from 5 to 7
client.workflows.experiments.update(
    experiment_id="exp_abc",
    n_consensus=7,
)

# Or rename only
client.workflows.experiments.update(
    experiment_id="exp_abc",
    name="Q1 invoices — v2",
)

import { Retab } from "@retab/node";

const client = new Retab({ apiKey: process.env.RETAB_API_KEY });

await client.workflows.experiments.update("exp_abc", undefined, undefined, 7);

package main

import (
	"context"
	"fmt"
	"log"

	retab "github.com/retab-dev/retab/clients/go"
)

func ptr[T any](v T) *T { return &v }

func main() {
	ctx := context.Background()
	nConsensus := retab.UpdateExperimentRequestNConsensus(retab.CreateExperimentRequestNConsensus7)

	client, err := retab.NewClient("")
	if err != nil {
		log.Fatal(err)
	}

	experiment, err := client.Workflows.Experiments.Update(
		ctx,
		"exp_abc",
		&retab.WorkflowExperimentsUpdateParams{NConsensus: &nConsensus},
	)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(experiment.ID, experiment.NConsensus)
}

require 'retab'

client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])

# Bump consensus from 5 to 7
client.workflow_experiments.update(
  experiment_id: 'exp_abc',
  n_consensus: 7,
)

# Or rename only
client.workflow_experiments.update(
  experiment_id: 'exp_abc',
  name: 'Q1 invoices — v2',
)

use retab::enums::UpdateExperimentRequestNConsensus;
use retab::models::UpdateExperimentRequest;
use retab::resources::workflow_experiments::UpdateParams;
use retab::Retab;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Retab::new(std::env::var("RETAB_API_KEY")?);

    let body = UpdateExperimentRequest {
        n_consensus: Some(UpdateExperimentRequestNConsensus::V7),
        ..Default::default()
    };
    let experiment = client
        .workflows()
        .experiments()
        .update("exp_abc", UpdateParams::new(body))
        .await?;
    println!("{}", experiment.id);
    Ok(())
}

<?php
require 'vendor/autoload.php';

use Retab\Client;

$client = new Client(apiKey: getenv('RETAB_API_KEY'));

$result = $client->workflowExperiments()->update(
    experimentId: 'exp_abc123',
);
print_r($result);

using Retab;
using RetabClient = Retab.Retab;

var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);

var result = await client.Workflows.Experiments.UpdateAsync("exp_abc123", new WorkflowExperimentsUpdateOptions());
Console.WriteLine(result);

import com.retab.RetabClient;

public final class Example {
  public static void main(String[] args) throws Exception {
    RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));

    var result = client.workflows().experiments().update("exp_abc123", null, null, null, "Invoice Processing");
    System.out.println(result);
  }
}

curl -X 'PATCH' \
  'https://api.retab.com/v1/workflows/experiments/exp_abc' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your-api-key>' \
  -d '{"n_consensus": 7}'

{
  "id": "exp_abc",
  "workflow_id": "wf_abc123",
  "block_id": "extract-invoice",
  "block_kind": "extract",
  "n_consensus": 7,
  "document_count": 12,
  "name": "Q1 invoices",
  "last_run_id": "exprun_1",
  "status": "completed",
  "score": 0.87,
  "is_stale": true,
  "schema_drift": "none",
  "schema_drift_detail": null,
  "created_at": "2026-05-01T14:30:00Z",
  "updated_at": "2026-05-02T11:00:00Z"
}

{
  "detail": "No fields to update."
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

experiment_id

string

required

Body

application/json

Body for updating an experiment. Only the supplied fields are changed.

document_captures

ExperimentDocumentCaptureRequest · object[] | null

Show child attributes

documents

ExplicitExperimentDocumentRequest · object[] | null

Show child attributes

n_consensus

enum<integer> | null

Available options:

3,

5,

7

name

string | null

Response

Successful Response

An experiment that evaluates a workflow block against a set of documents, with its latest run status and score.

string

required

workflow_id

string

required

block_id

string

required

n_consensus

enum<integer>

required

Available options:

3,

5,

7

name

string

required

block_type

enum<string>

required

Available options:

extract,

classifier,

split,

for_each

document_count

integer

default:0

last_run_id

string | null

created_at

string<date-time>

When the experiment was created

updated_at

string<date-time>

When the experiment was last updated

status

enum<string>

default:draft

Available options:

draft,

processing,

completed,

failed,

cancelled

score

number | null

is_stale

boolean

default:false

freshness

ArtifactFreshness · object

Show child attributes

schema_drift

enum<string>

default:unknown

Available options:

none,

partial,

drifted,

unknown

schema_drift_detail

string | null

drift

ArtifactDrift · object

Show child attributes