---
title: "Get or create a participant's assignment"
---

> 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.

# Get or create a participant's assignment

Path: Evidential Experiments API › Assignments

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

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

Gets or creates an arm assignment for a participant. The behavior depends on the experiment type:

- Preassigned A/B experiments: returns the assignment if one exists. `create_if_none` is ignored.
- Online A/B and Multi-armed Bandit experiments: returns the existing assignment, or creates one
  when `create_if_none` is true.
- Contextual Multi-armed Bandit (CMAB) experiments: returns the assignment if one exists. To create
  a new assignment, use the `assign_cmab` endpoint, which accepts the required context values.

## Authentication

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

## Path parameters

- `participant_id` (`get_assignment.path.participant_id`; string, required) — Your application's identifier for the participant.
- `experiment_id` (`get_assignment.path.experiment_id`; string, required) — The ID of the experiment to fetch.

## Query parameters

- `create_if_none` (`get_assignment.query.create_if_none`; boolean, optional) — Create an assignment if none exists. Set to false to check for an existing assignment without creating one. Ignored for preassigned experiments.
  - default: `true`
- `max_age` (`get_assignment.query.max_age`; integer, optional) — Sets the Cache-Control max-age, in seconds, for Preassigned A/B and Online A/B experiments. Set to 0 to disable caching.
  - maximum: `86400` · minimum: `0` · default: `3600`

## Code samples

### cURL

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

### TypeScript

```typescript
const url = 'https://api.evidential.dev/v1/experiments/<experiment_id>/assignments/<participant_id>';
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/<participant_id>"

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

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

print(response.text)
```

## Responses

### 200

Successful Response

#### Example

```json
{
  "experiment_id": "string",
  "participant_id": "string",
  "assignment": {
    "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_assignment.response.200.experiment_id`; string, required)
- `participant_id` (`get_assignment.response.200.participant_id`; string, required)
- `assignment` (`get_assignment.response.200.assignment`; any of, required) — Null if no assignment. Strata are not included.
  - any of the following:
    - `Assignment`
      - `arm_id` (`Assignment.arm_id`; string, required) — ID of the arm this participant was assigned to. Same as Arm.arm_id.
      - `participant_id` (`Assignment.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` (`Assignment.arm_name`; string, required) — The arm this participant was assigned to. Same as Arm.arm_name.
        - maxLength: `100`
      - `cluster_key` (`Assignment.cluster_key`; any of, optional) — Cluster identifier for this participant. Present for cluster-randomized preassigned experiments.
        - any of the following: `string`, `null`
      - `created_at` (`Assignment.created_at`; any of, optional) — The date and time the assignment was created.
        - any of the following: `string`, `null`
      - `strata` (`Assignment.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` (`Assignment.strata.1.field_name`; string, required)
              - maxLength: `300` · minLength: `1`
            - `strata_value` (`Assignment.strata.1.strata_value`; any of, optional)
              - any of the following: `string`, `null`
          - `null`
      - `observed_at` (`Assignment.observed_at`; any of, optional) — The date and time the outcome was recorded.
        - any of the following: `string`, `null`
      - `outcome` (`Assignment.outcome`; any of, optional) — The observed outcome for this assignment.
        - any of the following: `number`, `null`
      - `autofailed_outcome` (`Assignment.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` (`Assignment.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`
    - `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_assignment.response.422.detail`; array of object, optional)
  - `loc` (`get_assignment.response.422.detail.loc`; array\<any of\>, required)
    - any of the following: `string`, `integer`
  - `msg` (`get_assignment.response.422.detail.msg`; string, required)
  - `type` (`get_assignment.response.422.detail.type`; string, required)
  - `input` (`get_assignment.response.422.detail.input`; unknown, optional)
  - `ctx` (`get_assignment.response.422.detail.ctx`; object, optional)


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