How to query tenant metrics

Retrieve activity metrics for a date range and choose the right aggregation level

Before you start

The metrics endpoint returns aggregated session and event data for your tenant. Use it to build dashboards, generate reports, or compare activity across time periods.

A valid access token (see How to authenticate)
Your tenant_slug, the tenant DNS slug used in the API host and path (for example, demo-retail)
Required scope: read:metrics

Fetch metrics for a date range

Request activity data by specifying a time window and aggregation bucket size:

curl 'https://api.YOUR_TENANT_SLUG.urbanfox.io/v2/YOUR_TENANT_SLUG/metrics?start_date=2024-01-01T00:00:00Z&end_date=2024-01-02T00:00:00Z&aggregation=hour' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response:

{
  "data": {
    "metrics": [
      {
        "timestamp": "2024-01-01T00:00:00Z",
        "total_events": 1250,
        "unique_sessions": 1200,
        "guest_sessions": 450,
        "non_guest_sessions": 800,
        "session_starts": 1150,
        "unique_ids": 980
      }
    ]
  }
}

Choose an aggregation level

The aggregation parameter controls the time bucket size for the returned series. Pick the level that matches your reporting needs:

Aggregation	Use when	Range limit
`minute`	Real-time dashboards, investigating a spike	Max 7 days
`hour`	Daily reports, comparing day-over-day	Max 90 days
`day`	Weekly/monthly trends	No limit
`week`	Multi-week comparisons	No limit
`month`	Monthly executive summaries	No limit
`quarter`	Quarterly business reviews	No limit
`year`	Year-over-year analysis	No limit

Omit the parameter to receive non-aggregated metric data points.

Filter to a single metric

Use the metric query parameter to return only one field per data point instead of all fields:

curl 'https://api.YOUR_TENANT_SLUG.urbanfox.io/v2/YOUR_TENANT_SLUG/metrics?start_date=2024-01-01T00:00:00Z&end_date=2024-01-02T00:00:00Z&aggregation=hour&metric=total_events' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Use total_events for traffic volume. Use unique_sessions when you need session counts instead of event counts. See the API reference for the full metric field list.

Compare two periods

To compare activity across periods, request the same metric with the same aggregation for each time window. For example, fetch hourly total_events for two consecutive days:

curl 'https://api.YOUR_TENANT_SLUG.urbanfox.io/v2/YOUR_TENANT_SLUG/metrics?start_date=2024-01-02T00:00:00Z&end_date=2024-01-03T00:00:00Z&aggregation=hour&metric=total_events' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

curl 'https://api.YOUR_TENANT_SLUG.urbanfox.io/v2/YOUR_TENANT_SLUG/metrics?start_date=2024-01-01T00:00:00Z&end_date=2024-01-02T00:00:00Z&aggregation=hour&metric=total_events' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Compare the returned metrics arrays in your reporting tool or integration.

If it's not working

Symptom	Action
`401` response	Token expired; request a fresh one
`403` response	Confirm your token has `read:metrics` scope
`400` with validation error	Check date format is ISO 8601 (for example, `2024-01-01T00:00:00Z`)
`400` end_date must be after start_date	Swap your start/end values
Empty `metrics` array	No data recorded in that time range; try a wider window