---

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

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