---

name: databuddy-api description: 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. metadata: author: databuddy version: "2.3"

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

Authentication

API Key

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

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

Or use Bearer token format:

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

Query Endpoints

List Websites

CopyGET /v1/query/websites

Response:

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

Get Query Types

CopyGET /v1/query/types?include_meta=true

Returns available query types and their configurations.

Execute Query

CopyPOST /v1/query?website_id={id}

Request Body:

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

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

Date Presets:

Response:

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

Link Shortener Analytics

Use link_id instead of website_id:

Filter Operations

Event Tracking API

Send Single Event

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

Request Body:

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

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

Event Fields

Batch Events

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

Request Body:

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

Response:

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

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

Request Body:

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

Aggregate Functions

Error Codes

Rate Limits

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

Health Check

CopyGET /health

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