Analytics queries
The Query API lets you fetch analytics data for your websites with flexible date ranges, filters, and aggregations.
For a complete task using a scoped key, a selected website and checked query results, follow the REST reporting walkthrough. It includes a runnable script and explains empty responses, timezones and partial failures.
Endpoints
Public website access
When a website owner enables public sharing, anonymous viewers can request only the unfiltered aggregate overview. The /v1/query/types response marks these query types with publicAccess: true. Date ranges and the overview's fixed breakdowns remain available.
Custom events, arbitrary event properties, error diagnostics, audience details, web vitals, profiles, and revenue require authenticated website permission. Filters also require website permission, including trait, visitor identifier, and ordinary dimension filters. A batch containing a private query or any filter is rejected before execution unless the caller has website permission. The same policy applies to /v1/query/compile.
Public overview counts can include small groups, and page, referrer, or campaign labels can contain information supplied by your application. Public sharing does not apply a minimum group size or guarantee statistical anonymity. Review these labels and your traffic before publishing an overview, and keep sharing disabled when the overview itself could reveal personal information.
List websites
Get all websites you have access to:
GET /v1/query/websitesResponse:
{
"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.
GET /v1/query/types?include_meta=trueSet include_meta=true to get descriptions, output fields, and visualization hints.
Response:
{
"success": true,
"types": ["summary_metrics", "top_pages", "traffic_sources", "browser_name", "..."],
"configs": {
"summary_metrics": {
"allowedFilters": ["country", "device_type", "browser_name"],
"customizable": true,
"defaultLimit": 100,
"meta": {
"description": "Overall website metrics and KPIs",
"output_fields": [
{ "name": "pageviews", "type": "number" },
{ "name": "unique_visitors", "type": "number" },
{ "name": "sessions", "type": "number" }
]
}
}
}
}Execute query
Query analytics data with full parameter control:
POST /v1/query?website_id={id}Query parameters:
*One of website_id, link_id, schedule_id, or organization_id is required unless the signed-in session or global API key supplies an organization context.
Request body:
{
"parameters": ["summary_metrics", "top_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:
Date presets
Instead of specifying startDate and endDate, use a preset for common date ranges:
Example with preset:
{
"parameters": ["summary_metrics", "top_pages"],
"preset": "last_30d",
"limit": 10
}Parameters with custom date ranges
Each parameter can have its own date range:
{
"parameters": [
"summary_metrics",
{
"name": "top_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
{
"success": true,
"queryId": "my-query-123",
"data": [
{
"parameter": "summary_metrics",
"success": true,
"data": [
{
"date": "2024-01-01",
"pageviews": 1250,
"unique_visitors": 890,
"sessions": 1100
}
]
},
{
"parameter": "top_pages",
"success": true,
"data": [
{
"name": "/",
"pageviews": 450,
"visitors": 320
}
]
}
],
"meta": {
"parameters": ["summary_metrics", "top_pages"],
"total_parameters": 2,
"page": 1,
"limit": 100,
"filters_applied": 2
}
}Batch queries
Execute multiple queries in a single request by sending an array:
[
{
"id": "query-1",
"parameters": ["summary_metrics", "top_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:
{
"success": true,
"batch": true,
"results": [
{
"queryId": "query-1",
"data": [...],
"meta": {...}
},
{
"queryId": "query-2",
"data": [...],
"meta": {...}
}
]
}Filter operations
Common filter fields
Granularity
Control time-based aggregation:
{
"parameters": ["summary_metrics"],
"startDate": "2024-01-01",
"endDate": "2024-01-07",
"granularity": "hourly"
}Pagination
Use page and limit for large result sets:
{
"parameters": ["top_pages"],
"startDate": "2024-01-01",
"endDate": "2024-01-31",
"limit": 50,
"page": 2
}Page numbering starts at 1.
Continue with this workflow
For questions about step completion, review the conversion funnel measurement guide before comparing counts. If you want an assistant to help investigate the results, see the AI-assisted analytics comparison.
How is this guide?