---
title: "List an experiment's assignments"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.evidential.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# List an experiment's assignments

Path: Evidential Experiments API › Assignments

`GET /v1/experiments/{experiment_id}/assignments`

URL: `https://api.evidential.dev/v1/experiments/{experiment_id}/assignments`

## Authentication

- `DatasourceApiKey`, apiKey, in header, header `X-API-Key`

## Path parameters

- `experiment_id` (`get_experiment_assignments.path.experiment_id`; string, required) — The ID of the experiment to fetch.

## Code samples

### cURL

```bash
curl --request GET \
  --url 'https://api.evidential.dev/v1/experiments/<experiment_id>/assignments' \
  --header 'X-API-Key: <X-API-Key>'
```

### TypeScript

```typescript
const url = 'https://api.evidential.dev/v1/experiments/<experiment_id>/assignments';
const options = {method: 'GET', headers: {'X-API-Key': '<X-API-Key>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://api.evidential.dev/v1/experiments/<experiment_id>/assignments"

headers = {"X-API-Key": "<X-API-Key>"}

response = requests.get(url, headers=headers)

print(response.text)
```

## Responses

### 200

Successful Response

#### Example

```json
{
  "balance_check": {
    "f_statistic": 0,
    "numerator_df": 0,
    "denominator_df": 0,
    "p_value": 0,
    "balance_ok": true
  },
  "experiment_id": "string",
  "sample_size": 0,
  "assignments": [
    {
      "arm_id": "string",
      "participant_id": "string",
      "cluster_key": "string",
      "arm_name": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "strata": [
        {
          "field_name": "field_name",
          "strata_value": "string"
        }
      ],
      "observed_at": "2019-08-24T14:15:22Z",
      "outcome": 0,
      "autofailed_outcome": true,
      "context_values": [
        0
      ]
    }
  ]
}
```

- `experiment_id` (`get_experiment_assignments.response.200.experiment_id`; string, required)
- `sample_size` (`get_experiment_assignments.response.200.sample_size`; integer, required)
- `assignments` (`get_experiment_assignments.response.200.assignments`; array of object, required)
  - `arm_id` (`get_experiment_assignments.response.200.assignments.arm_id`; string, required) — ID of the arm this participant was assigned to. Same as Arm.arm_id.
  - `participant_id` (`get_experiment_assignments.response.200.assignments.participant_id`; string, required) — Unique identifier for the participant. This is the primary key for the participant in the data warehouse.
    - maxLength: `64`
  - `arm_name` (`get_experiment_assignments.response.200.assignments.arm_name`; string, required) — The arm this participant was assigned to. Same as Arm.arm_name.
    - maxLength: `100`
  - `cluster_key` (`get_experiment_assignments.response.200.assignments.cluster_key`; any of, optional) — Cluster identifier for this participant. Present for cluster-randomized preassigned experiments.
    - any of the following: `string`, `null`
  - `created_at` (`get_experiment_assignments.response.200.assignments.created_at`; any of, optional) — The date and time the assignment was created.
    - any of the following: `string`, `null`
  - `strata` (`get_experiment_assignments.response.200.assignments.strata`; any of, optional) — List of properties and their values for this participant used for stratification or tracking metrics. If stratification is not used, this will be None.
    - any of the following:
      - `array<unknown>`
        - `field_name` (`get_experiment_assignments.response.200.assignments.strata.1.field_name`; string, required)
          - maxLength: `300` · minLength: `1`
        - `strata_value` (`get_experiment_assignments.response.200.assignments.strata.1.strata_value`; any of, optional)
          - any of the following: `string`, `null`
      - `null`
  - `observed_at` (`get_experiment_assignments.response.200.assignments.observed_at`; any of, optional) — The date and time the outcome was recorded.
    - any of the following: `string`, `null`
  - `outcome` (`get_experiment_assignments.response.200.assignments.outcome`; any of, optional) — The observed outcome for this assignment.
    - any of the following: `number`, `null`
  - `autofailed_outcome` (`get_experiment_assignments.response.200.assignments.autofailed_outcome`; any of, optional) — Whether Evidential failed this outcome automatically (true) or a real outcome was observed (false). Null if no outcome was recorded.
    - any of the following: `boolean`, `null`
  - `context_values` (`get_experiment_assignments.response.200.assignments.context_values`; any of, optional) — List of context values for this assignment. If no contexts are used, this will be None.
    - any of the following: `array<number>`, `null`
- `balance_check` (`get_experiment_assignments.response.200.balance_check`; any of, optional) — Balance test results if available. Online experiments do not have balance checks.
  - any of the following:
    - `BalanceCheck`
      - `f_statistic` (`BalanceCheck.f_statistic`; number, required) — F-statistic testing the overall significance of the model predicting treatment assignment.
      - `numerator_df` (`BalanceCheck.numerator_df`; integer, required) — The numerator degrees of freedom for the f-statistic related to number of dependent variables.
      - `denominator_df` (`BalanceCheck.denominator_df`; integer, required) — Denominator degrees of freedom related to the number of observations.
      - `p_value` (`BalanceCheck.p_value`; number, required) — Probability of observing these data if the strata do not predict treatment assignment. A high value means the randomization is balanced.
      - `balance_ok` (`BalanceCheck.balance_ok`; boolean, required) — Whether the p-value for our observed f_statistic is greater than the f-stat threshold specified in our design specification. (See DesignSpec.fstat_thresh)
    - `null`

### 400

The request is invalid. Check that the request body matches the required structure and that all required fields and headers are present.

#### Example

```json
{}
```

### 403

You did not provide a valid API key, or your API key does not have permission for this operation.

Tip: Check that the API key in the `X-API-Key` header has access to the data source or experiment.

#### Example

```json
{}
```

### 404

The resource was not found, or you do not have access to it.

Tip: Check that the API key in the `X-API-Key` header has access to the data source or experiment.

#### Example

```json
{}
```

### 422

Validation Error

#### Example

```json
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
```

- `detail` (`get_experiment_assignments.response.422.detail`; array of object, optional)
  - `loc` (`get_experiment_assignments.response.422.detail.loc`; array\<any of\>, required)
    - any of the following: `string`, `integer`
  - `msg` (`get_experiment_assignments.response.422.detail.msg`; string, required)
  - `type` (`get_experiment_assignments.response.422.detail.type`; string, required)
  - `input` (`get_experiment_assignments.response.422.detail.input`; unknown, optional)
  - `ctx` (`get_experiment_assignments.response.422.detail.ctx`; object, optional)


Source: https://docs.evidential.dev/api/assignments/list/index.md
