API · Analytics

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

Reading analytics and report-link metadata requires an account API token with Read or Read + Write permission. Creating or revoking a report link requires Read + Write. 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.

Expiring report links

Report links are unauthenticated, read-only views for partners, sponsors, artists, venues, agencies, or clients. They expose a compact analytics report, never customer or order details. The opaque public URL is a bearer secret: anyone with it can read the report until it expires or is revoked.

The selected date range is fixed, but values remain live. A later order or refund inside that range changes the next rendered report. Public reports use no-store, noindex, nofollow, noarchive, and no-referrer protections; recipients can still forward the link or save its PDF.

GET /admin/analytics_publications

Returns all currently active links for the token’s account, ordered by expiry. Expired and revoked links are omitted. A read token is sufficient.

curl \
  -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  https://app.usetix.io/admin/analytics_publications

Response:

{
  "analytics_publications": [
    {
      "id": 42,
      "period": {
        "preset": "30",
        "start_on": "2026-08-01",
        "end_on": "2026-08-30"
      },
      "event": { "title": "Spring Showcase", "slug": "spring-showcase" },
      "branded": true,
      "expires_at": "2026-09-06T12:34:56Z",
      "created_at": "2026-08-30T12:34:56Z",
      "public_url": "https://your-subdomain.usetix.io/reports/opaque-secret-token",
      "pdf_url": "https://your-subdomain.usetix.io/reports/opaque-secret-token.pdf"
    }
  ]
}

event is null for an all-events report.

POST /admin/analytics_publications

Creates one link. Send fields directly at the JSON top level with a write token:

curl -X POST \
  -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "period": "custom",
    "start_on": "2026-07-01",
    "end_on": "2026-07-31",
    "event_slug": "spring-showcase",
    "expires_in_days": 7,
    "branded": false
  }' \
  https://app.usetix.io/admin/analytics_publications

Field	Description
period	today, 7, 30, 90, or custom. Defaults to 30.
start_on, end_on	YYYY-MM-DD; used for custom. Ranges follow the same normalization and 400-day cap as the main report.
event_slug	Optional event slug. Omit it for all events.
expires_in_days	7, 30, or 90. Defaults to 30; another value returns 422.
branded	Boolean. Defaults to true.

Success returns 201 Created, the publication object shown above, and a Location header pointing to its authenticated Admin API resource. Validation errors return 422 with the standard errors object.

GET /admin/analytics_publications/:id

Returns one link belonging to the token’s account in the same shape as the create response. Cross-account and unknown IDs return 404.

DELETE /admin/analytics_publications/:id

Revokes a link immediately and returns 204 No Content. This requires a write token. Later requests to either public_url or pdf_url return 404; PDFs already downloaded by recipients cannot be recalled.

The organizer workflow and sharing checklist are in Share analytics reports.

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.