---
title: List bandit policies
description: List the policies a bandit has served, newest first by default, including the policy it serves after it ends.
breadcrumbs: Docs > API > List bandit policies
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# List bandit policies

{% callout %}
This product or feature is not supported for the following sites: app.ddog-gov.com, us2.ddog-gov.com
{% /callout %}

## v2 (latest)

{% alert level="warning" %}
**Note**: This endpoint is in preview and is subject to change.
If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help.md).
{% /alert %}

| Datadog site      | API endpoint                                                                      |
| ----------------- | --------------------------------------------------------------------------------- |
| app.datadoghq.com | GET https://api.datadoghq.com/api/v2/experiments/bandits/{bandit_id}/policies     |
| us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/experiments/bandits/{bandit_id}/policies |
| us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/experiments/bandits/{bandit_id}/policies |
| app.datadoghq.eu  | GET https://api.datadoghq.eu/api/v2/experiments/bandits/{bandit_id}/policies      |
| ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/experiments/bandits/{bandit_id}/policies |
| ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/experiments/bandits/{bandit_id}/policies |
| uk1.datadoghq.com | GET https://api.uk1.datadoghq.com/api/v2/experiments/bandits/{bandit_id}/policies |
| app.ddog-gov.com  | GET https://api.ddog-gov.com/api/v2/experiments/bandits/{bandit_id}/policies      |
| us2.ddog-gov.com  | GET https://api.us2.ddog-gov.com/api/v2/experiments/bandits/{bandit_id}/policies  |

### Overview

List the policies a bandit has served, newest first by default, including the policy it serves after it ends. Each policy is the traffic split SDKs served from when it was applied until the next one. Exposures log the policy's ID as `bandit.policy_id`, so the history tells you the split behind each exposure. Exposures logged after the bandit ends have no policy ID. `filter[from]` and `filter[to]` keep the policies in effect during the range, including the one already in effect at `filter[from]`. Bandits must be enabled for the organization.

This endpoint requires the `product_analytics_experiments_read` permission.

OAuth apps require the `product_analytics_experiments_read` authorization [scope](https://docs.datadoghq.com/api/latest/scopes.md#experiments) to access this endpoint.

### Arguments

#### Path Parameters

| Field                  | Type   | Description             |
| ---------------------- | ------ | ----------------------- |
| bandit_id [*required*] | string | The UUID of the bandit. |

#### Query Strings

| Field        | Type    | Description                                                                                                                                                                                 |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filter[from] | string  | Return only the policies in effect at or after this RFC 3339 time (inclusive), including the one already in effect at it.                                                                   |
| filter[to]   | string  | Return only the policies applied before this RFC 3339 time (exclusive).                                                                                                                     |
| page[offset] | integer | Number of results to skip for pagination. Defaults to 0 when omitted.                                                                                                                       |
| page[limit]  | integer | Maximum number of results to return. Defaults to 25 when omitted, and is capped at 50 (larger values are clamped to 50). The response includes meta.page (with total) and pagination links. |
| sort         | string  | `applied_at` for oldest first, or `-applied_at` for newest first. Defaults to `-applied_at`.                                                                                                |

### Response

{% tabs %}
{% tab label="200" %}
OK

{% tabs %}
{% tab label="Model" %}
Response containing a page of a bandit's policy history.

| Parent field | Field                                | Type      | Description                                                                                                                                                                                                  |
| ------------ | ------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|              | data [*required*]                    | [object]  | Policies on this page.                                                                                                                                                                                       |
| data         | attributes [*required*]              | object    | A traffic split the bandit served, with the same fields as `active_policy`.                                                                                                                                  |
| attributes   | applied_at [*required*]              | date-time | When the policy was saved. SDKs pick it up on their next configuration fetch.                                                                                                                                |
| attributes   | config_version [*required*]          | int64     | The configuration version the policy was made for.                                                                                                                                                           |
| attributes   | is_active [*required*]               | boolean   | Whether this is the policy the bandit serves now, the one Get bandit returns as `active_policy`. A paused bandit keeps serving it, and an ended bandit serves its fallback.                                  |
| attributes   | kind [*required*]                    | enum      | `WARMUP` serves the arms equally. `ADAPTIVE` serves the initial split or a split from a refresh. `FALLBACK` serves one variant after the bandit ends. Allowed enum values: `WARMUP`, `ADAPTIVE`, `FALLBACK`. |
| attributes   | policy_number [*required*]           | int64     | The policy's place in the bandit's policy history. It follows `applied_at` and orders policies saved at the same time.                                                                                       |
| attributes   | reason [*required*]                  | enum      | Why the policy was applied. Allowed enum values: `ACTIVATION`, `REFRESH`, `ARM_CHANGE`, `SCHEDULED_END`, `STOP`.                                                                                             |
| attributes   | refresh_id [*required*]              | uuid      | The refresh that proposed the policy. `null` for policies no refresh proposed, such as the first split and the policy served after the bandit ends.                                                          |
| attributes   | variants [*required*]                | [object]  | Each variant's share of traffic. The probabilities add up to 1. A variant served as an arm keeps the key the arm had, even if the arm was removed later.                                                     |
| variants     | feature_flag_variant_id [*required*] | uuid      | The variant's ID on the flag.                                                                                                                                                                                |
| variants     | probability [*required*]             | double    | The share of traffic the variant gets, from 0 to 1.                                                                                                                                                          |
| variants     | variant_key [*required*]             | string    | The variant's key. `null` when it can't be resolved.                                                                                                                                                         |
| data         | id [*required*]                      | uuid      | The policy ID. Each exposure logs it as `bandit.policy_id`, except exposures logged after the bandit ends.                                                                                                   |
| data         | type [*required*]                    | enum      | Bandit policy resource type. Allowed enum values: `bandit-policies`. Default: `bandit-policies`.                                                                                                             |
|              | links [*required*]                   | object    | Links for navigating a paginated result set.                                                                                                                                                                 |
| links        | first                                | string    | URL of the first page of results.                                                                                                                                                                            |
| links        | last                                 | string    | URL of the last page of results.                                                                                                                                                                             |
| links        | next                                 | string    | URL of the next page of results.                                                                                                                                                                             |
| links        | prev                                 | string    | URL of the previous page of results.                                                                                                                                                                         |
| links        | self                                 | string    | URL of the current page of results.                                                                                                                                                                          |
|              | meta [*required*]                    | object    | Pagination information for a list response.                                                                                                                                                                  |
| meta         | page                                 | object    | Result counts and offsets for a page of results.                                                                                                                                                             |
| page         | first_offset                         | int64     | Offset of the first page of results.                                                                                                                                                                         |
| page         | last_offset                          | int64     | Offset of the last page of results.                                                                                                                                                                          |
| page         | limit                                | int64     | Maximum number of results returned in one page.                                                                                                                                                              |
| page         | next_offset                          | int64     | Offset of the next page of results.                                                                                                                                                                          |
| page         | offset                               | int64     | Number of results skipped before this page.                                                                                                                                                                  |
| page         | prev_offset                          | int64     | Offset of the previous page of results.                                                                                                                                                                      |
| page         | total                                | int64     | Total number of matching results across all pages.                                                                                                                                                           |
| page         | type                                 | string    | Pagination method used for this result set.                                                                                                                                                                  |
{% /tab %}

{% tab label="Example" %}
```json
{
  "data": [
    {
      "attributes": {
        "applied_at": "2026-10-30T02:15:00Z",
        "config_version": 2,
        "is_active": true,
        "kind": "ADAPTIVE",
        "policy_number": 9,
        "reason": "REFRESH",
        "refresh_id": "bb0e8400-e29b-41d4-a716-446655440000",
        "variants": [
          {
            "feature_flag_variant_id": "770e8400-e29b-41d4-a716-446655440001",
            "probability": 0.3,
            "variant_key": "blue"
          }
        ]
      },
      "id": "dd0e8400-e29b-41d4-a716-446655440000",
      "type": "bandit-policies"
    }
  ],
  "links": {
    "first": "string",
    "last": "string",
    "next": "string",
    "prev": "string",
    "self": "string"
  },
  "meta": {
    "page": {
      "first_offset": "integer",
      "last_offset": "integer",
      "limit": "integer",
      "next_offset": "integer",
      "offset": "integer",
      "prev_offset": "integer",
      "total": "integer",
      "type": "string"
    }
  }
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="400" %}
Malformed bandit ID (not a valid UUID), a sort other than `applied_at` or `-applied_at`, a malformed page parameter, `filter[from]` or `filter[to]` isn't an RFC 3339 time, or `filter[from]` isn't before `filter[to]`.

{% tabs %}
{% tab label="Model" %}
API error response.

| Parent field | Field               | Type     | Description                                                                     |
| ------------ | ------------------- | -------- | ------------------------------------------------------------------------------- |
|              | errors [*required*] | [object] | A list of errors.                                                               |
| errors       | code                | string   | An application-specific error code.                                             |
| errors       | detail              | string   | A human-readable explanation specific to this occurrence of the error.          |
| errors       | meta                | object   | Non-standard meta-information about the error                                   |
| errors       | source              | object   | References to the source of the error.                                          |
| source       | header              | string   | A string indicating the name of a single request header which caused the error. |
| source       | parameter           | string   | A string indicating which URI query parameter caused the error.                 |
| source       | pointer             | string   | A JSON pointer to the value in the request document that caused the error.      |
| errors       | status              | string   | Status code of the response.                                                    |
| errors       | title               | string   | Short human-readable summary of the error.                                      |
{% /tab %}

{% tab label="Example" %}
```json
{
  "errors": [
    {
      "code": "invalid_request",
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="401" %}
Missing or invalid authentication (dd-api-key + dd-application-key headers, or a valid user session).

{% tabs %}
{% tab label="Model" %}
API error response.

| Parent field | Field               | Type     | Description                                                                     |
| ------------ | ------------------- | -------- | ------------------------------------------------------------------------------- |
|              | errors [*required*] | [object] | A list of errors.                                                               |
| errors       | code                | string   | An application-specific error code.                                             |
| errors       | detail              | string   | A human-readable explanation specific to this occurrence of the error.          |
| errors       | meta                | object   | Non-standard meta-information about the error                                   |
| errors       | source              | object   | References to the source of the error.                                          |
| source       | header              | string   | A string indicating the name of a single request header which caused the error. |
| source       | parameter           | string   | A string indicating which URI query parameter caused the error.                 |
| source       | pointer             | string   | A JSON pointer to the value in the request document that caused the error.      |
| errors       | status              | string   | Status code of the response.                                                    |
| errors       | title               | string   | Short human-readable summary of the error.                                      |
{% /tab %}

{% tab label="Example" %}
```json
{
  "errors": [
    {
      "code": "invalid_request",
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="403" %}
Bandits are not enabled for the organization, or the caller lacks the product_analytics_experiments_read permission.

{% tabs %}
{% tab label="Model" %}
API error response.

| Parent field | Field               | Type     | Description                                                                     |
| ------------ | ------------------- | -------- | ------------------------------------------------------------------------------- |
|              | errors [*required*] | [object] | A list of errors.                                                               |
| errors       | code                | string   | An application-specific error code.                                             |
| errors       | detail              | string   | A human-readable explanation specific to this occurrence of the error.          |
| errors       | meta                | object   | Non-standard meta-information about the error                                   |
| errors       | source              | object   | References to the source of the error.                                          |
| source       | header              | string   | A string indicating the name of a single request header which caused the error. |
| source       | parameter           | string   | A string indicating which URI query parameter caused the error.                 |
| source       | pointer             | string   | A JSON pointer to the value in the request document that caused the error.      |
| errors       | status              | string   | Status code of the response.                                                    |
| errors       | title               | string   | Short human-readable summary of the error.                                      |
{% /tab %}

{% tab label="Example" %}
```json
{
  "errors": [
    {
      "code": "invalid_request",
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="404" %}
No bandit with this ID exists for the organization.

{% tabs %}
{% tab label="Model" %}
API error response.

| Parent field | Field               | Type     | Description                                                                     |
| ------------ | ------------------- | -------- | ------------------------------------------------------------------------------- |
|              | errors [*required*] | [object] | A list of errors.                                                               |
| errors       | code                | string   | An application-specific error code.                                             |
| errors       | detail              | string   | A human-readable explanation specific to this occurrence of the error.          |
| errors       | meta                | object   | Non-standard meta-information about the error                                   |
| errors       | source              | object   | References to the source of the error.                                          |
| source       | header              | string   | A string indicating the name of a single request header which caused the error. |
| source       | parameter           | string   | A string indicating which URI query parameter caused the error.                 |
| source       | pointer             | string   | A JSON pointer to the value in the request document that caused the error.      |
| errors       | status              | string   | Status code of the response.                                                    |
| errors       | title               | string   | Short human-readable summary of the error.                                      |
{% /tab %}

{% tab label="Example" %}
```json
{
  "errors": [
    {
      "code": "invalid_request",
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="429" %}
Too many requests

{% tabs %}
{% tab label="Model" %}
API error response.

| Field               | Type     | Description       |
| ------------------- | -------- | ----------------- |
| errors [*required*] | [string] | A list of errors. |
{% /tab %}

{% tab label="Example" %}
```json
{
  "errors": [
    "Bad Request"
  ]
}
```
{% /tab %}
{% /tabs %}
{% /tab %}
{% /tabs %}

### Code Example

{% tabs %}
{% tab label="Curl" %}
```bash
# Path parameters
export bandit_id="4b1f3c2e-8d5a-4f6b-9c7e-1a2b3c4d5e6f"

# Set your Datadog site and credentials
export DD_SITE="datadoghq.com" # Or us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com, ddog-gov.com, us2.ddog-gov.com
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/experiments/bandits/${bandit_id}/policies" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
```
{% /tab %}
{% /tabs %}
