> 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/custom-events.md).

# Custom events

The Elevate A/B Testing External API /custom-events endpoint lists your custom events and the tracking IDs used for filters and goals.

```http
GET /custom-events
```

Returns every custom event your store has defined, with the tracking ID you use to filter by it or to recognise an experiment's goal. Takes no parameters.

## Response

| Field                 | Type             | What it holds                                            |
| --------------------- | ---------------- | -------------------------------------------------------- |
| `items[].trackingId`  | `string`         | The ID used in `custom_event` filters and on experiments |
| `items[].name`        | `string`         | The event's name in Elevate A/B Testing                  |
| `items[].description` | `string \| null` | Its description, `null` when empty                       |
| `items[].createdAt`   | `string \| null` | ISO 8601 timestamp                                       |
| `items[].updatedAt`   | `string \| null` | ISO 8601 timestamp                                       |

```bash
curl https://elevateab.app/api/external/v1/custom-events \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "trackingId": "newsletter_signup",
        "name": "Newsletter signup",
        "description": "Footer form submitted",
        "createdAt": "2026-06-02T09:14:00.000Z",
        "updatedAt": "2026-08-20T11:02:00.000Z"
      }
    ]
  }
}
```

## Worth knowing

* **Two uses:** filter any results endpoint with `custom_event={trackingId}`, or resolve an experiment whose `goal` is `CUSTOM_EVENT` through its `customEventTrackingId`.
* **How an event is detected** (the element or URL it watches) stays in Elevate A/B Testing and is not returned here.