> For the complete documentation index, see [llms.txt](https://docs.elevateab.com/elevate-helpcenter/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.elevateab.com/elevate-helpcenter/developer-reference/external-api/api-reference/experiments.md).

# Experiments

The Elevate A/B Testing External API /experiments endpoint lists experiments and personalizations by status or type, with the testId to use.

```http
GET /experiments
```

Returns your experiments and personalizations, newest first by when they were last updated. Start here to find the `testId` every results endpoint needs.

## Parameters

| Parameter           | Description                                                   |
| ------------------- | ------------------------------------------------------------- |
| `status`            | `running`, `paused`, `done` or `review`                       |
| `type`              | One experiment type, see below                                |
| `isPersonalization` | `true` to list only personalizations, `false` to exclude them |
| `page`, `limit`     | Page number from 1, and page size from 1 to 100 (default 20)  |

`type` accepts `PAGE`, `PRODUCT`, `SPLIT_URL`, `PRODUCT_GROUP`, `PRICE_PLUS`, `SUBSCRIPTION_TEST`, `CONTENT`, `THEME`, `SHIPPING`, `PRODUCT_IMAGE`, `CHECKOUT` and `CUSTOM_CODE`, the same values `type` carries in the response.

## Response

| Field                                                         | Type             | What it holds                                                                                          |
| ------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------ |
| `items[].testId`                                              | `string`         | The ID every other endpoint takes                                                                      |
| `items[].name`                                                | `string \| null` | The experiment's name                                                                                  |
| `items[].type`, `items[].typeName`                            | `string`         | The type code and its display name                                                                     |
| `items[].status`                                              | `string`         | `Running`, `Paused`, `Done` or `In Review`                                                             |
| `items[].goal`                                                | `string \| null` | The metric it is judged on                                                                             |
| `items[].customEventTrackingId`                               | `string \| null` | Set when the goal is `CUSTOM_EVENT`                                                                    |
| `items[].isPersonalization`                                   | `boolean`        | Whether it is a personalization                                                                        |
| `items[].testTrafficPercentage`                               | `number \| null` | Share of visitors entering the experiment                                                              |
| `items[].startingAt`, `completedAt`, `createdAt`, `updatedAt` | `string \| null` | ISO 8601 timestamps                                                                                    |
| `items[].variations[]`                                        | `object`         | `id`, `name`, `trafficPercentage`, `isControl`                                                         |
| `pagination`                                                  | `object`         | `page`, `limit`, `total` and `totalPages` as integers, `hasNextPage` and `hasPreviousPage` as booleans |

```bash
curl "https://elevateab.app/api/external/v1/experiments?status=running&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "testId": "3f2a9c1e-5b7d-4e8a-9f10-2c4d6e8a0b12",
        "name": "Homepage hero",
        "type": "PAGE",
        "typeName": "Page Experiment",
        "status": "Running",
        "goal": "CONVERSION_RATE",
        "isPersonalization": false,
        "testTrafficPercentage": 100,
        "startingAt": "2026-09-01T08:00:00.000Z",
        "variations": [
          {
            "id": 1001,
            "name": "Control",
            "trafficPercentage": 50,
            "isControl": true
          },
          {
            "id": 1002,
            "name": "Variation 1",
            "trafficPercentage": 50,
            "isControl": false
          }
        ]
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPreviousPage": false
    }
  }
}
```

## Worth knowing

{% hint style="info" %}

* **Page through with `hasNextPage`** rather than counting pages yourself.
* **Drafts and deleted experiments are never returned**, and neither are experiment types the API does not support. Requesting one by ID returns `404`.
* **Poll this endpoint, not the results ones**, to spot what changed: it is far cheaper than asking for results you already have.
  {% endhint %}