Analytics API

The Analytics API gives you aggregated data about your support workspace — conversation volume over time, total customer counts, and geographic distribution of visitors. All endpoints use your secret API key and accept optional date range filters.

Authentication

All Analytics endpoints require a secret API key with api_user scope. The workspace is resolved automatically from the key — no workspace ID in the path.

Authorization: Bearer ts_sk_live_xxxxxxxxxxxx

Endpoints

GET/v1/analytics/overview

Returns high-level totals for a given period: total conversations (as events), total customers, and the period boundaries.

Request

curl "https://api.tidysupport.com/v1/analytics/overview?from=2026-03-01&to=2026-03-13" \
  -H "Authorization: Bearer ts_sk_live_xxxxxxxxxxxx"

Response

{
  "totalEvents": 148,
  "totalCustomers": 92,
  "totalRevenue": 0,
  "periodStart": "2026-03-01T00:00:00.000Z",
  "periodEnd": "2026-03-13T00:00:00.000Z"
}

totalEventsinteger

Number of new conversations opened in the period

totalCustomersinteger

Number of new customers created in the period

totalRevenuenumber

Reserved for future revenue tracking. Always 0 today.

periodStartstring

ISO 8601 start of the queried period

periodEndstring

ISO 8601 end of the queried period

GET/v1/analytics/events/timeseries

Returns daily conversation counts, useful for plotting volume charts in your own dashboard.

Request

curl "https://api.tidysupport.com/v1/analytics/events/timeseries?from=2026-03-01&to=2026-03-13" \
  -H "Authorization: Bearer ts_sk_live_xxxxxxxxxxxx"

Response

[
  { "date": "2026-03-01", "count": 12 },
  { "date": "2026-03-02", "count": 9 },
  { "date": "2026-03-03", "count": 15 },
  { "date": "2026-03-04", "count": 7 }
]

datestring

Date in YYYY-MM-DD format

countinteger

Number of conversations opened on that date

GET/v1/analytics/top-countries

Returns the top countries by visitor session count, derived from widget visitor geolocation data. Up to 20 countries are returned, ordered by count descending.

Request

curl "https://api.tidysupport.com/v1/analytics/top-countries?from=2026-03-01&to=2026-03-13" \
  -H "Authorization: Bearer ts_sk_live_xxxxxxxxxxxx"

Response

[
  { "country": "United States", "count": 54 },
  { "country": "United Kingdom", "count": 23 },
  { "country": "Germany", "count": 11 },
  { "country": "France", "count": 8 }
]

countrystring

Full country name

countinteger

Number of widget visitor sessions from this country

Node.js SDK

Use the official server SDK to query analytics without writing raw HTTP calls.

import { init } from "@tidysupport/node";

const tidysupport = init("ts_sk_live_xxxxxxxxxxxx");

const range = { from: "2026-03-01", to: "2026-03-13" };

// Summary totals
const overview = await tidysupport.analytics.getOverview(range);
console.log(overview.totalCustomers, overview.totalEvents);

// Daily chart data
const timeseries = await tidysupport.analytics.getEventsTimeseries(range);

// Geo breakdown
const countries = await tidysupport.analytics.getTopCountries(range);