---
title: Events (Read)
description: GET /v1/events - List and explore custom events
url: https://www.supalytics.co/docs/api/events
---



List custom events, discover event properties, and get property value breakdowns.

## List Events

```
GET https://api.supalytics.co/v1/events
```

Returns all custom events with counts and visitor numbers.

### Query Parameters

| Parameter | Type   | Default | Description                                           |
| --------- | ------ | ------- | ----------------------------------------------------- |
| `domain`  | string | -       | Site domain to query. Required when using a PAT.      |
| `period`  | string | `30d`   | Time period: `7d`, `14d`, `30d`, `90d`, `12mo`, `all` |
| `start`   | string | -       | Start date (YYYY-MM-DD), use with `end`               |
| `end`     | string | -       | End date (YYYY-MM-DD), use with `start`               |
| `limit`   | number | `100`   | Max results (1-1000)                                  |

### Response

```json
{
  "data": [
    {
      "name": "signup",
      "count": 1234,
      "visitors": 987,
      "has_properties": true
    },
    {
      "name": "faq_open",
      "count": 567,
      "visitors": 432,
      "has_properties": true
    },
    {
      "name": "download_pdf",
      "count": 89,
      "visitors": 76,
      "has_properties": false
    }
  ],
  "meta": {
    "domain": "example.com",
    "date_range": ["2024-11-22", "2024-12-22"],
    "query_ms": 15
  }
}
```

### Example

```bash
curl https://api.supalytics.co/v1/events?period=30d \
  -H "Authorization: Bearer sly_xxx..."
```

***

## List Property Keys

```
GET https://api.supalytics.co/v1/events/:name/properties
```

Returns available property keys for a specific event.

### Path Parameters

| Parameter | Description                             |
| --------- | --------------------------------------- |
| `name`    | Event name (e.g., `signup`, `faq_open`) |

### Query Parameters

Same as [List Events](#query-parameters).

### Response

```json
{
  "data": ["plan", "source", "referrer"],
  "meta": {
    "domain": "example.com",
    "event": "signup",
    "date_range": ["2024-11-22", "2024-12-22"],
    "query_ms": 12
  }
}
```

### Example

```bash
curl https://api.supalytics.co/v1/events/signup/properties \
  -H "Authorization: Bearer sly_xxx..."
```

***

## Property Breakdown

```
GET https://api.supalytics.co/v1/events/:name/properties/:key
```

Returns breakdown of values for a specific property, with visitor counts and optional revenue.

### Path Parameters

| Parameter | Description                 |
| --------- | --------------------------- |
| `name`    | Event name (e.g., `signup`) |
| `key`     | Property key (e.g., `plan`) |

### Query Parameters

| Parameter         | Type    | Default | Description                 |
| ----------------- | ------- | ------- | --------------------------- |
| `period`          | string  | `30d`   | Time period                 |
| `start`           | string  | -       | Start date (YYYY-MM-DD)     |
| `end`             | string  | -       | End date (YYYY-MM-DD)       |
| `limit`           | number  | `100`   | Max results (1-1000)        |
| `include_revenue` | boolean | `false` | Include revenue attribution |

### Response

```json
{
  "data": [
    {
      "value": "premium",
      "count": 450,
      "visitors": 380,
      "revenue": 45000
    },
    {
      "value": "free",
      "count": 784,
      "visitors": 607,
      "revenue": 0
    }
  ],
  "meta": {
    "domain": "example.com",
    "event": "signup",
    "property": "plan",
    "date_range": ["2024-11-22", "2024-12-22"],
    "query_ms": 18
  }
}
```

### Example

```bash
# Get plan breakdown for signup event
curl "https://api.supalytics.co/v1/events/signup/properties/plan?include_revenue=true" \
  -H "Authorization: Bearer sly_xxx..."
```

***

## Filtering with Event Properties

Once you know the property values, you can filter your analytics using the Query API:

```bash
curl -X POST https://api.supalytics.co/v1/query \
  -H "Authorization: Bearer sly_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "dimensions": ["country"],
    "filters": [
      ["event_property", "is", "plan:premium"]
    ]
  }'
```

This returns countries for visitors who signed up with the premium plan.

## Rate Limits

* **100 requests per minute** per API key

## Authentication

Requires an API key or Personal Access Token with `analytics:read` scope.

```
Authorization: Bearer sly_xxx...
```

When using a PAT, you must include the `domain` query parameter in all requests.


---

## Other Documentation

- [Autocapture](https://www.supalytics.co/llms/docs/autocapture)
- [Backfill Existing Subscriptions](https://www.supalytics.co/llms/docs/backfill-existing-subscriptions)
- [Block Your Own Traffic](https://www.supalytics.co/llms/docs/block-your-traffic)
- [CLI](https://www.supalytics.co/llms/docs/cli)
- [Custom Events](https://www.supalytics.co/llms/docs/custom-events)
- [Features](https://www.supalytics.co/llms/docs/features)
- [Conversion Funnels](https://www.supalytics.co/llms/docs/funnels)
- [Introduction](https://www.supalytics.co/llms/docs)
- [Install Script](https://www.supalytics.co/llms/docs/install-script)
- [MRR Tracking](https://www.supalytics.co/llms/docs/mrr-tracking)
- [Revenue Attribution](https://www.supalytics.co/llms/docs/revenue-attribution)
- [Agent Skills](https://www.supalytics.co/llms/docs/skills)
- [Tracking Modes](https://www.supalytics.co/llms/docs/tracking-modes)
- [Visitor Journey](https://www.supalytics.co/llms/docs/visitor-journey)
- [Annotations](https://www.supalytics.co/llms/docs/api/annotations)
- [Error Codes](https://www.supalytics.co/llms/docs/api/errors)
- [API Reference](https://www.supalytics.co/llms/docs/api)
- [Journeys](https://www.supalytics.co/llms/docs/api/journeys)
- [Query API](https://www.supalytics.co/llms/docs/api/query)
- [Realtime API](https://www.supalytics.co/llms/docs/api/realtime)
- [Revenue Attribution API](https://www.supalytics.co/llms/docs/api/revenue-attribution)
- [Events (Write)](https://www.supalytics.co/llms/docs/api/server-side-events)