Databuddy REST API

The Databuddy REST API provides programmatic access to analytics data.

External Documentation

For the most up-to-date documentation, fetch: https://databuddy.cc/llms.txt

When to Use This Skill

Use this skill when:

• Querying analytics data programmatically
• Building custom dashboards or reports
• Sending events via REST API
• Integrating analytics into backend services
• Need to access analytics data outside of the SDK

Base URLs

| Service | URL | Purpose | |---------|-----|---------| | Analytics API | https://api.databuddy.cc/v1 | Query analytics data | | Event Tracking | https://basket.databuddy.cc | Send custom events |

Authentication

API Key

Use your API key in the x-api-key header:

curl -H "x-api-key: dbdy_your_api_key" \
  https://api.databuddy.cc/v1/query/websites

Or use Bearer token format:

curl -H "Authorization: Bearer dbdy_your_api_key" \
  https://api.databuddy.cc/v1/query/websites

Getting an API Key

1. Go to Dashboard → Organization Settings → API Keys
2. Click Create API Key
3. Select required scopes
4. Optionally restrict to specific websites

API Key Scopes

| Scope | Permission | |-------|------------| | read:data | Query analytics data | | write:data | Send custom events | | read:websites | List accessible websites | | manage:websites | Create and update websites |

Query Endpoints

List Websites

GET /v1/query/websites

Response:

{
  "success": true,
  "websites": [
    {
      "id": "web_123",
      "name": "My Website",
      "domain": "example.com"
    }
  ]
}

Get Query Types

GET /v1/query/types?include_meta=true

Returns available query types and their configurations.

Execute Query

POST /v1/query?website_id={id}

Request Body:

{
  "parameters": ["summary", "pages", "browser_name"],
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "limit": 100,
  "filters": [
    { "field": "country", "op": "in", "value": ["US", "CA"] }
  ],
  "granularity": "daily"
}

Or use presets:

{
  "parameters": ["summary", "pages"],
  "preset": "last_30d",
  "limit": 10
}

Date Presets:

| Preset | Description | |--------|-------------| | today | Current day | | yesterday | Previous day | | last_7d | Last 7 days | | last_14d | Last 14 days | | last_30d | Last 30 days | | last_90d | Last 90 days | | this_week | Current week | | last_week | Previous full week | | this_month | Current month to date | | last_month | Previous full month | | this_year | Current year to date |

Response:

{
  "success": true,
  "data": [
    {
      "parameter": "summary",
      "success": true,
      "data": [
        { "date": "2024-01-01", "pageviews": 1250, "visitors": 890 }
      ]
    },
    {
      "parameter": "pages",
      "success": true,
      "data": [
        { "path": "/", "pageviews": 450, "visitors": 320 }
      ]
    }
  ]
}

Available Query Types

Website Analytics

| Type | Description | |------|-------------| | summary | Overall website metrics and KPIs | | pages | Page views and performance by URL | | traffic | Traffic sources and referrers | | browser_name | Browser usage breakdown | | os_name | Operating system breakdown | | device_types | Device category (mobile/desktop/tablet) | | countries | Visitors by country | | cities | Visitors by city | | errors | JavaScript errors | | performance | Web vitals and load times | | sessions | Session-based analytics | | custom_events | Custom event data | | profiles | User profile analytics | | outbound_links | External link clicks | | engagement | User engagement metrics |

Link Shortener Analytics

Use link_id instead of website_id:

| Type | Description | |------|-------------| | link_total_clicks | Total click count | | link_clicks_by_day | Daily click breakdown | | link_top_referrers | Top traffic sources | | link_top_countries | Top countries | | link_top_devices | Device breakdown | | link_top_browsers | Browser breakdown |

Filter Operations

| Operator | Description | Example | |----------|-------------|---------| | eq | Equals | { "field": "country", "op": "eq", "value": "US" } | | ne | Not equals | { "field": "device_type", "op": "ne", "value": "bot" } | | contains | Contains substring | { "field": "path", "op": "contains", "value": "/blog" } | | starts_with | Starts with | { "field": "path", "op": "starts_with", "value": "/docs" } | | in | Value in array | { "field": "country", "op": "in", "value": ["US", "CA"] } | | not_in | Not in array | { "field": "browser", "op": "not_in", "value": ["bot"] } |

Event Tracking API

Send Single Event

POST https://basket.databuddy.cc/?client_id={website_id}

Request Body:

{
  "type": "custom",
  "name": "purchase",
  "anonymousId": "anon_user_123",
  "sessionId": "session_456",
  "timestamp": 1704067200000,
  "properties": {
    "value": 99.99,
    "currency": "USD",
    "product_id": "prod_123"
  }
}

Minimal Event:

{
  "type": "custom",
  "name": "newsletter_signup",
  "properties": { "source": "footer_form" }
}

Event Fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | type | string | Yes | Must be "custom" | | name | string | Yes | Event name (1-128 chars) | | anonymousId | string | No | Anonymous user identifier | | sessionId | string | No | Session identifier | | timestamp | number | No | Unix timestamp in ms | | properties | object | No | Custom properties |

Batch Events

POST https://basket.databuddy.cc/batch?client_id={website_id}

Request Body:

[
  { "type": "custom", "name": "event1", "properties": {...} },
  { "type": "custom", "name": "event2", "properties": {...} }
]

Response:

{
  "status": "success",
  "batch": true,
  "processed": 2,
  "results": [
    { "status": "success", "type": "custom", "eventId": "evt_123" },
    { "status": "success", "type": "custom", "eventId": "evt_124" }
  ]
}

Custom Queries

For advanced queries with custom aggregations:

POST /v1/query/custom?website_id={id}

Request Body:

{
  "query": {
    "table": "events",
    "selects": [
      { "field": "path", "aggregate": "count", "alias": "pageviews" },
      { "field": "anonymous_id", "aggregate": "uniq", "alias": "visitors" }
    ],
    "filters": [
      { "field": "country", "operator": "eq", "value": "US" }
    ],
    "groupBy": ["path"]
  },
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "limit": 100
}

Available Tables

| Table | Description | |-------|-------------| | events | Page views and custom events | | sessions | Session-level data | | profiles | User profile data | | errors | JavaScript errors | | performance | Web vitals metrics |

Aggregate Functions

| Function | Description | |----------|-------------| | count | Count rows | | uniq | Count unique values | | sum | Sum numeric values | | avg | Average value | | max | Maximum value | | min | Minimum value |

Error Codes

| Code | Meaning | |------|---------| | AUTH_REQUIRED | No API key or session provided | | ACCESS_DENIED | No access to requested resource | | INVALID_API_KEY | API key invalid or revoked | | INSUFFICIENT_SCOPE | API key lacks required scope | | RATE_LIMITED | Too many requests |

Rate Limits

• Standard queries: 200+ requests/minute
• Custom queries: 30 requests/minute

Health Check

GET /health

{
  "clickhouse": true,
  "database": true,
  "redis": true,
  "success": true,
  "version": "1.0.0"
}