Skip to content
Navigation

Record a bandit arm outcome for a participant

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

Authorization

  • DatasourceApiKey
    API key in header
    required

    X-API-Key: <token>

Path parameters

  • participant_id
    string
    required

    Your application's identifier for the participant.

  • experiment_id
    string
    required

    The ID of the experiment to fetch.

Request body JSON required

  • outcome
    number
    required

Returns

200

Successful Response

JSON
  • arm_name
    string
    required
    maxLength: 100
  • arm_id
    optional

    Unique ID of the arm. Leave unset when creating an arm.

    Any of the following:

    • string
    • null
  • arm_description
    optional

    Any of the following:

    • string
    • null
  • arm_weight
    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
    optional

    Initial alpha parameter for the Beta prior.

    Any of the following:

    • number
    • null
  • beta_init
    optional

    Initial beta parameter for the Beta prior.

    Any of the following:

    • number
    • null
  • mu_init
    optional

    Initial mean parameter for the Normal prior.

    Any of the following:

    • number
    • null
  • sigma_init
    optional

    Initial standard deviation parameter for the Normal prior.

    Any of the following:

    • number
    • null
  • alpha
    optional

    Updated alpha parameter for the Beta prior.

    Any of the following:

    • number
    • null
  • beta
    optional

    Updated beta parameter for the Beta prior.

    Any of the following:

    • number
    • null
  • mu
    optional

    Updated mean vector for the Normal prior.

    Any of the following:

    • array<number>
    • null
  • covariance
    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.

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.

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.

422

Validation Error
JSON
  • detail
    optional
    array of
    object
    • loc
      array of
      required

      Any of the following:

      • string
      • integer
    • msg
      string
      required
    • type
      string
      required
    • input
      optional
      unknown
    • ctx
      optional
      object

Type to search…

↑↓ navigate↵ selectEsc close