Export

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 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:

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

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

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

{
  "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

Event Configuration

Each event in the events array supports the following properties:

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:

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:

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

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

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

{
  "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

{
  "error": "Bad Request",
  "message": "Invalid query parameters",
  "details": [
    {
      "path": ["events", 0, "name"],
      "message": "Required"
    }
  ]
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid client credentials"
}

403 Forbidden

{
  "error": "Forbidden",
  "message": "You do not have access to this project"
}

404 Not Found

{
  "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.