Skip to main content
POST
/
v1
/
query
Query Events
curl --request POST \
  --url https://api.example.com/v1/query \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "id": "<string>",
  "parameters": [
    {}
  ],
  "preset": "<string>",
  "startDate": "<string>",
  "endDate": "<string>",
  "granularity": "<string>",
  "filters": [
    {}
  ],
  "limit": 123,
  "page": 123
}
'
{
  "success": true,
  "requestId": "<string>",
  "queryId": "<string>",
  "data": [
    {}
  ],
  "meta": {}
}

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/databuddy-analytics/Databuddy/llms.txt

Use this file to discover all available pages before exploring further.

The query endpoint provides powerful analytics capabilities for querying event data with support for multiple metrics, date ranges, filters, and time-based aggregations.

​
Authentication

This endpoint requires authentication via:
  1. API Key: Include in the Authorization header. The API key must have the read:data scope.
  2. Session: User must be authenticated and have access to the specified project.

​
Request

​
Headers

​
Authorization
string
Bearer token with your API key (if using API key authentication)
​
Content-Type
string
required
Must be application/json

​
Query Parameters

​
website_id
string
UUID of the website to query data for
​
schedule_id
string
UUID of the uptime monitor schedule to query
​
link_id
string
UUID of the short link to query
​
organization_id
string
UUID of the organization for org-level queries
​
timezone
string
Timezone for date calculations (e.g., “America/New_York”, “UTC”). Defaults to UTC.

​
Body Parameters

​
id
string
Unique identifier for this query request
​
parameters
array
required
Array of query types to execute. Can be strings (e.g., "page_views") or objects with additional config:
  • name (string, required): Query type name
  • id (string, optional): Custom identifier for this parameter
  • start_date (string, optional): Override start date for this parameter
  • end_date (string, optional): Override end date for this parameter
  • granularity (string, optional): Time granularity (“hourly” or “daily”)
​
preset
string
Date range preset. Options: today, yesterday, last_7_days, last_30_days, last_90_days, this_month, last_month, this_year
​
startDate
string
Start date in YYYY-MM-DD format or ISO datetime. Required if no preset provided.
​
endDate
string
End date in YYYY-MM-DD format or ISO datetime. Required if no preset provided.
​
granularity
string
Time granularity for aggregation: "hourly" or "daily". Hourly limited to 30 days max.
​
filters
array
Array of filter objects to apply:
  • field (string): Field to filter on (e.g., “path”, “country”, “browser”)
  • operator (string): Filter operator (“eq”, “ne”, “contains”, “not_contains”, etc.)
  • value (string | number | array): Filter value
​
limit
number
Maximum number of results per parameter (1-10000). Default: 100
​
page
number
Page number for pagination (1-based). Default: 1

​
Response

​
success
boolean
Whether the query executed successfully
​
requestId
string
Unique identifier for this request
​
queryId
string
Query ID from the request (if provided)
​
data
array
Array of result objects, one per parameter:
  • parameter (string): Parameter name or ID
  • success (boolean): Whether this specific query succeeded
  • data (array): Result rows
  • error (string, optional): Error message if failed
​
meta
object
Query metadata:
  • parameters (array): Original parameters from request
  • total_parameters (number): Number of parameters queried
  • page (number): Current page number
  • limit (number): Results per page
  • filters_applied (number): Number of filters applied

​
Available Query Types

To get a list of all available query types and their configurations: 
curl https://api.databuddy.io/v1/query/types
Common query types include:
  • page_views - Total page views
  • visitors - Unique visitors
  • sessions - Session count
  • bounce_rate - Bounce rate percentage
  • pages - Top pages
  • referrers - Top referrers
  • countries - Traffic by country
  • browsers - Browser distribution
  • devices - Device types
  • events - Custom event tracking

​
Examples

​
Single Query with Preset

curl -X POST 'https://api.databuddy.io/v1/query?website_id=550e8400-e29b-41d4-a716-446655440000' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": ["page_views", "visitors"],
    "preset": "last_7_days"
  }'
Response
{
  "success": true,
  "requestId": "req_abc123",
  "queryId": "",
  "data": [
    {
      "parameter": "page_views",
      "success": true,
      "data": [
        {
          "date": "2024-03-01",
          "value": 1250
        },
        {
          "date": "2024-03-02",
          "value": 1430
        }
      ]
    },
    {
      "parameter": "visitors",
      "success": true,
      "data": [
        {
          "date": "2024-03-01",
          "value": 845
        },
        {
          "date": "2024-03-02",
          "value": 923
        }
      ]
    }
  ],
  "meta": {
    "parameters": ["page_views", "visitors"],
    "total_parameters": 2,
    "page": 1,
    "limit": 100,
    "filters_applied": 0
  }
}

​
Custom Date Range with Filters

curl -X POST 'https://api.databuddy.io/v1/query?website_id=550e8400-e29b-41d4-a716-446655440000&timezone=America/New_York' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": ["pages"],
    "startDate": "2024-03-01",
    "endDate": "2024-03-07",
    "filters": [
      {
        "field": "country",
        "operator": "eq",
        "value": "US"
      }
    ],
    "limit": 10
  }'
Response
{
  "success": true,
  "requestId": "req_xyz789",
  "queryId": "",
  "data": [
    {
      "parameter": "pages",
      "success": true,
      "data": [
        {
          "path": "/home",
          "views": 4523,
          "visitors": 3201
        },
        {
          "path": "/pricing",
          "views": 2341,
          "visitors": 1876
        },
        {
          "path": "/features",
          "views": 1987,
          "visitors": 1543
        }
      ]
    }
  ],
  "meta": {
    "parameters": ["pages"],
    "total_parameters": 1,
    "page": 1,
    "limit": 10,
    "filters_applied": 1
  }
}

​
Hourly Granularity

curl -X POST 'https://api.databuddy.io/v1/query?website_id=550e8400-e29b-41d4-a716-446655440000' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": ["page_views"],
    "startDate": "2024-03-01",
    "endDate": "2024-03-02",
    "granularity": "hourly"
  }'

​
Batch Query with Multiple Requests

curl -X POST 'https://api.databuddy.io/v1/query?website_id=550e8400-e29b-41d4-a716-446655440000' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": "query_1",
      "parameters": ["page_views"],
      "preset": "today"
    },
    {
      "id": "query_2",
      "parameters": ["visitors"],
      "preset": "yesterday"
    }
  ]'
Response
{
  "success": true,
  "requestId": "req_batch123",
  "batch": true,
  "results": [
    {
      "queryId": "query_1",
      "data": [
        {
          "parameter": "page_views",
          "success": true,
          "data": [...]
        }
      ],
      "meta": {...}
    },
    {
      "queryId": "query_2",
      "data": [
        {
          "parameter": "visitors",
          "success": true,
          "data": [...]
        }
      ],
      "meta": {...}
    }
  ]
}

​
Error Responses

​
Authentication Required

{
  "success": false,
  "error": "Authentication required",
  "code": "AUTH_REQUIRED",
  "requestId": "req_abc123"
}

​
Access Denied

{
  "success": false,
  "error": "Access denied to this website",
  "code": "ACCESS_DENIED",
  "requestId": "req_abc123"
}

​
Validation Error

{
  "success": false,
  "error": "Unknown query type: pageviews. Did you mean 'page_views'?",
  "code": "VALIDATION_ERROR",
  "requestId": "req_abc123",
  "details": [
    {
      "field": "parameters[0]",
      "message": "Unknown query type: pageviews",
      "suggestion": "Did you mean 'page_views'?"
    }
  ]
}

​
Missing Project ID

{
  "success": false,
  "error": "Missing project identifier (website_id, schedule_id, link_id, or organization_id)",
  "code": "MISSING_PROJECT_ID",
  "requestId": "req_abc123"
}
  • GET /v1/query/websites - List accessible websites
  • GET /v1/query/types - Get available query types and configurations
  • POST /v1/query/compile - Compile a query to SQL without executing
  • POST /v1/query/custom - Execute custom SQL-like queries

Build docs developers (and LLMs) love

Get started for freeTalk to us