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": {}
}
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