---
title: Get bandit traffic summary
description: "Get what a bandit has observed, as of its latest saved refresh: observation counts, subjects, and each arm's valid observations and subjects in total and…"
breadcrumbs: Docs > API > Get bandit traffic summary
---

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

# Get bandit traffic summary

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

### Overview

Get what a bandit has observed, as of its latest saved refresh: observation counts, subjects, and each arm's valid observations and subjects in total and per UTC day. An observation is a subject's reward on the arm it was exposed to, counted on the UTC day of its anchor time. `filter[from]` and `filter[to]` narrow only `daily`, not the totals. 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 UTC days that overlap the range starting at this RFC3339 timestamp. Inclusive. |
| filter[to]   | string | Return only the UTC days that overlap the range ending at this RFC3339 timestamp. Exclusive.   |

### Response

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

{% tabs %}
{% tab label="Model" %}
Response containing a bandit's traffic summary.

| Parent field       | Field                                | Type      | Description                                                                                                                                                                                                                                                |
| ------------------ | ------------------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|                    | data [*required*]                    | object    | JSON:API resource containing a bandit's traffic summary.                                                                                                                                                                                                   |
| data               | attributes [*required*]              | object    | What the bandit has observed, as of its latest saved refresh.                                                                                                                                                                                              |
| attributes         | daily [*required*]                   | [object]  | Valid observations per arm, grouped by the UTC day of their anchor time. Includes each day from the bandit's start to the data cutoff that overlaps the requested range. Days without observations have zero counts. Empty before the first saved refresh. |
| daily              | cumulative_new_subjects [*required*] | int64     | The arm's new subjects from the bandit's start through this day, including days before the requested range.                                                                                                                                                |
| daily              | cumulative_observations [*required*] | int64     | The arm's observations from the bandit's start through this day, including days before the requested range.                                                                                                                                                |
| daily              | date [*required*]                    | date      | A UTC date as YYYY-MM-DD.                                                                                                                                                                                                                                  |
| daily              | feature_flag_variant_id [*required*] | uuid      | The arm's variant ID on the flag.                                                                                                                                                                                                                          |
| daily              | new_subjects [*required*]            | int64     | Subjects whose first valid observation is on this day and arm.                                                                                                                                                                                             |
| daily              | observations [*required*]            | int64     | The arm's valid observations on this day.                                                                                                                                                                                                                  |
| daily              | variant_key [*required*]             | string    | The arm's variant key.                                                                                                                                                                                                                                     |
| attributes         | data_as_of [*required*]              | date-time | The timestamp of the most recent warehouse data that the latest saved refresh read.                                                                                                                                                                        |
| attributes         | observation_counts [*required*]      | object    | How many observations the latest saved refresh saw, regardless of the requested range. `null` when its counts can't be read.                                                                                                                               |
| observation_counts | invalid [*required*]                 | int64     | Observations the refresh couldn't use.                                                                                                                                                                                                                     |
| observation_counts | total [*required*]                   | int64     | All observations (the sum of the other three counts).                                                                                                                                                                                                      |
| observation_counts | valid_immature [*required*]          | int64     | Valid observations whose aggregation window is still open.                                                                                                                                                                                                 |
| observation_counts | valid_mature [*required*]            | int64     | Valid observations whose aggregation window has closed. The estimates use these.                                                                                                                                                                           |
| attributes         | refresh_id [*required*]              | uuid      | The latest refresh that saved results. The counts come from it.                                                                                                                                                                                            |
| attributes         | total_subjects [*required*]          | int64     | Distinct subjects with a valid observation, regardless of the requested range.                                                                                                                                                                             |
| attributes         | variants [*required*]                | [object]  | One row per arm, regardless of the requested range.                                                                                                                                                                                                        |
| variants           | feature_flag_variant_id [*required*] | uuid      | The arm's variant ID on the flag.                                                                                                                                                                                                                          |
| variants           | observations [*required*]            | int64     | The arm's valid observations, regardless of whether their aggregation windows have closed.                                                                                                                                                                 |
| variants           | subjects [*required*]                | int64     | Subjects whose first valid observation is on this arm. A subject counts once, on the arm its reward goes to.                                                                                                                                               |
| variants           | variant_key [*required*]             | string    | The arm's variant key.                                                                                                                                                                                                                                     |
| data               | id [*required*]                      | uuid      | The bandit ID.                                                                                                                                                                                                                                             |
| data               | type [*required*]                    | enum      | Bandit traffic summary resource type. Allowed enum values: `bandit-traffic-summary`. Default: `bandit-traffic-summary`.                                                                                                                                    |
{% /tab %}

{% tab label="Example" %}
```json
{
  "data": {
    "attributes": {
      "daily": [
        {
          "cumulative_new_subjects": 3600,
          "cumulative_observations": 4260,
          "date": "2026-10-29",
          "feature_flag_variant_id": "770e8400-e29b-41d4-a716-446655440001",
          "new_subjects": 300,
          "observations": 410,
          "variant_key": "blue"
        }
      ],
      "data_as_of": "2026-10-30T00:00:00Z",
      "observation_counts": {
        "invalid": 40,
        "total": 14210,
        "valid_immature": 420,
        "valid_mature": 13750
      },
      "refresh_id": "bb0e8400-e29b-41d4-a716-446655440000",
      "total_subjects": 11900,
      "variants": [
        {
          "feature_flag_variant_id": "770e8400-e29b-41d4-a716-446655440001",
          "observations": 4260,
          "subjects": 3600,
          "variant_key": "blue"
        }
      ]
    },
    "id": "4b1f3c2e-8d5a-4f6b-9c7e-1a2b3c4d5e6f",
    "type": "bandit-traffic-summary"
  }
}
```
{% /tab %}
{% /tabs %}
{% /tab %}

{% tab label="400" %}
Malformed bandit ID (not a valid UUID), or filter[from] or filter[to] isn't an RFC3339 timestamp, 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}/traffic-summary" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
```
{% /tab %}
{% /tabs %}
