BlogPricingDashboardGitHubGitHub★ 655

API Reference

Access your analytics data programmatically with Databuddy's REST API. All endpoints require authentication and are rate-limited for security.

Authentication

All API requests require authentication using either session cookies (for browser-based requests) or API keys (for programmatic access). The API supports both authentication methods seamlessly.

For browser-based requests, use your session cookies from the dashboard:

bash
curl -H "Cookie: your-session-cookie" \
https://api.databuddy.cc/v1/query/websites

API Key Authentication

For programmatic access, use your API key in the x-api-key header:

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

API Key Scopes:

  • read:analytics - Read analytics data and query types
  • write:custom-sql - Execute custom SQL queries
  • read:data - Access specific website data (requires website-specific or global access)

API Key Access Levels:

  • Global Access: Access all websites in your account/organization
  • Website-Specific Access: Access only specified websites

Base URLs

  • Analytics API: https://api.databuddy.cc/v1
  • Event Tracking (Basket): https://basket.databuddy.cc

Analytics Query API

Get Accessible Websites

Get all websites you have access to through your authentication method.

http
GET /v1/query/websites

Authentication: Requires session cookie or API key with appropriate access.

Response:

json
{
"success": true,
"websites": [
  {
    "id": "web_123",
    "name": "My Website",
    "domain": "example.com",
    "isPublic": false,
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
],
"total": 1
}

Get Available Query Types

Get all available query types and their configurations.

http
GET /v1/query/types

Parameters:

  • include_meta (optional, boolean) - Include detailed metadata about query types including descriptions, output fields, and visualization hints

Response:

json
{
"success": true,
"types": ["summary", "pages", "traffic", "devices", "geo", "errors", "performance", "sessions", "custom_events", "profiles", "links", "engagement"],
"configs": {
  "summary": {
    "allowedFilters": ["date", "country", "device", "browser"],
    "customizable": true,
    "defaultLimit": 100
  },
  "pages": {
    "allowedFilters": ["date", "path"],
    "customizable": true,
    "defaultLimit": 50
  },
  "browser_name": {
    "allowedFilters": ["date", "browser", "country"],
    "customizable": true,
    "defaultLimit": 100,
    "meta": {
      "title": "Browser Usage",
      "description": "Website traffic breakdown by browser type showing which browsers your visitors use most.",
      "category": "Technology",
      "tags": ["browsers", "technology", "devices", "compatibility"],
      "output_fields": [
        {
          "name": "name",
          "type": "string",
          "label": "Browser Name",
          "description": "The browser name (Chrome, Firefox, Safari, etc.)"
        },
        {
          "name": "pageviews",
          "type": "number",
          "label": "Pageviews",
          "description": "Total pageviews from this browser"
        }
      ],
      "default_visualization": "pie",
      "supports_granularity": ["hour", "day"],
      "version": "1.0"
    }
  }
}
}

Execute Dynamic Analytics Query

Execute analytics queries with advanced parameter support, including batch processing and flexible date ranges.

http
POST /v1/query

Query Parameters:

  • website_id (required) - The website ID to query
  • start_date or startDate (optional) - Default start date for all parameters
  • end_date or endDate (optional) - Default end date for all parameters
  • timezone (optional) - Timezone for date calculations

Single Query Request:

json
{
"id": "my-query-123",
"parameters": ["summary", "pages", "browser_name"],
"limit": 100,
"page": 1,
"filters": [
  {
    "field": "country",
    "op": "in",
    "value": ["US", "CA"]
  },
  {
    "field": "device_type",
    "op": "eq",
    "value": "desktop"
  }
],
"granularity": "daily"
}

Advanced Parameter Objects:

json
{
"id": "advanced-query",
"parameters": [
  "summary",
  {
    "name": "pages",
    "start_date": "2024-01-01",
    "end_date": "2024-01-07",
    "granularity": "hourly",
    "id": "pages-last-week"
  },
  {
    "name": "browser_name",
    "start_date": "2024-01-15",
    "end_date": "2024-01-31",
    "id": "browsers-recent"
  }
],
"limit": 50
}

Batch Query Request:

json
[
{
  "id": "query-1",
  "parameters": ["summary", "pages"],
  "limit": 100
},
{
  "id": "query-2", 
  "parameters": ["browser_name", "os_name"],
  "limit": 50,
  "filters": [
    {
      "field": "country",
      "op": "eq",
      "value": "US"
    }
  ]
}
]

Available Query Types:

  • summary - Overall website metrics and KPIs
  • pages - Page views and performance data
  • traffic - Traffic sources and referrers
  • browser_name - Browser usage analytics
  • os_name - Operating system analytics
  • device_types - Device category breakdown
  • countries - Geographic visitor data by country
  • cities - Geographic visitor data by city
  • errors - JavaScript errors and issues
  • performance - Web vitals and performance metrics
  • sessions - Session-based analytics
  • custom_events - Custom event tracking data
  • profiles - User profile analytics
  • links - Outgoing link tracking
  • engagement - User engagement metrics

Filter Operations:

  • eq - Equals
  • ne - Not equals
  • like - Contains (case-insensitive)
  • gt - Greater than
  • lt - Less than
  • in - In array
  • notIn - Not in array

Single Query Response:

json
{
"success": true,
"queryId": "my-query-123",
"data": [
  {
    "parameter": "summary",
    "success": true,
    "data": [
      {
        "date": "2024-01-01",
        "pageviews": 1250,
        "visitors": 890,
        "sessions": 1100
      }
    ]
  },
  {
    "parameter": "pages",
    "success": true,
    "data": [
      {
        "path": "/",
        "pageviews": 450,
        "visitors": 320
      }
    ]
  }
],
"meta": {
  "parameters": ["summary", "pages"],
  "total_parameters": 2,
  "page": 1,
  "limit": 100,
  "filters_applied": 2
}
}

Batch Query Response:

json
{
"success": true,
"batch": true,
"results": [
  {
    "success": true,
    "queryId": "query-1",
    "data": [...]
  },
  {
    "success": true,
    "queryId": "query-2", 
    "data": [...]
  }
]
}

Compile Query (Advanced)

Compile a query to see the generated SQL without executing it. Useful for debugging and understanding query structure.

http
POST /v1/query/compile

Query Parameters:

  • website_id (optional) - Website ID for domain-specific compilation

Request:

json
{
"projectId": "web_123",
"type": "summary",
"from": "2024-01-01",
"to": "2024-01-31",
"timeUnit": "day",
"filters": [
  {
    "field": "country",
    "op": "in",
    "value": ["US", "CA"]
  }
],
"limit": 100,
"offset": 0
}

Response:

json
{
"success": true,
"sql": "SELECT toDate(time) as date, count(*) as pageviews, count(distinct anonymous_id) as visitors FROM analytics.events WHERE time >= '2024-01-01' AND time <= '2024-01-31' AND country IN ('US', 'CA') GROUP BY date ORDER BY date LIMIT 100",
"parameters": {
  "projectId": "web_123",
  "from": "2024-01-01",
  "to": "2024-01-31",
  "filters": [{"field": "country", "op": "in", "value": ["US", "CA"]}]
}
}

AI Assistant

Stream Analytics Query

Use natural language to query your analytics data with streaming responses.

http
POST /v1/assistant/stream

Request:

json
{
"websiteId": "web_123",
"message": "Show me the top pages by pageviews last week",
"context": {
  "dateRange": {
    "start": "2024-01-01",
    "end": "2024-01-07"
  }
}
}

Response (Server-Sent Events):

json
data: {"type": "thinking", "content": "Analyzing your page views..."}

data: {"type": "query", "content": "SELECT path, COUNT(*) as pageviews FROM analytics.events..."}

data: {"type": "complete", "content": "Here are your top pages:", "data": {"results": [{"path": "/", "pageviews": 1250}]}}

Data Export

Export Analytics Data

Export analytics data in various formats (CSV, JSON).

http
POST /v1/export

Request:

json
{
"websiteId": "web_123",
"type": "summary",
"format": "csv",
"startDate": "2024-01-01",
"endDate": "2024-01-31",
"timezone": "UTC"
}

Response: Returns a downloadable file in the requested format.

Event Tracking

Send Custom Events

Track custom events programmatically using the basket endpoint.

http
POST basket.databuddy.cc/?client_id={website_id}

Single Custom Event Request:

json
{
"type": "custom",
"name": "purchase",
"anonymousId": "anon_user_123",
"sessionId": "session_456",
"timestamp": 1704067200000,
"properties": {
  "value": 99.99,
  "currency": "USD",
  "product_id": "prod_123"
}
}

Minimal Custom Event (without session/user tracking):

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

Batch Custom Events Request:

http
POST basket.databuddy.cc/batch?client_id={website_id}
json
[
{
  "type": "custom",
  "name": "purchase",
  "anonymousId": "anon_user_123",
  "sessionId": "session_456",
  "timestamp": 1704067200000,
  "properties": {
    "value": 99.99,
    "currency": "USD",
    "product_id": "prod_123"
  }
},
{
  "type": "custom",
  "name": "signup",
  "anonymousId": "anon_user_124",
  "sessionId": "session_457",
  "timestamp": 1704067260000,
  "properties": {
    "plan": "premium",
    "source": "landing_page"
  }
}
]

Required Fields:

  • type: Must be "custom"
  • name: Event name (1-128 characters)

Optional Fields:

  • anonymousId: Anonymous user identifier (max 128 characters) - not needed for all use cases
  • sessionId: Session identifier (max 128 characters) - not needed for all use cases
  • timestamp: Unix timestamp in milliseconds (defaults to current time)
  • properties: JSON object with custom event properties

Response:

json
{
"status": "success",
"type": "custom"
}

Batch Response:

json
{
"status": "success",
"batch": true,
"processed": 2,
"results": [
  {
    "status": "success",
    "type": "custom",
    "eventId": "evt_12345"
  },
  {
    "status": "success", 
    "type": "custom",
    "eventId": "evt_12346"
  }
]
}

Health Check

API Health Status

Check the health status of the API and its dependencies.

http
GET /health

Response:

json
{
"clickhouse": true,
"database": true,
"redis": true,
"success": true,
"version": "1.0.0",
"timestamp": "2024-01-01T12:00:00.000Z"
}

Rate Limits

API endpoints have different rate limits based on their computational cost and your subscription plan:

Plan-Based Rate Limits

Rate limits vary by your subscription tier:

  • Free: 50 requests per 10 seconds (300/minute)
  • Hobby: 100 requests per 10 seconds (600/minute)
  • Pro: 200 requests per 10 seconds (1,200/minute)
  • Scale: 500 requests per 10 seconds (3,000/minute)

Endpoint-Specific Rate Limits

Certain endpoints have additional restrictions:

  • Public endpoints: 100 requests per minute
  • Authentication endpoints: 30 requests per minute
  • Custom SQL: 30 requests per minute (heavy operations)

Rate limit headers are included in responses:

http
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Error Handling

All errors follow a consistent format:

json
{
"success": false,
"error": "Website not found or access denied",
"code": "WEBSITE_NOT_FOUND"
}

Common Error Codes:

  • AUTH_REQUIRED - Authentication required (missing session cookie or API key)
  • WEBSITE_NOT_FOUND - Website not found or no access
  • INVALID_QUERY_TYPE - Unknown query type
  • VALIDATION_ERROR - Request validation failed
  • RATE_LIMIT_EXCEEDED - Too many requests
  • INTERNAL_SERVER_ERROR - Server error occurred
  • CLIENT_ACCESS_DENIED - API key does not have access to specified resource
  • INSUFFICIENT_SCOPE - API key lacks required scopes
  • FORBIDDEN_OPERATION - Operation not allowed with current permissions

Practical Examples

Getting Started Workflow

  1. Get your accessible websites:
bash
curl -H "x-api-key: dbdy_your_api_key_here" \
https://api.databuddy.cc/v1/query/websites
  1. Explore available query types:
bash
curl -H "x-api-key: dbdy_your_api_key_here" \
"https://api.databuddy.cc/v1/query/types?include_meta=true"
  1. Execute a simple query:
bash
curl -X POST -H "x-api-key: dbdy_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
  "id": "dashboard-summary",
  "parameters": ["summary", "pages", "browser_name"],
  "limit": 10
}' \
"https://api.databuddy.cc/v1/query?website_id=web_123&start_date=2024-01-01&end_date=2024-01-31&timezone=UTC"

Advanced Multi-Period Analysis

Compare different time periods with parameter-specific date ranges:

bash
curl -X POST -H "x-api-key: dbdy_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
  "id": "period-comparison",
  "parameters": [
    {
      "name": "summary",
      "start_date": "2024-01-01",
      "end_date": "2024-01-15",
      "id": "first-half-jan"
    },
    {
      "name": "summary", 
      "start_date": "2024-01-16",
      "end_date": "2024-01-31",
      "id": "second-half-jan"
    }
  ]
}' \
"https://api.databuddy.cc/v1/query?website_id=web_123&timezone=America/New_York"

Batch Processing Multiple Websites

Process multiple queries for different websites simultaneously:

bash
curl -X POST -H "x-api-key: dbdy_your_api_key_here" \
-H "Content-Type: application/json" \
-d '[
  {
    "id": "website-1-analysis",
    "parameters": ["summary", "pages"],
    "filters": [{"field": "country", "op": "eq", "value": "US"}]
  },
  {
    "id": "website-2-analysis", 
    "parameters": ["browser_name", "os_name"],
    "limit": 20
  }
]' \
"https://api.databuddy.cc/v1/query?website_id=web_123&start_date=2024-01-01&end_date=2024-01-31"
Edit on GitHub