List assign

The variant one subject is bucketed into, and the payload that variant carries.

GET /v1/experiment/{id}/assign

Experiment → · All API references → · Get started →

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

The variant one subject is bucketed into, and the payload that variant carries.

The bucketing is a deterministic hash of the subject, so the same subject gets the same arm on every call for as long as the flag definition is unchanged — and this is a pure READ: it records nothing. In particular it does NOT record an exposure. The caller's SDK must emit the experiment's exposure event itself, or the analysis has an empty denominator and every arm measures zero.

An empty variant with on false is not an error — it means the flag returned nothing for this subject, so the subject is not enrolled. A flags engine that is unavailable refuses rather than defaulting to an arm. Requires a validated principal, and the experiment must exist in the caller's org and project.

Request

3 fields.

Field	In	Type	Required	Description
`id`	path	string	yes	ID is the experiment the URL names.
`subject`	query	string	yes	Subject is the unit to bucket — a user, org, session or audience key, matching the experiment's subjectKind.
`props`	query	string	—	Props is a JSON object of person properties for targeting.

Response

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

200 body — 5 fields.

Field	In	Type	Always	Description
`experiment`	body	string	—	Trial is the experiment that was evaluated.
`on`	body	boolean	—	On is false when the flag returned nothing for this subject, which means the subject is not enrolled — not an error.
`payload`	body	any	—	Payload is the opaque JSON the winning arm carries, which the caller interprets: a feature config, an ad-creative id, a subject line, a model id.
`subject`	body	string	—	Subject is the unit that was bucketed.
`variant`	body	string	—	Arm is the arm the subject falls in, empty when the flag enrolled it in none.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo experiment assign <id> --subject <subject>

.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.getExperimentByIdAssign({ id: 'id', subject: 'subject' });

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_assign(id='id', subject='subject')

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

resp, _, err := client.ExperimentAPI.GetExperimentByIdAssign(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_assign(&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).getExperimentByIdAssign();

curl https://api.hanzo.ai/v1/experiment/<id>/assign?subject=%3Csubject%3E \
  -H "Authorization: Bearer $HANZO_API_KEY"

MCP reaches experiment through the experiment tool, which names its 7 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_experiments"
         }
       }
     }'

Experiment API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousCreate exec NextGet experiment