Query Events

Query and analyze event data with flexible filtering and aggregation

POST /v1/query

Query Events

cURL

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
}
'

200

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

Related Endpoints

• 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