Get experiment

One experiment's definition and lifecycle: variants, weights, control arm, status and winner.

GET /v1/experiment/{id}

Experiment → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/experiment/{id}`
Method	`GET`
Operation	`get_experiment_by_id`
Auth	`Authorization: Bearer $HANZO_API_KEY`

One experiment's definition and lifecycle: variants, weights, control arm, status and winner.

It reads the registry row only — the definition and the decision, never live measurements. Assignment lives in the flags plane and outcomes in analytics; this is the value that names both.

Scoped to the caller's org and project from the validated principal, so another tenant's experiment of the same id is simply not found. An id that is not a legal slug is answered the same way, without a store read — the shape check and the existence check are one answer, so neither leaks the other.

Request

1 field.

Field	In	Type	Required	Description
`id`	path	string	yes	ID is the experiment the URL names.

Response

Status	Body	Meaning
`200`	experiment.Trial	ok
`default`	problem-details	refused

200 body — 18 fields.

Field	In	Type	Always	Description
`createdAt`	body	string	—	when it started assigning
`createdBy`	body	string	—	the credential that registered it
`decidedAt`	body	string	—	when the promotion took effect
`decidedBy`	body	string	—	the credential that promoted the winner
`exposureEvent`	body	string	—	the event that enrols a subject — the analysis denominator
`flagKey`	body	string	—	the assignment flag this experiment drives
`id`	body	string	—	the experiment's slug, unique within the project
`metricEvent`	body	string	—	the event that counts as a conversion — the numerator
`name`	body	string	—	free text for a reader
`project`	body	string	—	the sub-scope within the org, stamped from the principal
`status`	body	string	—	running while it assigns and measures, decided once a winner is promoted
`subjectKind`	body	string	—	the unit assigned and measured: user, org, session or audience
`variants`	body	experiment.Arm[]	—	the arms, weighted, one of them the control
`variants[].control`	body	boolean	—	true on the baseline arm every other arm is compared to
`variants[].key`	body	string	—	the arm's slug, unique within the experiment
`variants[].payload`	body	any	—	opaque JSON the arm carries, which the consumer interprets
`variants[].weight`	body	number (double)	—	its share of the rollout; the arms sum to 100
`winner`	body	string	—	the arm promoted to the whole rollout

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo experiment get <id>

.ts

.py

.go

.rs

.java

import { Configuration, ExperimentApi } from 'hanzoai';

const api = new ExperimentApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getExperimentById({ id: 'id' });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import ExperimentApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = ExperimentApi(client).get_experiment_by_id(id='id')

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.ExperimentAPI.GetExperimentById(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, experiment_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = experiment_api::get_experiment_by_id(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.ExperimentApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new ExperimentApi(client).getExperimentById();

curl https://api.hanzo.ai/v1/experiment/<id> \
  -H "Authorization: Bearer $HANZO_API_KEY"

Tool experiment, op get_experiment_by_id — POST the JSON-RPC envelope to https://api.hanzo.ai/v1/mcp.

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "experiment",
         "arguments": {
           "op": "get_experiment_by_id",
           "input": {
             "id": "<id>"
           }
         }
       }
     }'

Experiment API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousList assign NextList health