---
title: "Record a bandit arm outcome for a participant"
---

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

# Record a bandit arm outcome for a participant

Path: Evidential Experiments API › Outcomes

`POST /v1/experiments/{experiment_id}/assignments/{participant_id}/outcome`

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

Records the outcome for a participant's assigned arm and returns the updated arm parameters.

Use this in push integrations to report each outcome as it happens. Applies only to MAB or
CMAB experiments using push-based integrations.

Prerequisites:
- The experiment must record outcomes through this API. Experiments of type `mab_online_dwh`
  use the pull integration, where Evidential reads outcomes from a connected data warehouse,
  and they reject this call.
- The participant must already have an assignment. Create one with the GET assignment endpoint
  first.
- The participant must not already have a recorded outcome. Use the GET assignment endpoint to
  check whether an outcome is already recorded.

The endpoint returns a 422 error if a prerequisite is not met.

## Authentication

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

## Path parameters

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

## Request body

_Required._

- `outcome` (`update_bandit_arm_with_participant_outcome.outcome`; number, required)

## Example request

```json
{
  "outcome": 0
}
```

## Code samples

### cURL

```bash
curl --request POST \
  --url 'https://api.evidential.dev/v1/experiments/<experiment_id>/assignments/<participant_id>/outcome' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{
  "outcome": 0
}'
```

### TypeScript

```typescript
const url = 'https://api.evidential.dev/v1/experiments/<experiment_id>/assignments/<participant_id>/outcome';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', 'X-API-Key': '<X-API-Key>'},
  body: JSON.stringify({outcome: 0})
};

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>/outcome"

payload = { "outcome": 0 }
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "<X-API-Key>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

## Responses

### 200

Successful Response

#### Example

```json
{
  "arm_id": "string",
  "arm_name": "string",
  "arm_description": "string",
  "arm_weight": 99,
  "alpha_init": null,
  "beta_init": null,
  "mu_init": null,
  "sigma_init": null,
  "alpha": null,
  "beta": null,
  "mu": null,
  "covariance": null
}
```

- `arm_name` (`update_bandit_arm_with_participant_outcome.response.200.arm_name`; string, required)
  - maxLength: `100`
- `arm_id` (`update_bandit_arm_with_participant_outcome.response.200.arm_id`; any of, optional) — Unique ID of the arm. Leave unset when creating an arm.
  - any of the following: `string`, `null`
- `arm_description` (`update_bandit_arm_with_participant_outcome.response.200.arm_description`; any of, optional)
  - any of the following: `string`, `null`
- `arm_weight` (`update_bandit_arm_with_participant_outcome.response.200.arm_weight`; any of, optional) — Optional weight for this arm, used for unequal allocation. The weight must be greater than 0 and less than 100. If you set a weight, all arms must have weights, and they must sum to 100.
  - any of the following: `ArmWeight`, `null`
- `alpha_init` (`update_bandit_arm_with_participant_outcome.response.200.alpha_init`; any of, optional) — Initial alpha parameter for the Beta prior.
  - any of the following: `number`, `null`
- `beta_init` (`update_bandit_arm_with_participant_outcome.response.200.beta_init`; any of, optional) — Initial beta parameter for the Beta prior.
  - any of the following: `number`, `null`
- `mu_init` (`update_bandit_arm_with_participant_outcome.response.200.mu_init`; any of, optional) — Initial mean parameter for the Normal prior.
  - any of the following: `number`, `null`
- `sigma_init` (`update_bandit_arm_with_participant_outcome.response.200.sigma_init`; any of, optional) — Initial standard deviation parameter for the Normal prior.
  - any of the following: `number`, `null`
- `alpha` (`update_bandit_arm_with_participant_outcome.response.200.alpha`; any of, optional) — Updated alpha parameter for the Beta prior.
  - any of the following: `number`, `null`
- `beta` (`update_bandit_arm_with_participant_outcome.response.200.beta`; any of, optional) — Updated beta parameter for the Beta prior.
  - any of the following: `number`, `null`
- `mu` (`update_bandit_arm_with_participant_outcome.response.200.mu`; any of, optional) — Updated mean vector for the Normal prior.
  - any of the following: `array<number>`, `null`
- `covariance` (`update_bandit_arm_with_participant_outcome.response.200.covariance`; any of, optional) — Updated covariance matrix for the Normal prior.
  - any of the following: `array<array<number>>`, `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` (`update_bandit_arm_with_participant_outcome.response.422.detail`; array of object, optional)
  - `loc` (`update_bandit_arm_with_participant_outcome.response.422.detail.loc`; array\<any of\>, required)
    - any of the following: `string`, `integer`
  - `msg` (`update_bandit_arm_with_participant_outcome.response.422.detail.msg`; string, required)
  - `type` (`update_bandit_arm_with_participant_outcome.response.422.detail.type`; string, required)
  - `input` (`update_bandit_arm_with_participant_outcome.response.422.detail.input`; unknown, optional)
  - `ctx` (`update_bandit_arm_with_participant_outcome.response.422.detail.ctx`; object, optional)


Source: https://docs.evidential.dev/api/outcomes/record/index.md
