---
title: List bandits
description: List the organization's bandits, newest first by default.
breadcrumbs: Docs > API > List bandits
---

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

# List bandits

{% 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     |
| us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/experiments/bandits |
| us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/experiments/bandits |
| app.datadoghq.eu  | GET https://api.datadoghq.eu/api/v2/experiments/bandits      |
| ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/experiments/bandits |
| ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/experiments/bandits |
| uk1.datadoghq.com | GET https://api.uk1.datadoghq.com/api/v2/experiments/bandits |
| app.ddog-gov.com  | GET https://api.ddog-gov.com/api/v2/experiments/bandits      |
| us2.ddog-gov.com  | GET https://api.us2.ddog-gov.com/api/v2/experiments/bandits  |

### Overview

List the organization's bandits, newest first by default. Each item is a summary. For a bandit's setup, active policy, and latest refresh, use Get bandit. 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

#### Query Strings

| Field                   | Type    | Description                                                                                                                                                                                                                        |
| ----------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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.                                        |
| filter[query]           | string  | Find bandits whose names contain the search text, regardless of case.                                                                                                                                                              |
| sort                    | string  | Sort fields: `name`, `created_at`, or `updated_at`. Use a comma-separated list in priority order; for example, `name,-created_at`. Prefix each field with `-` for descending. Defaults to `created_at` descending.                 |
| filter[status]          | array   | Filter by bandit status. Accepted values are `DRAFT`, `SCHEDULED`, `RUNNING`, `PAUSED`, `STOPPED`, and `COMPLETED`. Repeat this parameter to select several statuses; for example, `filter[status]=RUNNING&filter[status]=PAUSED`. |
| filter[subject_type_id] | array   | Filter by subject type UUID. Repeat this parameter to supply several IDs. A bandit matches if it uses any listed subject type.                                                                                                     |
| filter[tags]            | array   | Filter by tag name. Repeat this parameter to supply several tags. A bandit matches if it has at least one listed tag. Use `team:<handle>` to filter by team. When both tags and teams are given, a bandit must match one of each.  |

### Response

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

{% tabs %}
{% tab label="Model" %}
Response containing a page of bandit summaries.

| Parent field | Field                              | Type      | Description                                                                                                                                                                                                                                                     |
| ------------ | ---------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|              | data [*required*]                  | [object]  | Bandits on this page.                                                                                                                                                                                                                                           |
| data         | attributes [*required*]            | object    | Summary of a bandit. Use Get bandit for its setup, active policy, and latest refresh.                                                                                                                                                                           |
| attributes   | created_at [*required*]            | date-time | When the bandit was created.                                                                                                                                                                                                                                    |
| attributes   | description [*required*]           | string    | The bandit's description.                                                                                                                                                                                                                                       |
| attributes   | ended_at [*required*]              | date-time | When the bandit was stopped or reached its scheduled end. `null` while it hasn't ended.                                                                                                                                                                         |
| attributes   | metric_id [*required*]             | uuid      | The metric the bandit optimizes. `null` until set on a draft.                                                                                                                                                                                                   |
| attributes   | name [*required*]                  | string    | The bandit's name.                                                                                                                                                                                                                                              |
| attributes   | optimal_variant_key [*required*]   | string    | The key of the arm most likely to be best, when one arm leads and the bandit is outside warmup. `null` otherwise.                                                                                                                                               |
| attributes   | optimal_variant_unavailable_reason | enum      | Why no optimal variant is reported. Absent when one is, or when the cause isn't known. Allowed enum values: `NO_RESULTS_YET`, `WARMUP`, `NOT_ENOUGH_DATA`, `NO_DIFFERENCE`, `STATS_UNAVAILABLE`.                                                                |
| attributes   | started_at [*required*]            | date-time | When the bandit started. `null` until it starts.                                                                                                                                                                                                                |
| attributes   | status [*required*]                | enum      | The bandit's status. `STOPPED` means the bandit was stopped and serves the variant chosen then. `COMPLETED` means it reached its scheduled end and serves its fallback. Allowed enum values: `DRAFT`, `SCHEDULED`, `RUNNING`, `PAUSED`, `STOPPED`, `COMPLETED`. |
| attributes   | subject_type_id [*required*]       | uuid      | The subject type the bandit randomizes and measures by. `null` until set on a draft.                                                                                                                                                                            |
| attributes   | tags [*required*]                  | [string]  | The bandit's tags, without team tags.                                                                                                                                                                                                                           |
| attributes   | teams [*required*]                 | [string]  | Handles of the teams that own the bandit.                                                                                                                                                                                                                       |
| attributes   | updated_at [*required*]            | date-time | When the bandit was last changed.                                                                                                                                                                                                                               |
| data         | id [*required*]                    | uuid      | The bandit ID.                                                                                                                                                                                                                                                  |
| data         | type [*required*]                  | enum      | Bandit resource type. Allowed enum values: `bandits`. Default: `bandits`.                                                                                                                                                                                       |
|              | 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": {
        "created_at": "2026-10-22T12:00:00Z",
        "description": "Find the button color that maximizes checkout revenue.",
        "ended_at": "2026-12-01T00:00:00Z",
        "metric_id": "990e8400-e29b-41d4-a716-446655440000",
        "name": "Checkout button color",
        "optimal_variant_key": "green",
        "optimal_variant_unavailable_reason": "NOT_ENOUGH_DATA",
        "started_at": "2026-10-23T09:00:00Z",
        "status": "RUNNING",
        "subject_type_id": "880e8400-e29b-41d4-a716-446655440000",
        "tags": [
          "checkout"
        ],
        "teams": [
          "growth"
        ],
        "updated_at": "2026-10-30T02:15:00Z"
      },
      "id": "4b1f3c2e-8d5a-4f6b-9c7e-1a2b3c4d5e6f",
      "type": "bandits"
    }
  ],
  "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" %}
Invalid query parameter: an unknown filter[status] or sort field, a filter[subject_type_id] that isn't a UUID, a filter[query] over 1024 characters, or a malformed page parameter.

{% 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="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
# 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" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
```
{% /tab %}
{% /tabs %}
