stats/apps/public/content/docs/api/export.mdx

---
title: Export
description: The Export API allows you to retrieve event data and chart data from your OpenPanel projects.
---

## Authentication

To authenticate with the Export API, you need to use your `clientId` and `clientSecret`. Make sure your client has `read` or `root` mode. The default client does not have access to the Export API.

Include the following headers with your requests:
- `openpanel-client-id`: Your OpenPanel client ID
- `openpanel-client-secret`: Your OpenPanel client secret

Example:

```bash
curl 'https://api.openpanel.dev/export/events' \
  -H 'openpanel-client-id: YOUR_CLIENT_ID' \
  -H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
```

## Events

Get events from a specific project within a date range.

Endpoint: `GET /export/events`

Parameters:
- project_id (required): The ID of the project
- event (optional): Filter by event name(s). Can be a single event or an array of events.
- start (optional): Start date (format: YYYY-MM-DD)
- end (optional): End date (format: YYYY-MM-DD)
- page (optional, default: 1): Page number for pagination
- limit (optional, default: 50, max: 50): Number of events per page
- includes (optional): Additional fields to include in the response

Example:

```bash
curl 'https://api.openpanel.dev/export/events?project_id=abc&event=screen_view&start=2024-04-15&end=2024-04-18' \
  -H 'openpanel-client-id: YOUR_CLIENT_ID' \
  -H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
```

### Query Parameters

| Parameter | Type | Description | Example |
|-----------|------|-------------|---------|
| projectId | string | The ID of the project to fetch events from | `abc123` |
| event | string or string[] | Event name(s) to filter | `screen_view` or `["screen_view","button_click"]` |
| start | string | Start date for the event range (ISO format) | `2024-04-15` |
| end | string | End date for the event range (ISO format) | `2024-04-18` |
| page | number | Page number for pagination (default: 1) | `2` |
| limit | number | Number of events per page (default: 50, max: 50) | `25` |
| includes | string or string[] | Additional fields to include in the response | `profile` or `["profile","meta"]` |

### Example Request

```bash
curl 'https://api.openpanel.dev/export/events?project_id=abc123&event=screen_view&start=2024-04-15&end=2024-04-18&page=1&limit=50&includes=profile,meta' \
  -H 'openpanel-client-id: YOUR_CLIENT_ID' \
  -H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
```

### Response

```json
{
  "meta": {
    "count": number,
    "totalCount": number,
    "pages": number,
    "current": number
  },
  "data": Array<Event>
}
```

## Charts

Retrieve chart data for a specific project.

### Endpoint

```
GET /export/charts
```

### Query Parameters

| Parameter | Type | Description | Example |
|-----------|------|-------------|---------|
| projectId | string | The ID of the project to fetch chart data from | `abc123` |
| events | string[] | Array of event configurations to include in the chart | `[{"name":"sign_up","filters":[]}]` |
| breakdowns | object[] | Array of breakdown configurations | `[{"name":"country"}]` |
| interval | string | Time interval for data points | `day` |
| range | string | Predefined date range | `last_7_days` |
| previous | boolean | Include data from the previous period | `true` |
| startDate | string | Custom start date (ISO format) | `2024-04-01` |
| endDate | string | Custom end date (ISO format) | `2024-04-30` |
| chartType | string | Type of chart to generate | `linear` |
| metric | string | Metric to use for calculations | `sum` |
| limit | number | Limit the number of results | `10` |
| offset | number | Offset for pagination | `0` |

#### Events configuration

Each event configuration object has the following properties:

| Property | Type | Description | Required |
|----------|------|-------------|----------|
| name | string | Name of the event to track | Yes |
| filters | Filter[] | Array of filters to apply to the event | No |
| segment | string | Type of segmentation. Options: `event`, `user`, `session`, `user_average`, `one_event_per_user`, `property_sum`, `property_average` | No (defaults to `event`) |
| property | string | Property name to analyze when using property-based segments | No |

##### Filter Configuration

Each filter in the `filters` array has the following structure:

| Property | Type | Description | Required |
|----------|------|-------------|----------|
| name | string | Name of the property to filter on | Yes |
| operator | string | Comparison operator. Valid values: `is`, `isNot`, `contains`, `doesNotContain`, `startsWith`, `endsWith`, `regex` | Yes |
| value | (string \| number \| boolean \| null)[] | Array of values to compare against | Yes |

Example event configuration:
```json
{
  "name": "purchase",
  "segment": "user",
  "filters": [
    {
      "name": "total",
      "operator": "is",
      "value": ["100"]
    }
  ]
}
```

The operators are used in the SQL builder (`chart.service.ts` lines 262-346) with the following mappings:
- `is`: Equals comparison
- `isNot`: Not equals comparison
- `contains`: LIKE %value%
- `doesNotContain`: NOT LIKE %value%
- `startsWith`: LIKE value%
- `endsWith`: LIKE %value
- `regex`: Match function

### Example Request

```bash
curl 'https://api.openpanel.dev/export/charts?projectId=abc123&events=[{"name":"screen_view"}]&interval=day&range=last_30_days&chartType=linear&metric=sum' \
  -H 'openpanel-client-id: YOUR_CLIENT_ID' \
  -H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
```

### Response

The response will include chart data with series, metrics, and optional previous period comparisons based on the input parameters.

## Funnel

Retrieve funnel data for a specific project.

### Endpoint

```
GET /export/funnel
```

### Query Parameters

| Parameter | Type | Description | Example |
|-----------|------|-------------|---------|
| projectId | string | The ID of the project to fetch funnel data from | `abc123` |
| events | object[] | Array of event configurations for the funnel steps | `[{"name":"sign_up","filters":[]}]` |
| range | string | Predefined date range | `last_30_days` |
| startDate | string | Custom start date (ISO format) | `2024-04-01` |
| endDate | string | Custom end date (ISO format) | `2024-04-30` |

### Example Request

```bash
curl 'https://api.openpanel.dev/export/funnel?projectId=abc123&events=[{"name":"sign_up"},{"name":"purchase"}]&range=last_30_days' \
  -H 'openpanel-client-id: YOUR_CLIENT_ID' \
  -H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
```

### Response

The response will include funnel data with total sessions and step-by-step breakdown of the funnel progression.

```json
{
  "totalSessions": number,
  "steps": [
    {
      "event": {
        "name": string,
        "displayName": string
      },
      "count": number,
      "percent": number,
      "dropoffCount": number,
      "dropoffPercent": number,
      "previousCount": number
    }
  ]
}
```

## Notes

- All date parameters should be in ISO format (YYYY-MM-DD).
- The `range` parameter accepts values like `today`, `yesterday`, `last_7_days`, `last_30_days`, `this_month`, `last_month`, `this_year`, `last_year`, `all_time`.
- The `interval` parameter accepts values like `minute`, `hour`, `day`, `month`.
- The `chartType` parameter can be `linear` or other supported chart types.
- The `metric` parameter can be `sum`, `average`, `min`, or `max`.

Remember to replace `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET` with your actual OpenPanel API credentials.