# List assign

URL: https://docs.hanzo.ai/docs/openapi/experiment/get-experiment-by-id-assign

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

`GET /v1/experiment/{id}/assign`

> [Experiment →](https://docs.hanzo.ai/docs/openapi/experiment) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides)

|               |                                                  |
| ------------- | ------------------------------------------------ |
| **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](https://docs.hanzo.ai/docs/errors).

## Examples

**CLI**

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

**SDK**

**.ts**

```ts
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' });
```

**.py**

```python
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')
```

**.go**

```go
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
}
```

**.rs**

```rust
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?;
```

**.java**

```java
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();
```

**HTTP**

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

**MCP**

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:

```bash
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](https://docs.hanzo.ai/docs/openapi/experiment) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)