GET
/
aggregations
Get analytics aggregation
curl --request GET \
  --url https://api.usefathom.com/v1/aggregations \
  --header 'Authorization: Bearer <token>'
{
  "object": "list",
  "url": "<string>",
  "has_more": true,
  "data": [
    {
      "browser": "Chrome",
      "device_type": "Desktop",
      "pageviews": 30000
    }
  ]
}

Generate an aggregation. This is effectively an unbelievably flexible report that allows you to group on any fields you wish, and filter them at your leisure.

This API endpoint is only accurate on data from March 2021. Before then, we did not tie browser, country, pathname, etc. together, so we have no way to offer this advanced filtering on that data. If there’s demand for it, we will build a legacy endpoint that allows simple aggregations on historical data.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
entity
enum<string>
required

The entity you want to report on. Events are treated separately from pageviews. Supported values: pageview and event.

Available options:
pageview,
event
​
entity_id
string
required

The ID of the site that you want to aggregate pageviews on. Do not include this parameter when entity is set to "event".

Deprecation note: For backward compatability, we still support goal IDs in this field but we don't recommend using this field for that anymore. Use site_id and entity_name parameters instead.

​
site_id
string
required

The ID of the site the event belongs to.

​
entity_name
string
required

The name of the event you want to report on. Example: purchase.

​
aggregates
string
required

The SUM aggregates you wish to include, separated by a comma.

Supported values for pageview entities: visits, uniques, pageviews, avg_duration and bounce_rate. The difference between "visitors" and "uniques" is that visitors are unique site visits whilst uniques are unique page visits. So a single user can only have one "visit" to your site, but they can view 10 unique pages.

Supported values for event entities: conversions, unique_conversions and value. Note: Value will be returned in cents.

​
date_grouping
enum<string>
default:none

By default, we don't do any kind of date grouping, and we offer "total" aggregations. You can override this but you still have limits such as: When grouping daily, you cannot aggregate over 6 months of data.

Available options:
none,
hour,
day,
month,
year
​
field_grouping
string

The fields you want to group by. Supported values are hostname, pathname, referrer_hostname, referrer_pathname, referrer_source, browser, country_code, region, device_type, operating_system, utm_campaign, utm_content, utm_medium, utm_source, utm_term, keyword, q, ref and s.

You can group by multiple fields using a comma hostname,pathname.

​
sort_by
string

The field you want to sort by. Format is: field:asc|desc. You can use any field that you've asked for in the aggregations and field_grouping options. If using date_grouping, you can also use timestamp:asc or timestamp:desc here, which allows you to sort by date.

Example:

"pageviews:desc"

​
timezone
string
default:UTC

The timezone you want us to use in our queries. We store all data in UTC, and use that by default, but can support any timezone. The timezone you send should be a TZ database name.

​
date_from
string

Timestamp (e.g. 2022-04-01 15:31:00). This should match the timezone you specified.

​
date_to
string
default:now

Timestamp (e.g. 2022-04-01 15:31:00). This should match the timezone you specified.

​
limit
integer

A limit on the number of entries to return. For example, if your site had 10,000 unique pathnames, and you had "pathname" in field_grouping, you might get 10,000 rows back by default. You should limit this to prevent timeouts. We have no limits for early access but we'll soon be introducing pagination for this endpoint, and setting a maximum amount of rows that can be returned.

​
starting_after
string
​
filters
object

JSON payload. An array of objects. You can add as many filters as you like.

The filtering is hyper flexible and is best illustrated via some JSON payload examples to the right (or below if you're on a mobile).

We support the following operators: is, is not, is like and is not like.

Response

200 - application/json

Aggregation data

The response is of type object.