---
title: "List bandits"
method: GET
path: "/api/v2/experiments/bandits"
tags: ["Experiments"]
---

# List bandits

`GET /api/v2/experiments/bandits`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/experiments/bandits`
- Auth: one of:
  - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`
  - OAuth 2
    - Authorization code: `/oauth2/v1/authorize`
    - Token URL: `/oauth2/v1/token` scopes: `product_analytics_experiments_read`

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.

## Query parameters

- `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]` string[]: 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]` string[]: Filter by subject type UUID. Repeat this parameter to supply several IDs. A bandit matches if it uses any listed subject type.
- `filter[tags]` string[]: 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 `200`

OK

- ExperimentsBanditV2ListDTOArray: Response containing a page of bandit summaries.
  - `data` ExperimentsBanditV2ListDTOData[], required: Bandits on this page.
    - `attributes` ExperimentsBanditV2ListDTODataAttributes, required: Summary of a bandit. Use Get bandit for its setup, active policy, and latest refresh.
      - `created_at` string, date-time, required: When the bandit was created.
      - `description` string, required: The bandit's description.
      - `ended_at` string, date-time, nullable, required: When the bandit was stopped or reached its scheduled end. `null` while it hasn't ended.
      - `metric_id` string, uuid, nullable, required: The metric the bandit optimizes. `null` until set on a draft.
      - `name` string, required: The bandit's name.
      - `optimal_variant_key` string, nullable, required: The key of the arm most likely to be best, when one arm leads and the bandit is outside warmup. `null` otherwise.
      - `optimal_variant_unavailable_reason` 'NO_RESULTS_YET' | 'WARMUP' | 'NOT_ENOUGH_DATA' | 'NO_DIFFERENCE' | 'STATS_UNAVAILABLE': Why no optimal variant is reported. Absent when one is, or when the cause isn't known.
      - `started_at` string, date-time, nullable, required: When the bandit started. `null` until it starts.
      - `status` 'DRAFT' | 'SCHEDULED' | 'RUNNING' | 'PAUSED' | 'STOPPED' | 'COMPLETED', required: 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.
      - `subject_type_id` string, uuid, nullable, required: The subject type the bandit randomizes and measures by. `null` until set on a draft.
      - `tags` string[], required: The bandit's tags, without team tags.
      - `teams` string[], required: Handles of the teams that own the bandit.
      - `updated_at` string, date-time, required: When the bandit was last changed.
    - `id` string, uuid, required: The bandit ID.
    - `type` 'bandits', required: Bandit resource type.
  - `links` ExperimentsOffsetLinks, required: Links for navigating a paginated result set.
    - `first` string: URL of the first page of results.
    - `last` string: URL of the last page of results.
    - `next` string: URL of the next page of results.
    - `prev` string: URL of the previous page of results.
    - `self` string: URL of the current page of results.
  - `meta` ExperimentsOffsetMeta, required: Pagination information for a list response.
    - `page` ExperimentsOffsetMetaPage: Result counts and offsets for a page of results.
      - `first_offset` integer: Offset of the first page of results.
      - `last_offset` integer, nullable: Offset of the last page of results.
      - `limit` integer: Maximum number of results returned in one page.
      - `next_offset` integer, nullable: Offset of the next page of results.
      - `offset` integer: Number of results skipped before this page.
      - `prev_offset` integer, nullable: Offset of the previous page of results.
      - `total` integer, nullable: Total number of matching results across all pages.
      - `type` string: Pagination method used for this result set.

## Other responses

- `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.
- `401`: Missing or invalid authentication (dd-api-key + dd-application-key headers, or a valid user session).
- `403`: Bandits are not enabled for the organization, or the caller lacks the product_analytics_experiments_read permission.
- `429`: Too many requests

## Changes

- **2026-11-17** `633e476d0d57`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/changes/api/v2/experiments/bandits/get.md)

---

[API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/8d1a5e5973da?raw)
