English EN Deutsch DE Português PT Français FR Español ES
Start for Free

API · Analytics

The analytics API exposes the same privacy-aware reports as the Analytics workspace: historical performance with period-over-period comparisons, plus Live View for current shop activity.

Both endpoints require an account API token with Read or Read + Write permission. See Authentication.

GET /admin/analytics

Returns the historical report for the requested period. Dates and day boundaries use the account’s configured time zone.

curl -G \
  -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  --data-urlencode "period=30" \
  https://app.usetix.io/admin/analytics

Query parameters:

Parameter Description
period today, 7, 30, 90, or custom. Defaults to 30.
start_on Start date as YYYY-MM-DD. Used when period=custom.
end_on End date as YYYY-MM-DD. Used when period=custom.
event_slug Optional event slug. When present, the entire report is limited to that event.

Custom ranges are normalized to valid dates, cannot extend beyond today, and are limited to 400 days. A reversed range is reordered automatically.

Response (daily arrays shortened to two dates):

{
  "data": {
    "period": {
      "preset": "30",
      "start_on": "2026-07-09",
      "end_on": "2026-08-07"
    },
    "event": null,
    "collection_enabled": true,
    "currency": "EUR",
    "measurement_basis": {
      "page_views": "all_anonymous_page_views",
      "sessions": "consented_sessions",
      "visitors": "consented_visitors",
      "returning_visitor_rate": {
        "numerator": "consented_visitors_seen_earlier_in_retained_history",
        "denominator": "consented_visitors_in_period"
      },
      "session_comparison": "complete_previous_period",
      "orders": "retaining_revenue_orders",
      "conversion_rate": {
        "numerator": "converting_consented_sessions",
        "denominator": "consented_sessions"
      }
    },
    "summary": {
      "page_views": { "value": 1250, "previous": 1100, "change": 13.6 },
      "sessions": { "value": 620, "previous": 580, "change": 6.9 },
      "visitors": { "value": 540, "previous": 510, "change": 5.9 },
      "returning_visitor_rate": { "value": 14.8, "previous": 13.1, "change": 13.0 },
      "conversion_rate": { "value": 5.6, "previous": 5.0, "change": 12.0 },
      "orders": { "value": 51, "previous": 43, "change": 18.6 },
      "revenue": {
        "value": { "value": "4200.00", "currency": "EUR" },
        "previous": { "value": "3550.00", "currency": "EUR" },
        "change": 18.3
      },
      "average_order_value": {
        "value": { "value": "82.35", "currency": "EUR" },
        "previous": { "value": "82.56", "currency": "EUR" },
        "change": -0.3
      }
    },
    "coverage": {
      "page_views": 76.4,
      "tracked_page_views": 955,
      "total_page_views": 1250,
      "orders": 68.6,
      "tracked_orders": 35,
      "total_orders": 51,
      "session_comparison_available": true
    },
    "funnel": [
      { "key": "sessions", "count": 620, "rate": null, "start": true },
      { "key": "event_views", "count": 510, "rate": 82.3, "start": false },
      { "key": "checkouts", "count": 94, "rate": 18.4, "start": false },
      { "key": "orders", "count": 35, "rate": 37.2, "start": false }
    ],
    "trend": {
      "labels": ["Aug 6", "Aug 7"],
      "currencySymbol": "€",
      "metrics": {
        "page_views": {
          "label": "Page views",
          "format": "number",
          "values": [72, 91],
          "previous": [68, 80],
          "previousLabel": "Previous period"
        },
        "sessions": {
          "label": "Sessions",
          "format": "number",
          "values": [38, 42],
          "previous": [35, 39],
          "previousLabel": "Previous period"
        },
        "orders": {
          "label": "Orders",
          "format": "number",
          "values": [2, 3],
          "previous": [2, 2],
          "previousLabel": "Previous period"
        },
        "revenue": {
          "label": "Revenue",
          "format": "currency",
          "values": [180.0, 240.0],
          "previous": [160.0, 170.0],
          "previousLabel": "Previous period"
        }
      }
    },
    "daily_series": {
      "dates": ["2026-08-06", "2026-08-07"],
      "metrics": {
        "revenue": [180.0, 240.0],
        "orders": [2, 3],
        "conversion_rate": [5.3, 7.1],
        "returning_visitor_rate": [12.5, 15.0],
        "page_views": [72, 91],
        "sessions": [38, 42],
        "visitors": [34, 37],
        "average_order_value": [90.0, 80.0]
      }
    },
    "sources": [
      {
        "source": "newsletter",
        "medium": "email",
        "campaign": "summer-sale",
        "page_views": 420,
        "sessions": 210,
        "orders": 19,
        "revenue": { "value": "1580.00", "currency": "EUR" },
        "conversion_rate": 6.7
      }
    ],
    "devices": [
      {
        "device_type": "mobile",
        "sessions": 390,
        "converting_sessions": 22,
        "conversion_rate": 5.6,
        "share": 62.9
      }
    ],
    "top_events": [
      {
        "page_views": 680,
        "sessions": 340,
        "orders": 31,
        "revenue": { "value": "2620.00", "currency": "EUR" },
        "event": { "title": "Spring Showcase", "slug": "spring-showcase" }
      }
    ]
  },
  "generated_at": "2026-08-07T12:34:56Z"
}

Summary and comparisons

Analytics money objects contain a decimal-string value and an ISO 4217 currency code. This deliberately preserves the report and Live View contract; most other API resources use amount instead. In summary metrics, the money object sits inside the metric’s own value or previous field.

Every summary metric contains:

Field Description
value Value for the requested period. Revenue and average order value use an analytics money object: { "value": "...", "currency": "..." }.
previous Value for the immediately preceding period of the same length.
change Percentage change from previous, rounded to one decimal. null when the previous value is zero.

The eight summary metrics are page_views, sessions, visitors, returning_visitor_rate, conversion_rate, orders, revenue, and average_order_value.

Session data is retained for 400 days. For a long custom range whose equally long preceding period falls partly outside that history, sessions, visitors, returning_visitor_rate, and conversion_rate return null for previous and change; coverage.session_comparison_available is false; and measurement_basis.session_comparison is unavailable_outside_retained_history. Order, revenue, and page-view comparisons remain available.

Conversion funnel

Every funnel stage counts distinct consented sessions from one coherent cohort, so later stages cannot exceed earlier ones:

Key Meaning
sessions Consented sessions that started in the requested period.
event_views Cohort sessions that visited an event. A later checkout or conversion also satisfies this stage.
checkouts Cohort sessions that started checkout. A conversion also satisfies this stage.
orders Cohort sessions that converted. Despite the legacy key name, this is converting sessions, not the authoritative order total from summary.orders.

Each non-starting stage’s rate is its percentage of the preceding stage. The summary conversion rate is converting sessions divided by all consented sessions in the cohort.

Daily series and chart data

daily_series.dates aligns by array index with all eight arrays in daily_series.metrics. Revenue and average-order-value entries are decimal numbers in the response’s currency; percentage series are percentages from 0 to 100.

The response also contains trend, the chart-ready current/previous-period data used by the admin’s main performance chart. Its metrics are page_views, sessions, orders, and revenue; labels, metric label, and previousLabel follow the account locale. Use daily_series when you need unlocalized ISO dates and all eight KPIs.

Breakdowns

Field Contents
sources Up to 25 source rows: source, medium, campaign, page_views, sessions, orders, conversion_rate, and revenue. Consented visits and their linked orders use the visit’s first known touch, including Direct; only orders without a consented visit use checkout attribution. orders is the authoritative order count for that source, while conversion_rate uses converting consented sessions divided by consented sessions.
devices Consented-session rows for desktop, mobile, tablet, or unknown: sessions, converting_sessions, conversion_rate, and percentage share.
top_events Up to 8 events, ranked by performance. Each row contains event (title and slug), page_views, sessions, orders, and revenue. Empty for an event-scoped report.

GET /admin/analytics/live

Returns Live View: activity during the last five minutes, today’s totals, coarse locations, and the latest orders. Pass event_slug to limit the report to one event.

curl -G \
  -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  --data-urlencode "event_slug=spring-showcase" \
  https://app.usetix.io/admin/analytics/live

Response:

{
  "data": {
    "generated_at": "2026-08-07T12:34:56Z",
    "active_window_seconds": 300,
    "event": { "title": "Spring Showcase", "slug": "spring-showcase" },
    "collection_enabled": true,
    "currency": "EUR",
    "measurement_basis": {
      "active_sessions": "consented_sessions_active_within_five_minutes",
      "checking_out": "consented_sessions_that_started_checkout_within_five_minutes",
      "locations": "rounded_cloudflare_ip_geolocation_for_consented_sessions",
      "orders": "all_retaining_revenue_orders",
      "order_locations": "orders_linked_to_located_consented_sessions"
    },
    "summary": {
      "active_sessions": 18,
      "located_active_sessions": 13,
      "sessions_today": 420,
      "checking_out": 4,
      "orders_today": 31,
      "revenue_today": { "value": "2480.00", "currency": "EUR" }
    },
    "active_locations": [
      {
        "latitude": 52.5,
        "longitude": 13.4,
        "label": "Berlin",
        "sessions": 7,
        "last_seen_at": "2026-08-07T12:34:30Z"
      }
    ],
    "order_locations": [
      {
        "latitude": 52.5,
        "longitude": 13.4,
        "label": "Berlin",
        "orders": 5,
        "last_order_at": "2026-08-07T12:32:10Z"
      }
    ],
    "recent_orders": [
      {
        "public_id": "abcd1234efgh5678",
        "order_code": "7K3Q9D2A",
        "occurred_at": "2026-08-07T12:32:10Z",
        "location": "Berlin",
        "events": ["Spring Showcase"],
        "amount": { "value": "84.00", "currency": "EUR" }
      }
    ]
  }
}

active_locations only includes consented sessions with usable location data. located_active_sessions can therefore be lower than active_sessions. recent_orders contains at most 8 orders from today; location can be null, and events can contain more than one title when an order spans events.

summary.checking_out counts distinct currently active consented sessions whose most recent checkout start happened during the five-minute Live View window. The historical funnel keeps the first checkout milestone, while Live View uses the most recent one so a repeated checkout attempt appears immediately.

Measurement and privacy boundaries

The measurement_basis object is part of the API contract. Keep these populations separate:

  • Page views include all anonymous page views while collection is enabled.
  • Sessions, visitors, devices, funnel steps, conversion rates, and Live View activity only use consented sessions.
  • Orders and retained revenue are authoritative business totals and do not require analytics consent.
  • Revenue is net of completed refunds. Event-scoped and top-event revenue allocate mixed-event orders and refunds to the applicable event rather than assigning the full order total to every event.
  • Coverage shows what share of page views and orders can be linked to a consented session. Do not calculate conversion by dividing all orders by consented sessions.
  • Live coordinates come only from consented sessions and are rounded to one decimal place before storage. Usetix does not store the visitor’s IP address in analytics records.

When collection_enabled is false, new analytics collection is paused. Historical analytics and authoritative order/revenue totals remain available.