BlogPricingDashboardGitHubGitHub★ 898
API Reference

Analytics Queries

The Query API lets you fetch analytics data for your websites with flexible date ranges, filters, and aggregations.

Endpoints

MethodEndpointDescription
GET/v1/query/websitesList accessible websites
GET/v1/query/typesGet available query types
POST/v1/queryExecute analytics query

List Websites

Get all websites you have access to:

http
GET /v1/query/websites

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 Query Types

Discover available query types and their configurations. This endpoint is public and doesn't require authentication.

http
GET /v1/query/types?include_meta=true

Set include_meta=true to get descriptions, output fields, and visualization hints.

Response:

json
{
"success": true,
"types": ["summary", "pages", "traffic", "browser_name", "..."],
"configs": {
  "summary": {
    "allowedFilters": ["country", "device_type", "browser_name"],
    "customizable": true,
    "defaultLimit": 100,
    "meta": {
      "description": "Overall website metrics and KPIs",
      "outputFields": ["pageviews", "visitors", "sessions", "..."]
    }
  }
}
}

Execute Query

Query analytics data with full parameter control:

http
POST /v1/query?website_id={id}

Query Parameters:

ParameterRequiredDescription
website_idYes*Website to query
link_idYes*Link shortener ID (for link analytics)
schedule_idYes*Uptime monitor ID (for uptime analytics)
timezoneNoTimezone for date calculations (default: UTC)

*One of website_id, link_id, or schedule_id is required.

Request Body:

json
{
"parameters": ["summary", "pages", "browser_name"],
"startDate": "2024-01-01",
"endDate": "2024-01-31",
"limit": 100,
"page": 1,
"filters": [
  {
    "field": "country",
    "op": "in",
    "value": ["US", "CA"]
  }
],
"granularity": "daily"
}

Request Body Fields:

FieldTypeRequiredDescription
parametersarrayYesQuery types to execute
startDatestringConditionalStart date (YYYY-MM-DD). Required if no preset
endDatestringConditionalEnd date (YYYY-MM-DD). Required if no preset
presetstringConditionalDate preset instead of explicit dates
idstringNoQuery identifier returned in response
limitnumberNoMax results per parameter (default: 100, max: 10000)
pagenumberNoPage number for pagination (default: 1)
filtersarrayNoFilter conditions
granularitystringNo"hourly" or "daily" (default: daily)
groupBystring/arrayNoFields to group results by

Date Presets

Instead of specifying startDate and endDate, use a preset for common date ranges:

PresetDescription
todayCurrent day
yesterdayPrevious day
last_7dLast 7 days including today
last_14dLast 14 days including today
last_30dLast 30 days including today
last_90dLast 90 days including today
this_weekCurrent week (Sunday to today)
last_weekPrevious full week
this_monthCurrent month to date
last_monthPrevious full month
this_yearCurrent year to date

Example with preset:

json
{
"parameters": ["summary", "pages"],
"preset": "last_30d",
"limit": 10
}

Parameters with Custom Date Ranges

Each parameter can have its own date range:

json
{
"parameters": [
  "summary",
  {
    "name": "pages",
    "start_date": "2024-01-01",
    "end_date": "2024-01-15",
    "id": "pages-first-half"
  }
],
"startDate": "2024-01-01",
"endDate": "2024-01-31"
}

Response Format

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 Queries

Execute multiple queries in a single request by sending an array:

json
[
{
  "id": "query-1",
  "parameters": ["summary", "pages"],
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "limit": 100
},
{
  "id": "query-2", 
  "parameters": ["browser_name", "os_name"],
  "startDate": "2024-01-01",
  "endDate": "2024-01-31",
  "limit": 50
}
]

Batch Response:

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

Filter Operations

OperatorDescriptionExample Value
eqEquals"US"
neNot equals"bot"
containsContains substring"chrome"
not_containsDoes not contain"preview"
starts_withStarts with prefix"/blog"
inValue in array["US", "CA", "UK"]
not_inValue not in array["bot", "crawler"]

Common Filter Fields

FieldAvailable OnExample
countryMost queries{"field": "country", "op": "eq", "value": "US"}
device_typeMost queries{"field": "device_type", "op": "in", "value": ["mobile", "tablet"]}
browser_nameMost queries{"field": "browser_name", "op": "eq", "value": "Chrome"}
os_nameMost queries{"field": "os_name", "op": "eq", "value": "iOS"}
pathpages, sessions{"field": "path", "op": "starts_with", "value": "/blog"}
referrertraffic{"field": "referrer", "op": "contains", "value": "google"}

Granularity

Control time-based aggregation:

  • "daily" — Group by day (default)
  • "hourly" — Group by hour (max 30 days range)
json
{
"parameters": ["summary"],
"startDate": "2024-01-01",
"endDate": "2024-01-07",
"granularity": "hourly"
}

Pagination

Use page and limit for large result sets:

json
{
"parameters": ["pages"],
"startDate": "2024-01-01",
"endDate": "2024-01-31",
"limit": 50,
"page": 2
}

Page numbering starts at 1.

How is this guide?

Edit on GitHub