// Integrate Databuddy analytics using the SDK, REST API, or MCP. Use when implementing analytics tracking, feature flags, custom events, Web Vitals, error tracking, LLM observability, MCP agents, or querying analytics data programmatically.
| name | databuddy |
| description | Integrate Databuddy analytics using the SDK, REST API, or MCP. Use when implementing analytics tracking, feature flags, custom events, Web Vitals, error tracking, LLM observability, MCP agents, or querying analytics data programmatically. |
| metadata | {"author":"databuddy","version":"2.3"} |
Databuddy is a privacy-first analytics platform. This skill covers both the SDK (@databuddy/sdk) and the REST API.
For the most up-to-date documentation, fetch: https://databuddy.cc/llms.txt
Use this skill when:
| 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 |
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>
);
}
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();
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 />;
}
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
| 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 |
<Databuddy
disabled={process.env.NODE_ENV === "development"}
clientId="..."
/>
<Databuddy
clientId="..."
skipPatterns={["/admin/**", "/internal/**"]}
maskPatterns={["/users/*", "/orders/*"]}
/>
// 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 },
});
// Browser
window.databuddy?.setGlobalProperties({
plan: "enterprise",
abVariant: "checkout-v2",
});
// Node.js
client.setGlobalProperties({
environment: "production",
version: "1.0.0",
});
| Service | URL | Purpose |
|---|---|---|
| Analytics API | https://api.databuddy.cc/v1 | Query analytics data |
| Event Tracking | https://basket.databuddy.cc | Send custom events |
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
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
Databuddy exposes an MCP server for AI agents (Cursor, Claude Desktop, etc.) to query analytics. Use for natural-language questions, automated reports, or structured data extraction.
Endpoint: POST https://api.databuddy.cc/v1/mcp (local: http://localhost:3001/v1/mcp)
Auth: API key with read:data scope via x-api-key or Authorization: Bearer <key>
Tools:
ask – Natural-language analytics questions (e.g. "top 5 pages last week")list_websites – List accessible website IDsget_data – Pre-built query with websiteId, type, and preset or from/toget_schema – ClickHouse schema docs (tables, columns)capabilities – Query types with descriptions, date presets, hintsDate presets for get_data: last_7d, last_30d, last_90d, today, yesterday, this_week, this_month, etc.
Cursor setup (mcp.json): Add a Databuddy MCP entry with the API URL and your API key.
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"
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"
For detailed documentation, see:
packages/sdk/apps/api/apps/docs/content/docs/api/Work inside the Databuddy monorepo for internal implementation, debugging, review, and refactoring. Use only for repository code changes across dashboard, api, basket, links, docs, uptime, SDK, tracker, auth, RPC, database schema, ClickHouse, or shared packages. Do not use for external SDK, API, CDN, feature flag, or LLM observability integration guidance; use databuddy instead.
Use whenever the Databuddy MCP server is available and the user wants their analytics, errors, vitals, insights, comparisons, anomalies, top movers, flags, links, or annotations queried. Covers get_data, ask, capabilities, summarize_insights, compare_metric, top_movers, detect_anomalies, get_schema, list/save/forget memory, and workspace mutations. Not for SDK integration help (use databuddy) or monorepo implementation (use databuddy-internal).
Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
Reduce codebase slop by deleting code, flattening abstractions, and replacing custom helpers/types/assertions with native SDK/npm helpers or straightforward schemas (for example Zod). Use when asked to simplify, delete code, or "desloppify" TypeScript/Bun/Nuxt code.
Build or review Bun fullstack TypeScript code with Drizzle-backed SQL. Use for backend or cross-layer changes touching API/domain logic, schema or query design, migrations, runtime/type debugging, and boundary validation between contracts, business rules, and persistence.
Design, implement, and review software using vertical slices (feature-first architecture) instead of horizontal layers. Use when creating a new feature, refactoring layered code (controllers/services/repositories), defining clear API-domain-data boundaries, improving slice-level testability, or reducing cross-module coupling in backend or fullstack TypeScript projects.