Skip to main content

​
Overview

The Databuddy Analytics API provides privacy-first access to your website analytics data. Query pageviews, custom events, user sessions, and conversion funnels using a flexible REST API.

​
Base URL

https://api.databuddy.com/v1/query

​
Authentication

All analytics API requests require authentication using either:
  • API Key: Include in the Authorization header as Bearer <api_key>
  • Session Cookie: Authenticated user session
API keys require the read:data scope to access analytics endpoints.

​
Query Endpoint

The main analytics endpoint accepts flexible query requests: 
POST /v1/query

​
Query Parameters

​
website_id
string
The website ID to query analytics for. Required for website-specific queries.
​
schedule_id
string
The uptime schedule ID for uptime monitor queries.
​
link_id
string
The link ID for link shortener analytics.
​
organization_id
string
The organization ID for organization-level queries (e.g., LLM analytics).
​
timezone
string
default:"UTC"
Timezone for date calculations (e.g., America/New_York).

​
Request Body

​
parameters
array
required
Array of query types to execute. Can be strings (e.g., "top_pages") or objects with additional configuration:
{
  "name": "top_pages",
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "granularity": "daily",
  "id": "pages_query"
}
​
startDate
string
Start date in YYYY-MM-DD format or ISO datetime (e.g., 2024-01-01 or 2024-01-01T00:00:00Z).
​
endDate
string
End date in YYYY-MM-DD format or ISO datetime.
​
preset
string
Date preset to use instead of explicit dates. Options: today, yesterday, last_7d, last_14d, last_30d, last_90d, this_week, last_week, this_month, last_month, this_year.
​
granularity
string
default:"daily"
Time granularity for time-series queries: hourly, daily, hour, or day. Hourly queries support up to 30 days.
​
filters
array
Array of filters to apply to queries:
[
  {
    "field": "country",
    "op": "eq",
    "value": "US"
  },
  {
    "field": "device_type",
    "op": "in",
    "value": ["desktop", "mobile"]
  }
]
Available operators: eq, ne, contains, not_contains, starts_with, in, not_in.
​
limit
number
default:"100"
Maximum number of results per query (1-10000).
​
page
number
default:"1"
Page number for pagination (1-based).

​
Response

​
success
boolean
Indicates if the request was successful.
​
requestId
string
Unique request ID for tracking and debugging.
​
queryId
string
Query ID from the request (if provided).
​
data
array
Array of query results, one per parameter:
[
  {
    "parameter": "top_pages",
    "success": true,
    "data": [...],
    "error": null
  }
]
​
meta
object
Query metadata including parameters, pagination, and filter counts.

​
Available Query Types

Retrieve available query types and their configurations: 
GET /v1/query/types?include_meta=true
​
types
array
Array of available query type names.
​
configs
object
Configuration for each query type including allowed filters, limits, and customization options.
​
presets
array
Available date presets.

​
List Accessible Websites

Get websites accessible with your credentials: 
GET /v1/query/websites
​
websites
array
Array of websites you have access to query.
​
total
number
Total number of accessible websites.

​
Batch Queries

Execute multiple queries in a single request by passing an array of query objects: 
POST /v1/query?website_id=web_123
Content-Type: application/json

[
  {
    "id": "query_1",
    "parameters": ["top_pages"],
    "preset": "last_7d"
  },
  {
    "id": "query_2",
    "parameters": ["summary_metrics"],
    "preset": "last_30d"
  }
]

​
Error Handling

Error responses include detailed information: 
{
  "success": false,
  "error": "Invalid date preset: last_7days",
  "code": "VALIDATION_ERROR",
  "requestId": "req_abc123",
  "details": [
    {
      "field": "preset",
      "message": "Invalid date preset: last_7days",
      "suggestion": "Did you mean 'last_7d'? Valid presets: today, yesterday, last_7d, ..."
    }
  ]
}
Common error codes:
  • AUTH_REQUIRED (401): Authentication required
  • ACCESS_DENIED (403): No access to the resource
  • VALIDATION_ERROR (400): Invalid request parameters
  • MISSING_PROJECT_ID (400): Missing website_id or other project identifier

​
Example Request

curl -X POST 'https://api.databuddy.com/v1/query?website_id=web_abc123' \
  -H 'Authorization: Bearer db_key_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "parameters": [
      "top_pages",
      "summary_metrics",
      {
        "name": "events_by_date",
        "granularity": "hourly",
        "id": "hourly_trends"
      }
    ],
    "preset": "last_7d",
    "filters": [
      {
        "field": "country",
        "op": "eq",
        "value": "US"
      }
    ],
    "limit": 50
  }'

​
Next Steps

Pageview Analytics

Query pageview data and top pages

Custom Events

Track and query custom events

Session Analytics

Analyze user sessions and behavior

Funnel Analytics

Track conversion funnels

Build docs developers (and LLMs) love

Get started for freeTalk to us