shield_lock
JinDaGe
← Back to skills
extension
Category: Marketing & GrowthNo API key required

databuddy-api

Use the Databuddy REST API for programmatic access to analytics data. Use when querying analytics data, building custom dashboards, sending events via API, or integrating analytics into backend services.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

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