One Dollar Stats - API Reference

The OneDollarStats Stats API is a powerful, single-endpoint HTTP interface for querying real-time and historical analytics data.
Use the /api endpoint to send flexible POST requests—from simple summaries to complex multi-dimensional queries—and receive JSON responses with calculated metrics.

Authentication

To create an API key:

Log in to your OneDollarStats dashboard.
In the top-right corner, open your account settings.
Go to the API Keys section and click Create API Key.
Name your API Key, then save the key securely—it will be shown only once.
Confirm by clicking Continue.

Authenticate your requests by including the key in the x-api-key header.

Example `curl` request

Replace YOUR-KEY with your API key and site_id with your site’s domain as registered in your OneDollarStats account:

curl \
--request POST \
--header 'x-api-key: YOUR-KEY' \
--header 'Content-Type: application/json' \
--url 'https://onedollarstats.com/api' \
--data '{ "site_id": "onedollarstats.com", "metrics": ["visitors"], "date_range": "7d" }'

Request Structure

All queries are made via the /api endpoint, which accepts a JSON object with the following fields:

{
  "site_id": "onedollarstats.com",
  "metrics": ["visitors", "pageviews", "bounce_rate"],
  "date_range": "7d",
  "filters": [["is_not", "visit:country_name", [""]]],
  "dimensions": ["visit:country_name", "visit:city_name"]
}

site_id `Required`

Your site’s domain, exactly as configured in OneDollarStats.

date_range `Required`

Specifies the date or time range for the query.

Option	Description
`["2024-01-01", "2024-07-01"]`	Custom date range (ISO8601)
`["2024-01-01T12:00:00+02:00", "2024-01-01T15:59:59+02:00"]`	Custom date-time range (ISO8601)
`"day"`	Current day
`"7d"`	Last 7 days
`"30d"`	Last 30 days
`"6mo"`	Last 6 months
`"12mo"`	Last 12 months
`"year"`	Since the start of this year
`"all"`	All available data in OneDollarStats

metrics `Required`

Metrics are the numeric values returned by the query.

Metric	Type	Description	Requirements
`visitors`	`int`	Unique visitors
`visits`	`int`	Total visits or sessions
`pageviews`	`int`	Total pageviews
`views_per_visit`	`float`	Pageviews ÷ visits
`bounce_rate`	`float`	Percentage of single-page visits
`visit_duration`	`int`	Average visit duration (seconds)
`events`	`int`	Total events (pageviews + custom events)
`scroll_depth`	`int`	Average scroll depth per session	Requires `event:page`
`conversion_rate`	`float`	% of visitors completing a goal	Requires `event:goal`
`group_conversion_rate`	`float`	Conversion rate per dimension group	Requires `event:goal`
`average_revenue`	`Revenue` or `null`	Avg. revenue per conversion	Requires revenue goals
`total_revenue`	`Revenue` or `null`	Total revenue from conversions	Requires revenue goals
`time_on_page`	`int`	Average time on page (seconds)	Requires `event:page`

dimensions `Optional`

Default: []

A list of attributes to group data by. Dimensions are like SQL GROUP BY fields.

Event dimensions

Dimension	Example	Description
`event:goal`	Register	Custom goal name
`event:page`	/blog/remove-google-analytics	Page path (wildcards supported, e.g. `/blog*`)
`event:hostname`	example.com	Event hostname

IMPORTANT

You cannot mix session metrics (bounce_rate, views_per_visit, visit_duration) with event dimensions.

Visit dimensions

Dimension	Example	Description
`visit:entry_page`	/home	Entry (landing) page
`visit:exit_page`	/about	Exit page
`visit:source`	Twitter	Traffic source
`visit:channel`	Organic Search	Acquisition channel
`visit:utm_medium`	social	`utm_medium` parameter
`visit:device`	Desktop	Device type
`visit:browser`	Chrome	Browser name
`visit:country_name`	United States	Country name
`visit:city_name`	San Francisco	City name

Time dimensions

Group results by time:

Dimension	Example	Description
`time`	`2024-01-01`	Auto time bucket based on range
`time:hour`	`2024-01-01T14:00:00Z`	Hourly grouping
`time:day`	`2024-01-01`	Daily grouping
`time:week`	`2024-01-01`	Weekly grouping
`time:month`	`2024-01-01`	Monthly grouping

Notes:

Time dimensions can’t be used in filters (use date_range instead).
Missing time buckets return no values unless you enable include.time_labels.
Timestamps use your site’s reporting timezone.

filters `Optional`

Default: []

Filters restrict which events or sessions are included in the query.

Each filter is an array: [operator, dimension, clauses]
Optionally, a fourth argument {modifiers} can be included.

Supported operators

Operator	Example	Description
`is`	`["is", "visit:country_name", ["Germany"]]`	Match values exactly
`is_not`	`["is_not", "event:page", ["/pricing"]]`	Exclude values
`contains`	`["contains", "event:page", ["/login"]]`	Match substrings
`matches`	`["matches", "event:page", ["^/user/\\d+$"]]`	Regex match (RE2 syntax)

Combine filters using logical operators:

Operator	Example	Description
`and`	`["and", [["is", "visit:country_name", ["Germany"]], ["is", "visit:city_name", ["Berlin"]]]]`	Both must match
`or`	`["or", [["is", "visit:country_name", ["Germany"]], ["is", "visit:city_name", ["Tallinn"]]]]`	Either matches
`not`	`["not", ["is", "visit:country_name", ["Germany"]]]`	Negation

Top-level filters are implicitly wrapped in and.

Behavioral filters

Use has_done or has_not_done to filter sessions based on whether specific events occurred within them.
See example

order_by `Optional`

Defines the sort order of results.

Example:

[
  ["visitors", "desc"],
  ["visit:country_name", "asc"]
]

Default order:

By time dimension (ascending), if present
By the first metric (descending)

include `Optional`

Adds optional metadata or computed data to the response.

Option	Default	Description
`include.imports`	`false`	Include imported analytics data (e.g. from Google Analytics)
`include.time_labels`	`false`	Add all valid time labels for `date_range`
`include.total_rows`	`false`	Include total row count (useful for pagination)

pagination `Optional`

Default: { "limit": 10000, "offset": 0 }

Use with include.total_rows for paginated results.

Response Structure

Example:

{
  "results": [
    { "metrics": [99, 98, 94], "dimensions": ["Estonia", "Tallinn"] },
    { "metrics": [98, 82, 97], "dimensions": ["Brazil", "São Paulo"] },
    { "metrics": [97, 77, 98], "dimensions": ["Germany", "Berlin"] },
    { "metrics": [94, 86, 93], "dimensions": ["Italy", "Rome"] },
    {
      "metrics": [89, 77, 96],
      "dimensions": ["United States", "San Francisco"]
    },
    { "metrics": [82, 78, 92], "dimensions": ["Poland", "Warsaw"] }
  ],
  "meta": {},
  "query": {
    "site_id": "dummy.site",
    "metrics": ["visitors", "pageviews", "bounce_rate"],
    "date_range": ["2024-09-04T00:00:00+00:00", "2024-09-10T23:59:59+00:00"],
    "filters": [["is_not", "visit:country_name", [""]]],
    "dimensions": ["visit:country_name", "visit:city_name"],
    "order_by": [["visitors", "desc"]],
    "include": {}
  }
}

results

Array of result rows.
Each row contains:

dimensions: values for each requested dimension
metrics: values for each requested metric

Examples

All examples below are live and editable when logged in.

Simple aggregate

Query

Example Response

{
  "site_id": "dummy.site",
  "metrics": ["visitors", "events"],
  "date_range": "7d"
}

{
  "results": [{"metrics": [944, 1797], "dimensions": []}],
  "meta": {},
  "query": {
    "site_id": "dummy.site",
    "metrics": ["visitors", "events"],
    "date_range": ["2024-09-04T00:00:00+00:00", "2024-09-10T23:59:59+00:00"],
    "filters": [],
    "dimensions": [],
    "order_by": [["visitors", "desc"]],
    "include": {}
  }
}

Custom date range

Query

Example Response

{
  "site_id": "dummy.site",
  "metrics": ["visitors"],
  "date_range": ["2024-08-01", "2024-08-15"]
}

{
  "results": [{"metrics": [1140], "dimensions": []}],
  "meta": {},
  "query": {
    "site_id": "dummy.site",
    "metrics": ["visitors"],
    "date_range": ["2024-08-01T00:00:00+00:00", "2024-08-15T23:59:59+00:00"],
    "filters": [],
    "dimensions": [],
    "order_by": [["visitors", "desc"]],
    "include": {}
  }
}

Country and city breakdown

Query

Example Response

{
"site_id": "dummy.site",
"metrics": ["visitors", "pageviews", "bounce_rate"],
"date_range": "7d",
"filters": [
["is_not", "visit:country_name", [""]]
],
"dimensions": ["visit:country_name", "visit:city_name"]
}

{
"results": [
{"metrics": [99, 98, 94], "dimensions": ["Estonia", "Tallinn"]},
{"metrics": [98, 82, 97], "dimensions": ["Brazil", "São Paulo"]},
{"metrics": [97, 77, 98], "dimensions": ["Germany", "Berlin"]},
{"metrics": [94, 86, 93], "dimensions": ["Italy", "Rome"]},
{"metrics": [89, 77, 96], "dimensions": ["United States", "San Francisco"]},
{"metrics": [82, 78, 92], "dimensions": ["Poland", "Warsaw"]}
],
"meta": {},
"query": {
"site_id": "dummy.site",
"metrics": ["visitors", "pageviews", "bounce_rate"],
"date_range": ["2024-09-04T00:00:00+00:00", "2024-09-10T23:59:59+00:00"],
"filters": [["is_not", "visit:country_name", [""]]],
"dimensions": ["visit:country_name", "visit:city_name"],
"order_by": [["visitors", "desc"]],
"include": {}
}
}

Filtering examples

Query

Example Response

{
  "site_id": "dummy.site",
  "metrics": ["visitors"],
  "date_range": "7d",
  "filters": [
    ["contains", "event:page", ["/docs", "/pricing"]],
    ["or", [
      ["not", ["is", "visit:utm_campaign", ["Referral"]]],
      ["is", "visit:country_name", ["Estonia", "United States of America"]]
    ]]
  ]
}

{
  "results": [{"metrics": [10], "dimensions": []}],
  "meta": {},
  "query": {
    "site_id": "dummy.site",
    "metrics": ["visitors"],
    "date_range": ["2024-09-04T00:00:00+00:00", "2024-09-10T23:59:59+00:00"],
    "filters": [
      ["contains", "event:page", ["/docs", "/pricing"]],
      [
        "or",
        [
          ["not", ["is", "visit:utm_campaign", ["Referral"]]],
          ["is", "visit:country_name", ["Estonia", "United States of America"]]
        ]
      ]
    ],
    "dimensions": [],
    "order_by": [["visitors", "desc"]],
    "include": {}
  }
}

Query

Example Response

{
  "site_id": "dummy.site",
  "metrics": ["visitors"],
  "date_range": "7d",
  "filters": [
    ["contains", "event:page", ["blog"], {"case_sensitive": false}]
  ]
}

{
  "results": [{"metrics": [10], "dimensions": []}],
  "meta": {},
  "query": {
    "site_id": "dummy.site",
    "metrics": ["visitors"],
    "date_range": ["2024-09-04T00:00:00+00:00", "2024-09-10T23:59:59+00:00"],
    "filters": [
      ["contains", "event:page", ["/blog"], {"case_sensitive": false}]
    ],
    "dimensions": [],
    "order_by": [["visitors", "desc"]],
    "include": {}
  }
}

Query

Example Response

{
  "site_id": "dummy.site",
  "metrics": ["visitors", "events"],
  "filters": [["is", "segment", [2]]],
  "date_range": "7d"
}

{
  "results": [{"metrics": [0, 0], "dimensions": []}],
  "meta": {},
  "query": {
    "site_id": "dummy.site",
    "metrics": ["visitors", "events"],
    "date_range": ["2025-02-27T00:00:00+00:00", "2025-03-05T23:59:59+00:00"],
    "filters": [
      ["has_not_done", ["is", "event:goal", ["Signup"]]],
      ["is", "visit:source", ["opensource.com"]]
    ],
    "dimensions": [],
    "order_by": [["visitors", "desc"]],
    "include": {},
    "pagination": {"offset": 0, "limit": 10000}
  }
}

Timeseries examples

Query

Example Response

{
  "site_id": "dummy.site",
  "metrics": ["visitors", "events"],
  "date_range": "7d",
  "filters": [
    ["is", "visit:os", ["GNU/Linux", "Mac"]]
  ],
  "dimensions": ["time:day"]
}

{
  "results": [
    {"metrics": [129, 144], "dimensions": ["2024-09-04"]},
    {"metrics": [65, 68], "dimensions": ["2024-09-05"]},
    {"metrics": [72, 78], "dimensions": ["2024-09-06"]},
    {"metrics": [94, 98], "dimensions": ["2024-09-07"]},
    {"metrics": [44, 49], "dimensions": ["2024-09-08"]},
    {"metrics": [14, 14], "dimensions": ["2024-09-09"]},
    {"metrics": [12, 12], "dimensions": ["2024-09-10"]}
  ],
  "meta": {},
  "query": {
    "site_id": "dummy.site",
    "metrics": ["visitors", "events"],
    "date_range": ["2024-09-04T00:00:00+00:00", "2024-09-10T23:59:59+00:00"],
    "filters": [["is", "visit:os", ["GNU/Linux", "Mac"]]],
    "dimensions": ["time:day"],
    "order_by": [["time:day", "asc"], ["visitors", "desc"]],
    "include": {}
  }
}

Query

Example Response

{
  "site_id": "dummy.site",
  "metrics": ["visitors"],
  "date_range": "day",
  "dimensions": ["time:hour"],
  "include": {
    "time_labels": true
  }
}

{
  "results": [
    {"metrics": [2], "dimensions": ["2024-09-10 01:00:00"]},
    {"metrics": [4], "dimensions": ["2024-09-10 02:00:00"]},
    {"metrics": [3], "dimensions": ["2024-09-10 08:00:00"]},
    {"metrics": [1], "dimensions": ["2024-09-10 12:00:00"]},
    {"metrics": [1], "dimensions": ["2024-09-10 13:00:00"]},
    {"metrics": [1], "dimensions": ["2024-09-10 23:00:00"]}
  ],
  "meta": {
    "time_labels": [
      "2024-09-10 00:00:00",
      "2024-09-10 01:00:00",
      "2024-09-10 02:00:00",
      "2024-09-10 03:00:00",
      "2024-09-10 04:00:00",
      "2024-09-10 05:00:00",
      "2024-09-10 06:00:00",
      "2024-09-10 07:00:00",
      "2024-09-10 08:00:00",
      "2024-09-10 09:00:00",
      "2024-09-10 10:00:00",
      "2024-09-10 11:00:00",
      "2024-09-10 12:00:00",
      "2024-09-10 13:00:00",
      "2024-09-10 14:00:00",
      "2024-09-10 15:00:00",
      "2024-09-10 16:00:00",
      "2024-09-10 17:00:00",
      "2024-09-10 18:00:00",
      "2024-09-10 19:00:00",
      "2024-09-10 20:00:00",
      "2024-09-10 21:00:00",
      "2024-09-10 22:00:00",
      "2024-09-10 23:00:00"
    ]
  },
  "query": {
    "site_id": "dummy.site",
    "metrics": ["visitors"],
    "date_range": ["2024-09-10T00:00:00+00:00", "2024-09-10T23:59:59+00:00"],
    "filters": [],
    "dimensions": ["time:hour"],
    "order_by": [["time:hour", "asc"], ["visitors", "desc"]],
    "include": {"time_labels": true}
  }
}

Custom properties

Query

Example Response

{
  "site_id": "dummy.site",
  "metrics": ["visitors"],
  "date_range": "7d",
  "dimensions": ["time:day", "event:props:is_customer"],
  "order_by": [["time:day", "asc"], ["event:props:is_customer", "desc"]]
}

{
  "results": [
    {"metrics": [162], "dimensions": ["2024-09-04", "true"]},
    {"metrics": [126], "dimensions": ["2024-09-04", "false"]},
    {"metrics": [74], "dimensions": ["2024-09-05", "true"]},
    {"metrics": [86], "dimensions": ["2024-09-05", "false"]},
    {"metrics": [116], "dimensions": ["2024-09-06", "true"]},
    {"metrics": [97], "dimensions": ["2024-09-06", "false"]},
    {"metrics": [176], "dimensions": ["2024-09-07", "true"]},
    {"metrics": [191], "dimensions": ["2024-09-07", "false"]},
    {"metrics": [161], "dimensions": ["2024-09-08", "true"]},
    {"metrics": [172], "dimensions": ["2024-09-08", "false"]},
    {"metrics": [38], "dimensions": ["2024-09-09", "true"]},
    {"metrics": [50], "dimensions": ["2024-09-09", "false"]},
    {"metrics": [129], "dimensions": ["2024-09-10", "true"]},
    {"metrics": [125], "dimensions": ["2024-09-10", "false"]}
  ],
  "meta": {},
  "query": {
    "site_id": "dummy.site",
    "metrics": ["visitors"],
    "date_range": ["2024-09-04T00:00:00+00:00", "2024-09-10T23:59:59+00:00"],
    "filters": [],
    "dimensions": ["time:day", "event:props:is_customer"],
    "order_by": [["time:day", "asc"], ["event:props:is_customer", "desc"]],
    "include": {}
  }
}

Pagination and imports

Query

Example Response

{
  "site_id": "dummy.site",
  "metrics": ["visitors", "events", "pageviews"],
  "date_range": "7d",
  "dimensions": ["visit:utm_medium", "visit:utm_source"],
  "include": { "total_rows": true },
  "pagination": { "limit": 3, "offset": 1 }
}

{
  "results": [
    {"metrics": [325, 397, 317], "dimensions": ["(not set)", "duckduckgo"]},
    {"metrics": [311, 369, 295], "dimensions": ["(not set)", "google"]},
    {"metrics": [296, 357, 292], "dimensions": ["social", "twitter"]}
  ],
  "meta": {"total_rows": 6},
  "query": {
    "site_id": "dummy.site",
    "metrics": ["visitors", "events", "pageviews"],
    "date_range": ["2024-09-10T00:00:00+00:00", "2024-09-16T23:59:59+00:00"],
    "filters": [],
    "dimensions": ["visit:utm_medium", "visit:utm_source"],
    "order_by": [["visitors", "desc"]],
    "include": {"total_rows": true},
    "pagination": {"offset": 1, "limit": 3}
  }
}

Query

Example Response

{
  "site_id": "dummy.site",
  "metrics": ["visitors"],
  "date_range": "all",
  "dimensions": ["visit:source"],
  "include": {
    "imports": true
  }
}

{
  "results": [
    {"metrics": [91349], "dimensions": ["Direct / None"]},
    {"metrics": [90901], "dimensions": ["Twitter"]},
    {"metrics": [90265], "dimensions": ["Facebook"]},
    {"metrics": [89511], "dimensions": ["Google"]},
    {"metrics": [89243], "dimensions": ["DuckDuckGo"]}
  ],
  "meta": {"imports_included": true},
  "query": {
    "site_id": "dummy.site",
    "metrics": ["visitors"],
    "date_range": ["2021-09-26T00:00:00+00:00", "2024-09-10T23:59:59+00:00"],
    "filters": [],
    "dimensions": ["visit:source"],
    "order_by": [["visitors", "desc"]],
    "include": {"imports": true}
  }
}

Authentication

Example curl request

Request Structure

site_id Required

date_range Required

metrics Required

dimensions Optional

Event dimensions

Visit dimensions

Time dimensions

filters Optional

Supported operators

Behavioral filters

order_by Optional

include Optional

pagination Optional

Response Structure

results

meta

Examples

Simple aggregate

Custom date range

Country and city breakdown

Filtering examples

Timeseries examples

Custom properties

Pagination and imports

Example `curl` request

site_id `Required`

date_range `Required`

metrics `Required`

dimensions `Optional`

filters `Optional`

order_by `Optional`

include `Optional`

pagination `Optional`