418 lines
12 KiB
Plaintext
418 lines
12 KiB
Plaintext
---
|
|
title: Export
|
|
description: The Export API allows you to retrieve event data and chart data from your OpenPanel projects for analysis, reporting, and data integration.
|
|
---
|
|
|
|
## 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.
|
|
|
|
For detailed authentication information, see the [Authentication](/docs/api/authentication) guide.
|
|
|
|
Include the following headers with your requests:
|
|
- `openpanel-client-id`: Your OpenPanel client ID
|
|
- `openpanel-client-secret`: Your OpenPanel client secret
|
|
|
|
## Base URL
|
|
|
|
All Export API requests should be made to:
|
|
|
|
```
|
|
https://api.openpanel.dev/export
|
|
```
|
|
|
|
## Common Query Parameters
|
|
|
|
Most endpoints support the following query parameters:
|
|
|
|
| Parameter | Type | Description | Default |
|
|
|-----------|------|-------------|---------|
|
|
| `projectId` | string | The ID of the project (alternative: `project_id`) | Required |
|
|
| `startDate` | string | Start date (ISO format: YYYY-MM-DD) | Based on range |
|
|
| `endDate` | string | End date (ISO format: YYYY-MM-DD) | Based on range |
|
|
| `range` | string | Predefined date range (`7d`, `30d`, `today`, etc.) | None |
|
|
|
|
## Endpoints
|
|
|
|
### Get Events
|
|
|
|
Retrieve individual events from a specific project within a date range. This endpoint provides raw event data with optional filtering and pagination.
|
|
|
|
```
|
|
GET /export/events
|
|
```
|
|
|
|
#### Query Parameters
|
|
|
|
| Parameter | Type | Description | Example |
|
|
|-----------|------|-------------|---------|
|
|
| `projectId` | string | The ID of the project to fetch events from | `abc123` |
|
|
| `profileId` | string | Filter events by specific profile/user ID | `user_123` |
|
|
| `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: 1000) | `100` |
|
|
| `includes` | string or string[] | Additional fields to include in the response | `profile` or `["profile","meta"]` |
|
|
|
|
#### Include Options
|
|
|
|
The `includes` parameter allows you to fetch additional related data:
|
|
|
|
- `profile`: Include user profile information
|
|
- `meta`: Include event metadata and configuration
|
|
|
|
#### Example Request
|
|
|
|
```bash
|
|
curl 'https://api.openpanel.dev/export/events?projectId=abc123&event=screen_view&start=2024-04-15&end=2024-04-18&page=1&limit=100&includes=profile,meta' \
|
|
-H 'openpanel-client-id: YOUR_CLIENT_ID' \
|
|
-H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
|
|
```
|
|
|
|
#### Response
|
|
|
|
```json
|
|
{
|
|
"meta": {
|
|
"count": 50,
|
|
"totalCount": 1250,
|
|
"pages": 25,
|
|
"current": 1
|
|
},
|
|
"data": [
|
|
{
|
|
"id": "evt_123456789",
|
|
"name": "screen_view",
|
|
"deviceId": "device_abc123",
|
|
"profileId": "user_789",
|
|
"projectId": "abc123",
|
|
"sessionId": "session_xyz",
|
|
"properties": {
|
|
"path": "/dashboard",
|
|
"title": "Dashboard",
|
|
"url": "https://example.com/dashboard"
|
|
},
|
|
"createdAt": "2024-04-15T10:30:00.000Z",
|
|
"country": "United States",
|
|
"city": "New York",
|
|
"region": "New York",
|
|
"os": "macOS",
|
|
"browser": "Chrome",
|
|
"device": "Desktop",
|
|
"duration": 0,
|
|
"path": "/dashboard",
|
|
"origin": "https://example.com",
|
|
"profile": {
|
|
"id": "user_789",
|
|
"email": "user@example.com",
|
|
"firstName": "John",
|
|
"lastName": "Doe",
|
|
"isExternal": true,
|
|
"createdAt": "2024-04-01T08:00:00.000Z"
|
|
},
|
|
"meta": {
|
|
"name": "screen_view",
|
|
"description": "Page view tracking",
|
|
"conversion": false
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Get Charts
|
|
|
|
Retrieve aggregated chart data for analytics and visualization. This endpoint provides time-series data with advanced filtering, breakdowns, and comparison capabilities.
|
|
|
|
```
|
|
GET /export/charts
|
|
```
|
|
|
|
#### Query Parameters
|
|
|
|
| Parameter | Type | Description | Example |
|
|
|-----------|------|-------------|---------|
|
|
| `projectId` | string | The ID of the project to fetch chart data from | `abc123` |
|
|
| `events` | object[] | Array of event configurations to analyze | `[{"name":"screen_view","filters":[]}]` |
|
|
| `breakdowns` | object[] | Array of breakdown dimensions | `[{"name":"country"}]` |
|
|
| `interval` | string | Time interval for data points | `day` |
|
|
| `range` | string | Predefined date range | `7d` |
|
|
| `previous` | boolean | Include data from the previous period for comparison | `true` |
|
|
| `startDate` | string | Custom start date (ISO format) | `2024-04-01` |
|
|
| `endDate` | string | Custom end date (ISO format) | `2024-04-30` |
|
|
|
|
#### Event Configuration
|
|
|
|
Each event in the `events` array supports the following properties:
|
|
|
|
| Property | Type | Description | Required | Default |
|
|
|----------|------|-------------|----------|---------|
|
|
| `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 | No | `event` |
|
|
| `property` | string | Property name for property-based segments | No | - |
|
|
|
|
#### Segmentation Options
|
|
|
|
- `event`: Count individual events (default)
|
|
- `user`: Count unique users/profiles
|
|
- `session`: Count unique sessions
|
|
- `user_average`: Average events per user
|
|
- `one_event_per_user`: One event per user (deduplicated)
|
|
- `property_sum`: Sum of a numeric property
|
|
- `property_average`: Average of a numeric property
|
|
- `property_min`: Minimum value of a numeric property
|
|
- `property_max`: Maximum value of a numeric property
|
|
|
|
#### Filter Configuration
|
|
|
|
Each filter in the `filters` array supports:
|
|
|
|
| Property | Type | Description | Required |
|
|
|----------|------|-------------|----------|
|
|
| `name` | string | Property name to filter on | Yes |
|
|
| `operator` | string | Comparison operator | Yes |
|
|
| `value` | array | Array of values to compare against | Yes |
|
|
|
|
#### Filter Operators
|
|
|
|
- `is`: Exact match
|
|
- `isNot`: Not equal to
|
|
- `contains`: Contains substring
|
|
- `doesNotContain`: Does not contain substring
|
|
- `startsWith`: Starts with
|
|
- `endsWith`: Ends with
|
|
- `regex`: Regular expression match
|
|
- `isNull`: Property is null or empty
|
|
- `isNotNull`: Property has a value
|
|
|
|
#### Breakdown Dimensions
|
|
|
|
Common breakdown dimensions include:
|
|
|
|
| Dimension | Description | Example Values |
|
|
|-----------|-------------|----------------|
|
|
| `country` | User's country | `United States`, `Canada` |
|
|
| `region` | User's region/state | `California`, `New York` |
|
|
| `city` | User's city | `San Francisco`, `New York` |
|
|
| `device` | Device type | `Desktop`, `Mobile`, `Tablet` |
|
|
| `browser` | Browser name | `Chrome`, `Firefox`, `Safari` |
|
|
| `os` | Operating system | `macOS`, `Windows`, `iOS` |
|
|
| `referrer` | Referrer URL | `google.com`, `facebook.com` |
|
|
| `path` | Page path | `/`, `/dashboard`, `/pricing` |
|
|
|
|
#### Time Intervals
|
|
|
|
- `minute`: Minute-by-minute data
|
|
- `hour`: Hourly aggregation
|
|
- `day`: Daily aggregation (default)
|
|
- `week`: Weekly aggregation
|
|
- `month`: Monthly aggregation
|
|
|
|
#### Date Ranges
|
|
|
|
- `30min`: Last 30 minutes
|
|
- `lastHour`: Last hour
|
|
- `today`: Current day
|
|
- `yesterday`: Previous day
|
|
- `7d`: Last 7 days
|
|
- `30d`: Last 30 days
|
|
- `6m`: Last 6 months
|
|
- `12m`: Last 12 months
|
|
- `monthToDate`: Current month to date
|
|
- `lastMonth`: Previous month
|
|
- `yearToDate`: Current year to date
|
|
- `lastYear`: Previous year
|
|
|
|
#### Example Request
|
|
|
|
```bash
|
|
curl 'https://api.openpanel.dev/export/charts?projectId=abc123&events=[{"name":"screen_view","segment":"user"}]&breakdowns=[{"name":"country"}]&interval=day&range=30d&previous=true' \
|
|
-H 'openpanel-client-id: YOUR_CLIENT_ID' \
|
|
-H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
|
|
```
|
|
|
|
#### Example Advanced Request
|
|
|
|
```bash
|
|
curl 'https://api.openpanel.dev/export/charts' \
|
|
-H 'openpanel-client-id: YOUR_CLIENT_ID' \
|
|
-H 'openpanel-client-secret: YOUR_CLIENT_SECRET' \
|
|
-G \
|
|
--data-urlencode 'projectId=abc123' \
|
|
--data-urlencode 'events=[{"name":"purchase","segment":"property_sum","property":"properties.total","filters":[{"name":"properties.total","operator":"isNotNull","value":[]}]}]' \
|
|
--data-urlencode 'breakdowns=[{"name":"country"}]' \
|
|
--data-urlencode 'interval=day' \
|
|
--data-urlencode 'range=30d'
|
|
```
|
|
|
|
#### Response
|
|
|
|
```json
|
|
{
|
|
"series": [
|
|
{
|
|
"id": "screen_view-united-states",
|
|
"names": ["screen_view", "United States"],
|
|
"event": {
|
|
"id": "evt1",
|
|
"name": "screen_view"
|
|
},
|
|
"metrics": {
|
|
"sum": 1250,
|
|
"average": 41.67,
|
|
"min": 12,
|
|
"max": 89,
|
|
"previous": {
|
|
"sum": {
|
|
"value": 1100,
|
|
"change": 13.64
|
|
},
|
|
"average": {
|
|
"value": 36.67,
|
|
"change": 13.64
|
|
}
|
|
}
|
|
},
|
|
"data": [
|
|
{
|
|
"date": "2024-04-01T00:00:00.000Z",
|
|
"count": 45,
|
|
"previous": {
|
|
"value": 38,
|
|
"change": 18.42
|
|
}
|
|
},
|
|
{
|
|
"date": "2024-04-02T00:00:00.000Z",
|
|
"count": 52,
|
|
"previous": {
|
|
"value": 41,
|
|
"change": 26.83
|
|
}
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"metrics": {
|
|
"sum": 1250,
|
|
"average": 41.67,
|
|
"min": 12,
|
|
"max": 89,
|
|
"previous": {
|
|
"sum": {
|
|
"value": 1100,
|
|
"change": 13.64
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
The API uses standard HTTP response codes. Common error responses:
|
|
|
|
### 400 Bad Request
|
|
|
|
```json
|
|
{
|
|
"error": "Bad Request",
|
|
"message": "Invalid query parameters",
|
|
"details": [
|
|
{
|
|
"path": ["events", 0, "name"],
|
|
"message": "Required"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 401 Unauthorized
|
|
|
|
```json
|
|
{
|
|
"error": "Unauthorized",
|
|
"message": "Invalid client credentials"
|
|
}
|
|
```
|
|
|
|
### 403 Forbidden
|
|
|
|
```json
|
|
{
|
|
"error": "Forbidden",
|
|
"message": "You do not have access to this project"
|
|
}
|
|
```
|
|
|
|
### 404 Not Found
|
|
|
|
```json
|
|
{
|
|
"error": "Not Found",
|
|
"message": "Project not found"
|
|
}
|
|
```
|
|
|
|
### 429 Too Many Requests
|
|
|
|
Rate limiting response includes headers indicating your rate limit status.
|
|
|
|
## Rate Limiting
|
|
|
|
The Export API implements rate limiting:
|
|
- **100 requests per 10 seconds** per client
|
|
- Rate limit headers included in responses
|
|
- Implement exponential backoff for retries
|
|
|
|
## Data Types and Formats
|
|
|
|
### Event Properties
|
|
|
|
Event properties are stored as key-value pairs and can include:
|
|
|
|
- **Built-in properties**: `path`, `origin`, `title`, `url`, `hash`
|
|
- **UTM parameters**: `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`
|
|
- **Custom properties**: Any custom data you track with your events
|
|
|
|
### Property Access
|
|
|
|
Properties can be accessed in filters and breakdowns using dot notation:
|
|
|
|
- `properties.custom_field`: Access custom properties
|
|
- `profile.properties.user_type`: Access profile properties
|
|
- `properties.__query.utm_source`: Access query parameters
|
|
|
|
### Date Handling
|
|
|
|
- All dates are in ISO 8601 format
|
|
- Timezone handling is done server-side based on project settings
|
|
- Date ranges are inclusive of start and end dates
|
|
|
|
### Geographic Data
|
|
|
|
Geographic information is automatically collected when available:
|
|
|
|
- `country`: Full country name
|
|
- `region`: State/province/region
|
|
- `city`: City name
|
|
- `longitude`/`latitude`: Coordinates (when available)
|
|
|
|
### Device Information
|
|
|
|
Device data is collected from user agents:
|
|
|
|
- `device`: Device type (Desktop, Mobile, Tablet)
|
|
- `browser`: Browser name and version
|
|
- `os`: Operating system and version
|
|
- `brand`/`model`: Device brand and model (mobile devices)
|
|
|
|
## Notes
|
|
|
|
- Event data is typically available within seconds of tracking
|
|
- All timezone handling is done server-side based on project settings
|
|
- Property names are case-sensitive in filters and breakdowns
|
|
|
|
Remember to replace `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET` with your actual OpenPanel API credentials. |