Databuddy

Databuddy is a privacy-first analytics platform. This skill covers both the SDK (@databuddy/sdk) and the REST API.

External Documentation

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

When to Use This Skill

Use this skill when:

• Setting up analytics in React/Next.js/Vue applications
• Implementing server-side tracking in Node.js
• Adding feature flags to an application
• Tracking custom events, errors, or Web Vitals
• Integrating LLM observability with Vercel AI SDK
• Querying analytics data via the REST API or MCP
• Building MCP agents or AI-powered analytics workflows
• Building custom dashboards or reports

SDK Entry Points

Import Path	Environment	Description
@databuddy/sdk	Browser (Core)	Core tracking utilities and types
@databuddy/sdk/react	React/Next.js	React component and hooks
@databuddy/sdk/node	Node.js/Server	Server-side tracking with batching
@databuddy/sdk/vue	Vue.js	Vue plugin and composables
@databuddy/sdk/ai/vercel	AI/LLM	Vercel AI SDK middleware for LLM analytics

Quick Start

React/Next.js

import { Databuddy } from "@databuddy/sdk/react";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Databuddy
          clientId={process.env.NEXT_PUBLIC_DATABUDDY_CLIENT_ID}
          trackWebVitals
          trackErrors
          trackPerformance
        />
      </body>
    </html>
  );
}

Node.js Server-Side

import { Databuddy } from "@databuddy/sdk/node";

const client = new Databuddy({
  clientId: process.env.DATABUDDY_CLIENT_ID,
  enableBatching: true,
});

await client.track({
  name: "api_call",
  properties: { endpoint: "/users", method: "GET" },
});

// Important: flush before process exit in serverless
await client.flush();

Feature Flags

import { FlagsProvider, useFlag, useFeature } from "@databuddy/sdk/react";

// Wrap your app
<FlagsProvider clientId="..." user={{ userId: "123" }}>
  <App />
</FlagsProvider>

// In components
function MyComponent() {
  const { on, loading } = useFeature("dark-mode");
  if (loading) return <Skeleton />;
  return on ? <DarkTheme /> : <LightTheme />;
}

LLM Analytics

import { databuddyLLM } from "@databuddy/sdk/ai/vercel";
import { openai } from "@ai-sdk/openai";

const { track } = databuddyLLM({
  apiKey: process.env.DATABUDDY_API_KEY,
});

const model = track(openai("gpt-4o"));
// All LLM calls are now automatically tracked

Key Configuration Options

Option	Type	Default	Description
clientId	string	Auto-detect	Project client ID
disabled	boolean	false	Disable all tracking
trackWebVitals	boolean	false	Track Web Vitals metrics
trackErrors	boolean	false	Track JavaScript errors
trackPerformance	boolean	true	Track performance metrics
enableBatching	boolean	true	Enable event batching
samplingRate	number	1.0	Sampling rate (0.0-1.0)
skipPatterns	string[]	—	Glob patterns to skip tracking

Common Patterns

Disable in Development

<Databuddy
  disabled={process.env.NODE_ENV === "development"}
  clientId="..."
/>

Skip Sensitive Paths

<Databuddy
  clientId="..."
  skipPatterns={["/admin/**", "/internal/**"]}
  maskPatterns={["/users/*", "/orders/*"]}
/>

Custom Event Tracking

// Browser
import { track } from "@databuddy/sdk/react";

track("purchase", {
  product_id: "sku-123",
  amount: 99.99,
  currency: "USD",
});

// Node.js
await client.track({
  name: "subscription_renewed",
  properties: { plan: "pro", amount: 29.99 },
});

Global Properties

// Browser
window.databuddy?.setGlobalProperties({
  plan: "enterprise",
  abVariant: "checkout-v2",
});

// Node.js
client.setGlobalProperties({
  environment: "production",
  version: "1.0.0",
});

REST API

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

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

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

Get API keys from: Dashboard → Organization Settings → API Keys

Query Analytics Data

curl -X POST -H "x-api-key: dbdy_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": ["summary", "pages"],
    "preset": "last_30d"
  }' \
  "https://api.databuddy.cc/v1/query?website_id=web_123"

Available Query Types:

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
device_types	Device category breakdown
countries	Visitors by country
errors	JavaScript errors
performance	Web vitals and load times
custom_events	Custom event data

Date Presets: today, yesterday, last_7d, last_30d, last_90d, this_month, last_month

MCP (Model Context Protocol)

Databuddy exposes an MCP server for AI agents (Claude, Claude Code, Cursor, Windsurf, etc.) to query analytics, read investigations, and manage goals, funnels, annotations, flags, and links. Use for analytics questions, automated reports, or structured data extraction.

Endpoint: POST https://api.databuddy.cc/v1/mcp (local: http://localhost:3001/v1/mcp)

Auth: Claude and Claude Code sign in with a Databuddy account (OAuth), no key needed. Other clients, including Cursor, send an API key via x-api-key or Authorization: Bearer <key>. read:data covers analytics and reads; add manage:websites for goal, funnel, annotation, and investigation-reply writes, manage:flags for flag mutations, and organization-wide read:links (link reads) plus write:links (link mutations) for short links. Tools the key lacks scopes for are hidden from tools/list.

Tools: Use the live tools/list and the databuddy://guide resource; see https://www.databuddy.cc/docs/api/mcp for the full list. Start with list_websites, capabilities, and get_data.

Dates for get_data: a preset such as last_7d, last_30d, last_90d, today, or yesterday, or both from and to. Defaults to last_30d.

Cursor setup (mcp.json): Add a Databuddy MCP entry with the API URL and your API key in the x-api-key header.

Send Events via API

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "type": "custom",
    "name": "purchase",
    "properties": {
      "value": 99.99,
      "currency": "USD"
    }
  }' \
  "https://basket.databuddy.cc/?client_id=web_123"

Batch Events

curl -X POST \
  -H "Content-Type: application/json" \
  -d '[
    {"type": "custom", "name": "event1", "properties": {...}},
    {"type": "custom", "name": "event2", "properties": {...}}
  ]' \
  "https://basket.databuddy.cc/batch?client_id=web_123"

Reference Documentation

For detailed documentation, see:

• Core SDK Reference - Browser tracking utilities and types
• React Integration - React/Next.js component and hooks
• Node.js Integration - Server-side tracking with batching
• Feature Flags - Feature flags for all platforms
• AI/LLM Tracking - Vercel AI SDK integration
• REST API Reference - Full REST API documentation

Source Code

• SDK: packages/sdk/
• API: apps/api/
• API Docs: apps/docs/content/docs/api/