January 202611 min read

API Endpoints

Complete reference for all pxlpeak API endpoints with request/response examples.

Base URL & Versioning

All API requests are made to:

code

https://api.pxlpeak.com/v1

The API uses semantic versioning. The current stable version is v1. Breaking changes will result in a new version number.

code

# Version in URL path (recommended)
https://api.pxlpeak.com/v1/events

# Version in header (alternative)
curl -H "X-API-Version: 2026-01-01" https://api.pxlpeak.com/events

Authentication

All endpoints require authentication via API key in the Authorization header:

code

curl -X GET "https://api.pxlpeak.com/v1/sites" \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

API Key Types

| Key Type | Prefix | Permissions | Use Case | |----------|--------|-------------|----------| | Public | pk_ | Read-only, client-safe | Browser tracking | | Secret | sk_ | Full access | Server-side integrations | | Test | pk_test_ / sk_test_ | Sandbox only | Development |

code

// Client-side (public key only)
const client = new PxlPeak({
  apiKey: 'pk_live_xxxxxxxxxxxxx',
  siteId: 'site_xxxxx'
});

// Server-side (secret key)
const server = new PxlPeak({
  apiKey: 'sk_live_xxxxxxxxxxxxx'
});

Sites

List Sites

code

GET /v1/sites

Returns all sites accessible to the authenticated account.

Query Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | limit | integer | Max results (1-100, default: 20) | | offset | integer | Pagination offset | | status | string | Filter by status: active, paused, archived |

Response:

code

{
  "data": [
    {
      "id": "site_aBcDeFgHiJkL",
      "name": "Main Website",
      "domain": "example.com",
      "status": "active",
      "timezone": "America/New_York",
      "currency": "USD",
      "created_at": "2026-01-01T00:00:00Z",
      "settings": {
        "tracking_enabled": true,
        "cookie_consent_required": true,
        "data_retention_days": 730
      }
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}

Get Site

code

GET /v1/sites/{site_id}

Response:

code

{
  "data": {
    "id": "site_aBcDeFgHiJkL",
    "name": "Main Website",
    "domain": "example.com",
    "status": "active",
    "timezone": "America/New_York",
    "currency": "USD",
    "public_key": "pk_live_xxxxxxxxxxxxx",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-10T12:00:00Z",
    "settings": {
      "tracking_enabled": true,
      "cookie_consent_required": true,
      "data_retention_days": 730,
      "ip_anonymization": true,
      "cross_domain_tracking": ["shop.example.com", "blog.example.com"]
    },
    "integrations": {
      "google_ads": { "enabled": true, "customer_id": "123-456-7890" },
      "meta_ads": { "enabled": true, "pixel_id": "1234567890" }
    }
  }
}

Create Site

code

POST /v1/sites

Request Body:

code

{
  "name": "New Website",
  "domain": "newsite.com",
  "timezone": "America/Los_Angeles",
  "currency": "USD",
  "settings": {
    "cookie_consent_required": true,
    "data_retention_days": 365
  }
}

Response: 201 Created

code

{
  "data": {
    "id": "site_newSiteId123",
    "name": "New Website",
    "domain": "newsite.com",
    "public_key": "pk_live_newkey123",
    "snippet": "<script defer src=\"https://cdn.pxlpeak.com/tracker.js\" data-site=\"site_newSiteId123\"></script>"
  }
}

Update Site

code

PATCH /v1/sites/{site_id}

Request Body:

code

{
  "name": "Updated Website Name",
  "settings": {
    "tracking_enabled": false
  }
}

Delete Site

code

DELETE /v1/sites/{site_id}

Response: 204 No Content

Warning: This permanently deletes all associated data. Consider archiving instead.

Events

Track Event

code

POST /v1/events

Send custom events for tracking.

Request Body:

code

{
  "site_id": "site_aBcDeFgHiJkL",
  "event_name": "purchase",
  "client_id": "cid_xxxxxxxxxxxx",
  "timestamp": "2026-01-12T14:30:00Z",
  "properties": {
    "transaction_id": "TXN-12345",
    "value": 99.99,
    "currency": "USD",
    "items": [
      {
        "item_id": "SKU-001",
        "item_name": "Premium Plan",
        "price": 99.99,
        "quantity": 1
      }
    ]
  },
  "context": {
    "page_url": "https://example.com/checkout/success",
    "page_title": "Order Confirmation",
    "referrer": "https://example.com/checkout",
    "user_agent": "Mozilla/5.0...",
    "ip": "203.0.113.50"
  },
  "user": {
    "user_id": "user_12345",
    "email_hash": "sha256_hash_of_email",
    "traits": {
      "plan": "premium",
      "company": "Acme Inc"
    }
  }
}

Response: 202 Accepted

code

{
  "data": {
    "event_id": "evt_xxxxxxxxxxxx",
    "status": "accepted",
    "processed_at": null
  }
}

Batch Track Events

code

POST /v1/events/batch

Send up to 1000 events in a single request.

Request Body:

code

{
  "site_id": "site_aBcDeFgHiJkL",
  "events": [
    {
      "event_name": "page_view",
      "client_id": "cid_xxxxxxxxxxxx",
      "timestamp": "2026-01-12T14:30:00Z",
      "properties": { "page_path": "/products" }
    },
    {
      "event_name": "add_to_cart",
      "client_id": "cid_xxxxxxxxxxxx",
      "timestamp": "2026-01-12T14:31:00Z",
      "properties": { "item_id": "SKU-001", "value": 49.99 }
    }
  ]
}

Response:

code

{
  "data": {
    "accepted": 2,
    "rejected": 0,
    "events": [
      { "index": 0, "event_id": "evt_xxx1", "status": "accepted" },
      { "index": 1, "event_id": "evt_xxx2", "status": "accepted" }
    ]
  }
}

Query Events

code

GET /v1/sites/{site_id}/events

Query Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | event_name | string | Filter by event name | | start_date | ISO 8601 | Start of date range | | end_date | ISO 8601 | End of date range | | client_id | string | Filter by client ID | | user_id | string | Filter by user ID | | limit | integer | Max results (1-1000) | | cursor | string | Pagination cursor |

Response:

code

{
  "data": [
    {
      "event_id": "evt_xxxxxxxxxxxx",
      "event_name": "purchase",
      "client_id": "cid_xxxxxxxxxxxx",
      "timestamp": "2026-01-12T14:30:00Z",
      "properties": {
        "transaction_id": "TXN-12345",
        "value": 99.99
      }
    }
  ],
  "pagination": {
    "cursor": "eyJsYXN0X2lkIjoiZXZ0X3h4eCJ9",
    "has_more": true
  }
}

Conversions

List Conversion Goals

code

GET /v1/sites/{site_id}/conversions

Response:

code

{
  "data": [
    {
      "id": "conv_xxxxxxxxxxxx",
      "name": "Purchase",
      "type": "event",
      "event_name": "purchase",
      "value_type": "dynamic",
      "value_property": "value",
      "attribution_window_days": 30,
      "counting_method": "one_per_user",
      "status": "active",
      "created_at": "2026-01-01T00:00:00Z"
    },
    {
      "id": "conv_yyyyyyyyyyyy",
      "name": "Lead Form Submit",
      "type": "event",
      "event_name": "form_submit",
      "value_type": "fixed",
      "fixed_value": 50.00,
      "attribution_window_days": 7,
      "counting_method": "every",
      "status": "active"
    }
  ]
}

Create Conversion Goal

code

POST /v1/sites/{site_id}/conversions

Request Body:

code

{
  "name": "Newsletter Signup",
  "type": "event",
  "event_name": "newsletter_signup",
  "value_type": "fixed",
  "fixed_value": 5.00,
  "attribution_window_days": 30,
  "counting_method": "one_per_user"
}

Get Conversion Stats

code

GET /v1/sites/{site_id}/conversions/{conversion_id}/stats

Query Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | start_date | ISO 8601 | Start of date range | | end_date | ISO 8601 | End of date range | | granularity | string | hour, day, week, month | | attribution_model | string | last_click, first_click, linear, position_based, time_decay |

Response:

code

{
  "data": {
    "conversion_id": "conv_xxxxxxxxxxxx",
    "period": {
      "start": "2026-01-01T00:00:00Z",
      "end": "2026-01-12T23:59:59Z"
    },
    "summary": {
      "total_conversions": 1250,
      "total_value": 124750.00,
      "conversion_rate": 3.2,
      "avg_value": 99.80
    },
    "by_source": [
      {
        "source": "google",
        "medium": "cpc",
        "conversions": 450,
        "value": 44955.00,
        "conversion_rate": 4.5
      },
      {
        "source": "meta",
        "medium": "paid",
        "conversions": 380,
        "value": 37962.00,
        "conversion_rate": 3.8
      }
    ],
    "timeseries": [
      { "date": "2026-01-01", "conversions": 95, "value": 9495.00 },
      { "date": "2026-01-02", "conversions": 102, "value": 10200.00 }
    ]
  }
}

Analytics

Get Traffic Overview

code

GET /v1/sites/{site_id}/analytics/traffic

Query Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | start_date | ISO 8601 | Start date | | end_date | ISO 8601 | End date | | metrics | string | Comma-separated: sessions,pageviews,users,bounce_rate,avg_duration | | dimensions | string | Comma-separated: source,medium,campaign,device,country,page | | filters | string | Filter expression (see below) |

Filter Expression Syntax:

code

device==mobile;country==US,CA;source!=direct

Response:

code

{
  "data": {
    "period": {
      "start": "2026-01-01T00:00:00Z",
      "end": "2026-01-12T23:59:59Z"
    },
    "totals": {
      "sessions": 125000,
      "pageviews": 312500,
      "users": 98000,
      "bounce_rate": 42.5,
      "avg_duration": 185.5
    },
    "comparison": {
      "sessions": { "value": 125000, "previous": 110000, "change_percent": 13.6 },
      "users": { "value": 98000, "previous": 85000, "change_percent": 15.3 }
    },
    "rows": [
      {
        "dimensions": { "source": "google", "medium": "organic" },
        "metrics": {
          "sessions": 45000,
          "pageviews": 112500,
          "users": 38000,
          "bounce_rate": 38.2,
          "avg_duration": 210.5
        }
      }
    ]
  }
}

Get Funnel Report

code

POST /v1/sites/{site_id}/analytics/funnel

Request Body:

code

{
  "name": "Purchase Funnel",
  "steps": [
    { "event_name": "page_view", "filters": { "page_path": "/products" } },
    { "event_name": "view_item" },
    { "event_name": "add_to_cart" },
    { "event_name": "begin_checkout" },
    { "event_name": "purchase" }
  ],
  "start_date": "2026-01-01",
  "end_date": "2026-01-12",
  "conversion_window_hours": 168
}

Response:

code

{
  "data": {
    "funnel": {
      "name": "Purchase Funnel",
      "total_entered": 50000,
      "total_completed": 1250,
      "overall_conversion_rate": 2.5
    },
    "steps": [
      {
        "step": 1,
        "name": "Product Page View",
        "users": 50000,
        "conversion_rate": 100.0,
        "drop_off_rate": 0
      },
      {
        "step": 2,
        "name": "View Item",
        "users": 35000,
        "conversion_rate": 70.0,
        "drop_off_rate": 30.0
      },
      {
        "step": 3,
        "name": "Add to Cart",
        "users": 12000,
        "conversion_rate": 34.3,
        "drop_off_rate": 65.7
      },
      {
        "step": 4,
        "name": "Begin Checkout",
        "users": 4500,
        "conversion_rate": 37.5,
        "drop_off_rate": 62.5
      },
      {
        "step": 5,
        "name": "Purchase",
        "users": 1250,
        "conversion_rate": 27.8,
        "drop_off_rate": 72.2
      }
    ]
  }
}

Get Attribution Report

code

GET /v1/sites/{site_id}/analytics/attribution

Query Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | conversion_id | string | Target conversion goal | | start_date | ISO 8601 | Start date | | end_date | ISO 8601 | End date | | model | string | Attribution model | | dimension | string | source, campaign, channel |

Response:

code

{
  "data": {
    "model": "position_based",
    "conversion": {
      "id": "conv_xxxxxxxxxxxx",
      "name": "Purchase"
    },
    "channels": [
      {
        "channel": "Paid Search",
        "attributed_conversions": 450.0,
        "attributed_value": 44955.00,
        "cost": 12500.00,
        "roas": 3.60,
        "cpa": 27.78
      },
      {
        "channel": "Paid Social",
        "attributed_conversions": 380.0,
        "attributed_value": 37962.00,
        "cost": 8500.00,
        "roas": 4.47,
        "cpa": 22.37
      },
      {
        "channel": "Organic Search",
        "attributed_conversions": 250.0,
        "attributed_value": 24975.00,
        "cost": 0,
        "roas": null,
        "cpa": 0
      }
    ]
  }
}

Reports

Create Custom Report

code

POST /v1/sites/{site_id}/reports

Request Body:

code

{
  "name": "Weekly Marketing Performance",
  "description": "Automated weekly report for marketing team",
  "type": "scheduled",
  "schedule": {
    "frequency": "weekly",
    "day_of_week": 1,
    "time": "09:00",
    "timezone": "America/New_York"
  },
  "config": {
    "date_range": "last_7_days",
    "metrics": ["sessions", "conversions", "revenue", "roas"],
    "dimensions": ["source", "medium", "campaign"],
    "filters": "medium==cpc,paid",
    "comparison": "previous_period"
  },
  "delivery": {
    "email": ["marketing@example.com", "cmo@example.com"],
    "format": "pdf",
    "include_raw_data": true
  }
}

Export Data

code

POST /v1/sites/{site_id}/exports

Request Body:

code

{
  "type": "events",
  "start_date": "2026-01-01",
  "end_date": "2026-01-12",
  "format": "csv",
  "filters": {
    "event_names": ["purchase", "add_to_cart"]
  },
  "columns": ["event_id", "event_name", "timestamp", "client_id", "properties.value"],
  "delivery": {
    "method": "download",
    "webhook_url": "https://example.com/webhooks/export-complete"
  }
}

Response:

code

{
  "data": {
    "export_id": "exp_xxxxxxxxxxxx",
    "status": "processing",
    "estimated_rows": 125000,
    "estimated_completion": "2026-01-12T15:00:00Z"
  }
}

Get Export Status

code

GET /v1/exports/{export_id}

Response:

code

{
  "data": {
    "export_id": "exp_xxxxxxxxxxxx",
    "status": "completed",
    "rows_exported": 124532,
    "file_size_bytes": 15234567,
    "download_url": "https://exports.pxlpeak.com/exp_xxxxxxxxxxxx.csv",
    "expires_at": "2026-01-19T15:00:00Z"
  }
}

Users & Profiles

Get User Profile

code

GET /v1/sites/{site_id}/users/{user_id}

Response:

code

{
  "data": {
    "user_id": "user_12345",
    "client_ids": ["cid_xxx1", "cid_xxx2"],
    "first_seen": "2025-06-15T10:00:00Z",
    "last_seen": "2026-01-12T14:30:00Z",
    "total_sessions": 45,
    "total_pageviews": 312,
    "total_conversions": 3,
    "lifetime_value": 297.00,
    "traits": {
      "email_hash": "sha256_xxxx",
      "plan": "premium",
      "company": "Acme Inc"
    },
    "segments": ["high_value", "repeat_purchaser", "engaged"],
    "attribution": {
      "first_touch": {
        "source": "google",
        "medium": "cpc",
        "campaign": "brand_search"
      },
      "last_touch": {
        "source": "direct",
        "medium": "none"
      }
    }
  }
}

Update User Traits

code

PATCH /v1/sites/{site_id}/users/{user_id}

Request Body:

code

{
  "traits": {
    "plan": "enterprise",
    "mrr": 499.00,
    "company_size": "50-200"
  }
}

List User Events

code

GET /v1/sites/{site_id}/users/{user_id}/events

Query Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | start_date | ISO 8601 | Start date | | end_date | ISO 8601 | End date | | event_name | string | Filter by event name | | limit | integer | Max results |

Segments

List Segments

code

GET /v1/sites/{site_id}/segments

Response:

code

{
  "data": [
    {
      "id": "seg_xxxxxxxxxxxx",
      "name": "High Value Customers",
      "description": "Users with LTV > $500",
      "type": "dynamic",
      "rules": {
        "operator": "and",
        "conditions": [
          { "field": "lifetime_value", "operator": "gt", "value": 500 },
          { "field": "total_conversions", "operator": "gte", "value": 2 }
        ]
      },
      "user_count": 2500,
      "last_computed": "2026-01-12T00:00:00Z"
    }
  ]
}

Create Segment

code

POST /v1/sites/{site_id}/segments

Request Body:

code

{
  "name": "Cart Abandoners",
  "description": "Users who added to cart but didn't purchase in 7 days",
  "rules": {
    "operator": "and",
    "conditions": [
      {
        "type": "event",
        "event_name": "add_to_cart",
        "time_window": { "last": 7, "unit": "days" }
      },
      {
        "type": "event_absence",
        "event_name": "purchase",
        "time_window": { "last": 7, "unit": "days" }
      }
    ]
  }
}

Error Handling

All errors follow a consistent format:

code

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "start_date",
        "message": "Must be a valid ISO 8601 date"
      }
    ],
    "request_id": "req_xxxxxxxxxxxx"
  }
}

Error Codes

| HTTP Status | Code | Description | |-------------|------|-------------| | 400 | validation_error | Invalid request parameters | | 401 | unauthorized | Invalid or missing API key | | 403 | forbidden | Insufficient permissions | | 404 | not_found | Resource not found | | 409 | conflict | Resource already exists | | 422 | unprocessable | Valid syntax but semantic error | | 429 | rate_limited | Too many requests | | 500 | internal_error | Server error |

Error Handling Example

code

async function fetchAnalytics(siteId: string) {
  try {
    const response = await fetch(
      `https://api.pxlpeak.com/v1/sites/${siteId}/analytics/traffic`,
      {
        headers: {
          'Authorization': `Bearer ${process.env.PXLPEAK_API_KEY}`,
          'Content-Type': 'application/json'
        }
      }
    );

    if (!response.ok) {
      const error = await response.json();

      switch (response.status) {
        case 429:
          const retryAfter = response.headers.get('Retry-After');
          console.log(`Rate limited. Retry after ${retryAfter}s`);
          break;
        case 401:
          throw new Error('Invalid API key');
        case 404:
          throw new Error(`Site ${siteId} not found`);
        default:
          throw new Error(error.error.message);
      }
    }

    return response.json();
  } catch (error) {
    console.error('API Error:', error);
    throw error;
  }
}

Pagination

List endpoints use cursor-based pagination for consistent results:

code

async function fetchAllEvents(siteId: string) {
  const events: Event[] = [];
  let cursor: string | null = null;

  do {
    const params = new URLSearchParams({
      limit: '100',
      ...(cursor && { cursor })
    });

    const response = await fetch(
      `https://api.pxlpeak.com/v1/sites/${siteId}/events?${params}`,
      {
        headers: { 'Authorization': `Bearer ${apiKey}` }
      }
    );

    const data = await response.json();
    events.push(...data.data);
    cursor = data.pagination.has_more ? data.pagination.cursor : null;
  } while (cursor);

  return events;
}

Next: See Webhooks to receive real-time event notifications.

January 202611 min read

API Endpoints

Complete reference for all pxlpeak API endpoints with request/response examples.

Base URL & Versioning

All API requests are made to:

code

https://api.pxlpeak.com/v1

The API uses semantic versioning. The current stable version is v1. Breaking changes will result in a new version number.

code

# Version in URL path (recommended)
https://api.pxlpeak.com/v1/events

# Version in header (alternative)
curl -H "X-API-Version: 2026-01-01" https://api.pxlpeak.com/events

Authentication

All endpoints require authentication via API key in the Authorization header:

code

curl -X GET "https://api.pxlpeak.com/v1/sites" \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

API Key Types

code

// Client-side (public key only)
const client = new PxlPeak({
  apiKey: 'pk_live_xxxxxxxxxxxxx',
  siteId: 'site_xxxxx'
});

// Server-side (secret key)
const server = new PxlPeak({
  apiKey: 'sk_live_xxxxxxxxxxxxx'
});

Sites

List Sites

code

GET /v1/sites

Returns all sites accessible to the authenticated account.

Query Parameters:

Response:

code

{
  "data": [
    {
      "id": "site_aBcDeFgHiJkL",
      "name": "Main Website",
      "domain": "example.com",
      "status": "active",
      "timezone": "America/New_York",
      "currency": "USD",
      "created_at": "2026-01-01T00:00:00Z",
      "settings": {
        "tracking_enabled": true,
        "cookie_consent_required": true,
        "data_retention_days": 730
      }
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}

Get Site

code

GET /v1/sites/{site_id}

Response:

code

{
  "data": {
    "id": "site_aBcDeFgHiJkL",
    "name": "Main Website",
    "domain": "example.com",
    "status": "active",
    "timezone": "America/New_York",
    "currency": "USD",
    "public_key": "pk_live_xxxxxxxxxxxxx",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-10T12:00:00Z",
    "settings": {
      "tracking_enabled": true,
      "cookie_consent_required": true,
      "data_retention_days": 730,
      "ip_anonymization": true,
      "cross_domain_tracking": ["shop.example.com", "blog.example.com"]
    },
    "integrations": {
      "google_ads": { "enabled": true, "customer_id": "123-456-7890" },
      "meta_ads": { "enabled": true, "pixel_id": "1234567890" }
    }
  }
}

Create Site

code

POST /v1/sites

Request Body:

code

{
  "name": "New Website",
  "domain": "newsite.com",
  "timezone": "America/Los_Angeles",
  "currency": "USD",
  "settings": {
    "cookie_consent_required": true,
    "data_retention_days": 365
  }
}

Response: 201 Created

code

{
  "data": {
    "id": "site_newSiteId123",
    "name": "New Website",
    "domain": "newsite.com",
    "public_key": "pk_live_newkey123",
    "snippet": "<script defer src=\"https://cdn.pxlpeak.com/tracker.js\" data-site=\"site_newSiteId123\"></script>"
  }
}

Update Site

code

PATCH /v1/sites/{site_id}

Request Body:

code

{
  "name": "Updated Website Name",
  "settings": {
    "tracking_enabled": false
  }
}

Delete Site

code

DELETE /v1/sites/{site_id}

Response: 204 No Content

Warning: This permanently deletes all associated data. Consider archiving instead.

Events

Track Event

code

POST /v1/events

Send custom events for tracking.

Request Body:

code

{
  "site_id": "site_aBcDeFgHiJkL",
  "event_name": "purchase",
  "client_id": "cid_xxxxxxxxxxxx",
  "timestamp": "2026-01-12T14:30:00Z",
  "properties": {
    "transaction_id": "TXN-12345",
    "value": 99.99,
    "currency": "USD",
    "items": [
      {
        "item_id": "SKU-001",
        "item_name": "Premium Plan",
        "price": 99.99,
        "quantity": 1
      }
    ]
  },
  "context": {
    "page_url": "https://example.com/checkout/success",
    "page_title": "Order Confirmation",
    "referrer": "https://example.com/checkout",
    "user_agent": "Mozilla/5.0...",
    "ip": "203.0.113.50"
  },
  "user": {
    "user_id": "user_12345",
    "email_hash": "sha256_hash_of_email",
    "traits": {
      "plan": "premium",
      "company": "Acme Inc"
    }
  }
}

Response: 202 Accepted

code

{
  "data": {
    "event_id": "evt_xxxxxxxxxxxx",
    "status": "accepted",
    "processed_at": null
  }
}

Batch Track Events

code

POST /v1/events/batch

Send up to 1000 events in a single request.

Request Body:

code

{
  "site_id": "site_aBcDeFgHiJkL",
  "events": [
    {
      "event_name": "page_view",
      "client_id": "cid_xxxxxxxxxxxx",
      "timestamp": "2026-01-12T14:30:00Z",
      "properties": { "page_path": "/products" }
    },
    {
      "event_name": "add_to_cart",
      "client_id": "cid_xxxxxxxxxxxx",
      "timestamp": "2026-01-12T14:31:00Z",
      "properties": { "item_id": "SKU-001", "value": 49.99 }
    }
  ]
}

Response:

code

{
  "data": {
    "accepted": 2,
    "rejected": 0,
    "events": [
      { "index": 0, "event_id": "evt_xxx1", "status": "accepted" },
      { "index": 1, "event_id": "evt_xxx2", "status": "accepted" }
    ]
  }
}

Query Events

code

GET /v1/sites/{site_id}/events

Query Parameters:

Response:

code

{
  "data": [
    {
      "event_id": "evt_xxxxxxxxxxxx",
      "event_name": "purchase",
      "client_id": "cid_xxxxxxxxxxxx",
      "timestamp": "2026-01-12T14:30:00Z",
      "properties": {
        "transaction_id": "TXN-12345",
        "value": 99.99
      }
    }
  ],
  "pagination": {
    "cursor": "eyJsYXN0X2lkIjoiZXZ0X3h4eCJ9",
    "has_more": true
  }
}

Conversions

List Conversion Goals

code

GET /v1/sites/{site_id}/conversions

Response:

code

{
  "data": [
    {
      "id": "conv_xxxxxxxxxxxx",
      "name": "Purchase",
      "type": "event",
      "event_name": "purchase",
      "value_type": "dynamic",
      "value_property": "value",
      "attribution_window_days": 30,
      "counting_method": "one_per_user",
      "status": "active",
      "created_at": "2026-01-01T00:00:00Z"
    },
    {
      "id": "conv_yyyyyyyyyyyy",
      "name": "Lead Form Submit",
      "type": "event",
      "event_name": "form_submit",
      "value_type": "fixed",
      "fixed_value": 50.00,
      "attribution_window_days": 7,
      "counting_method": "every",
      "status": "active"
    }
  ]
}

Create Conversion Goal

code

POST /v1/sites/{site_id}/conversions

Request Body:

code

{
  "name": "Newsletter Signup",
  "type": "event",
  "event_name": "newsletter_signup",
  "value_type": "fixed",
  "fixed_value": 5.00,
  "attribution_window_days": 30,
  "counting_method": "one_per_user"
}

Get Conversion Stats

code

GET /v1/sites/{site_id}/conversions/{conversion_id}/stats

Query Parameters:

Response:

code

{
  "data": {
    "conversion_id": "conv_xxxxxxxxxxxx",
    "period": {
      "start": "2026-01-01T00:00:00Z",
      "end": "2026-01-12T23:59:59Z"
    },
    "summary": {
      "total_conversions": 1250,
      "total_value": 124750.00,
      "conversion_rate": 3.2,
      "avg_value": 99.80
    },
    "by_source": [
      {
        "source": "google",
        "medium": "cpc",
        "conversions": 450,
        "value": 44955.00,
        "conversion_rate": 4.5
      },
      {
        "source": "meta",
        "medium": "paid",
        "conversions": 380,
        "value": 37962.00,
        "conversion_rate": 3.8
      }
    ],
    "timeseries": [
      { "date": "2026-01-01", "conversions": 95, "value": 9495.00 },
      { "date": "2026-01-02", "conversions": 102, "value": 10200.00 }
    ]
  }
}

Analytics

Get Traffic Overview

code

GET /v1/sites/{site_id}/analytics/traffic

Query Parameters:

Filter Expression Syntax:

code

device==mobile;country==US,CA;source!=direct

Response:

code

{
  "data": {
    "period": {
      "start": "2026-01-01T00:00:00Z",
      "end": "2026-01-12T23:59:59Z"
    },
    "totals": {
      "sessions": 125000,
      "pageviews": 312500,
      "users": 98000,
      "bounce_rate": 42.5,
      "avg_duration": 185.5
    },
    "comparison": {
      "sessions": { "value": 125000, "previous": 110000, "change_percent": 13.6 },
      "users": { "value": 98000, "previous": 85000, "change_percent": 15.3 }
    },
    "rows": [
      {
        "dimensions": { "source": "google", "medium": "organic" },
        "metrics": {
          "sessions": 45000,
          "pageviews": 112500,
          "users": 38000,
          "bounce_rate": 38.2,
          "avg_duration": 210.5
        }
      }
    ]
  }
}

Get Funnel Report

code

POST /v1/sites/{site_id}/analytics/funnel

Request Body:

code

{
  "name": "Purchase Funnel",
  "steps": [
    { "event_name": "page_view", "filters": { "page_path": "/products" } },
    { "event_name": "view_item" },
    { "event_name": "add_to_cart" },
    { "event_name": "begin_checkout" },
    { "event_name": "purchase" }
  ],
  "start_date": "2026-01-01",
  "end_date": "2026-01-12",
  "conversion_window_hours": 168
}

Response:

code

{
  "data": {
    "funnel": {
      "name": "Purchase Funnel",
      "total_entered": 50000,
      "total_completed": 1250,
      "overall_conversion_rate": 2.5
    },
    "steps": [
      {
        "step": 1,
        "name": "Product Page View",
        "users": 50000,
        "conversion_rate": 100.0,
        "drop_off_rate": 0
      },
      {
        "step": 2,
        "name": "View Item",
        "users": 35000,
        "conversion_rate": 70.0,
        "drop_off_rate": 30.0
      },
      {
        "step": 3,
        "name": "Add to Cart",
        "users": 12000,
        "conversion_rate": 34.3,
        "drop_off_rate": 65.7
      },
      {
        "step": 4,
        "name": "Begin Checkout",
        "users": 4500,
        "conversion_rate": 37.5,
        "drop_off_rate": 62.5
      },
      {
        "step": 5,
        "name": "Purchase",
        "users": 1250,
        "conversion_rate": 27.8,
        "drop_off_rate": 72.2
      }
    ]
  }
}

Get Attribution Report

code

GET /v1/sites/{site_id}/analytics/attribution

Query Parameters:

Response:

code

{
  "data": {
    "model": "position_based",
    "conversion": {
      "id": "conv_xxxxxxxxxxxx",
      "name": "Purchase"
    },
    "channels": [
      {
        "channel": "Paid Search",
        "attributed_conversions": 450.0,
        "attributed_value": 44955.00,
        "cost": 12500.00,
        "roas": 3.60,
        "cpa": 27.78
      },
      {
        "channel": "Paid Social",
        "attributed_conversions": 380.0,
        "attributed_value": 37962.00,
        "cost": 8500.00,
        "roas": 4.47,
        "cpa": 22.37
      },
      {
        "channel": "Organic Search",
        "attributed_conversions": 250.0,
        "attributed_value": 24975.00,
        "cost": 0,
        "roas": null,
        "cpa": 0
      }
    ]
  }
}

Reports

Create Custom Report

code

POST /v1/sites/{site_id}/reports

Request Body:

code

{
  "name": "Weekly Marketing Performance",
  "description": "Automated weekly report for marketing team",
  "type": "scheduled",
  "schedule": {
    "frequency": "weekly",
    "day_of_week": 1,
    "time": "09:00",
    "timezone": "America/New_York"
  },
  "config": {
    "date_range": "last_7_days",
    "metrics": ["sessions", "conversions", "revenue", "roas"],
    "dimensions": ["source", "medium", "campaign"],
    "filters": "medium==cpc,paid",
    "comparison": "previous_period"
  },
  "delivery": {
    "email": ["marketing@example.com", "cmo@example.com"],
    "format": "pdf",
    "include_raw_data": true
  }
}

Export Data

code

POST /v1/sites/{site_id}/exports

Request Body:

code

{
  "type": "events",
  "start_date": "2026-01-01",
  "end_date": "2026-01-12",
  "format": "csv",
  "filters": {
    "event_names": ["purchase", "add_to_cart"]
  },
  "columns": ["event_id", "event_name", "timestamp", "client_id", "properties.value"],
  "delivery": {
    "method": "download",
    "webhook_url": "https://example.com/webhooks/export-complete"
  }
}

Response:

code

{
  "data": {
    "export_id": "exp_xxxxxxxxxxxx",
    "status": "processing",
    "estimated_rows": 125000,
    "estimated_completion": "2026-01-12T15:00:00Z"
  }
}

Get Export Status

code

GET /v1/exports/{export_id}

Response:

code

{
  "data": {
    "export_id": "exp_xxxxxxxxxxxx",
    "status": "completed",
    "rows_exported": 124532,
    "file_size_bytes": 15234567,
    "download_url": "https://exports.pxlpeak.com/exp_xxxxxxxxxxxx.csv",
    "expires_at": "2026-01-19T15:00:00Z"
  }
}

Users & Profiles

Get User Profile

code

GET /v1/sites/{site_id}/users/{user_id}

Response:

code

{
  "data": {
    "user_id": "user_12345",
    "client_ids": ["cid_xxx1", "cid_xxx2"],
    "first_seen": "2025-06-15T10:00:00Z",
    "last_seen": "2026-01-12T14:30:00Z",
    "total_sessions": 45,
    "total_pageviews": 312,
    "total_conversions": 3,
    "lifetime_value": 297.00,
    "traits": {
      "email_hash": "sha256_xxxx",
      "plan": "premium",
      "company": "Acme Inc"
    },
    "segments": ["high_value", "repeat_purchaser", "engaged"],
    "attribution": {
      "first_touch": {
        "source": "google",
        "medium": "cpc",
        "campaign": "brand_search"
      },
      "last_touch": {
        "source": "direct",
        "medium": "none"
      }
    }
  }
}

Update User Traits

code

PATCH /v1/sites/{site_id}/users/{user_id}

Request Body:

code

{
  "traits": {
    "plan": "enterprise",
    "mrr": 499.00,
    "company_size": "50-200"
  }
}

List User Events

code

GET /v1/sites/{site_id}/users/{user_id}/events

Query Parameters:

Segments

List Segments

code

GET /v1/sites/{site_id}/segments

Response:

code

{
  "data": [
    {
      "id": "seg_xxxxxxxxxxxx",
      "name": "High Value Customers",
      "description": "Users with LTV > $500",
      "type": "dynamic",
      "rules": {
        "operator": "and",
        "conditions": [
          { "field": "lifetime_value", "operator": "gt", "value": 500 },
          { "field": "total_conversions", "operator": "gte", "value": 2 }
        ]
      },
      "user_count": 2500,
      "last_computed": "2026-01-12T00:00:00Z"
    }
  ]
}

Create Segment

code

POST /v1/sites/{site_id}/segments

Request Body:

code

{
  "name": "Cart Abandoners",
  "description": "Users who added to cart but didn't purchase in 7 days",
  "rules": {
    "operator": "and",
    "conditions": [
      {
        "type": "event",
        "event_name": "add_to_cart",
        "time_window": { "last": 7, "unit": "days" }
      },
      {
        "type": "event_absence",
        "event_name": "purchase",
        "time_window": { "last": 7, "unit": "days" }
      }
    ]
  }
}

Error Handling

All errors follow a consistent format:

code

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "start_date",
        "message": "Must be a valid ISO 8601 date"
      }
    ],
    "request_id": "req_xxxxxxxxxxxx"
  }
}

Error Codes

Error Handling Example

code

async function fetchAnalytics(siteId: string) {
  try {
    const response = await fetch(
      `https://api.pxlpeak.com/v1/sites/${siteId}/analytics/traffic`,
      {
        headers: {
          'Authorization': `Bearer ${process.env.PXLPEAK_API_KEY}`,
          'Content-Type': 'application/json'
        }
      }
    );

    if (!response.ok) {
      const error = await response.json();

      switch (response.status) {
        case 429:
          const retryAfter = response.headers.get('Retry-After');
          console.log(`Rate limited. Retry after ${retryAfter}s`);
          break;
        case 401:
          throw new Error('Invalid API key');
        case 404:
          throw new Error(`Site ${siteId} not found`);
        default:
          throw new Error(error.error.message);
      }
    }

    return response.json();
  } catch (error) {
    console.error('API Error:', error);
    throw error;
  }
}

Pagination

List endpoints use cursor-based pagination for consistent results:

code

async function fetchAllEvents(siteId: string) {
  const events: Event[] = [];
  let cursor: string | null = null;

  do {
    const params = new URLSearchParams({
      limit: '100',
      ...(cursor && { cursor })
    });

    const response = await fetch(
      `https://api.pxlpeak.com/v1/sites/${siteId}/events?${params}`,
      {
        headers: { 'Authorization': `Bearer ${apiKey}` }
      }
    );

    const data = await response.json();
    events.push(...data.data);
    cursor = data.pagination.has_more ? data.pagination.cursor : null;
  } while (cursor);

  return events;
}

Next: See Webhooks to receive real-time event notifications.