Skip to content
Navigation

Get or create a participant's assignment

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

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.

Query parameters

  • create_if_none
    optional
    boolean

    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
    optional
    integer

    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

Returns

200

Successful Response

JSON
  • experiment_id
    string
    required
  • participant_id
    string
    required
  • assignment
    required

    Null if no assignment. Strata are not included.

    Any of the following:

    • Assignment
      • arm_id
        string
        required

        ID of the arm this participant was assigned to. Same as Arm.arm_id.

      • 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
        string
        required

        The arm this participant was assigned to. Same as Arm.arm_name.

        maxLength: 100
      • cluster_key
        optional

        Cluster identifier for this participant. Present for cluster-randomized preassigned experiments.

        Any of the following:

        • string
        • null
      • created_at
        optional

        The date and time the assignment was created.

        Any of the following:

        • string
        • null
      • strata
        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
            string
            required
            maxLength: 300 · minLength: 1
          • strata_value
            optional

            Any of the following:

            • string
            • null
        • null
      • observed_at
        optional

        The date and time the outcome was recorded.

        Any of the following:

        • string
        • null
      • outcome
        optional

        The observed outcome for this assignment.

        Any of the following:

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

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