Count visitors
Read distinct anonymous visitor totals across a selected time period or lifetime.
Request
/api/v1/stats/visitorsCall this endpoint from your server with a website-scoped Stats API bearer key. Follow Get started to create a key. The key selects your website; do not send a website ID.
Query parameters
| Parameter | Accepted values |
|---|---|
days | 1, 7, 30, or 90. Defaults to 30. Use this or a pair of explicit dates. |
startDate | Inclusive UTC date in YYYY-MM-DD format. Requires endDate. |
endDate | Inclusive UTC date in YYYY-MM-DD format. Requires startDate. |
interval | hourly or daily. Defaults to hourly for days=1, otherwise daily. |
period | lifetime. Count all retained native traffic up to calculation time. Omit days, startDate, endDate, and interval. |
Explicit ranges cover up to 365 days through today. Hourly ranges cover at most seven days. Do not combine days with explicit dates. Unknown or repeated parameters return 400 INVALID_QUERY.
days=1 selects the rolling last 24 hours. Longer presets use UTC calendar days including today. Both explicit dates are inclusive: the example includes all of October 18 in UTC and excludes midnight on October 19. Counts use timestamps greater than or equal to period.start and less than period.endExclusive. The interval option changes period metadata, not the total; these endpoints do not return a time series. Use Get traffic for charts and dimension reports.
Response
A successful response contains data with the report and meta.generatedAt and meta.expiresAt with its cache timestamps. The report contains these fields:
period- The reporting interval, UTC boundaries, and calculation time.
metric- Always visitors.
count- Distinct non-null anonymous visitor identifiers on pageviews with a session identifier, deduplicated across the entire selected period.
previous- start, endExclusive, and count for the immediately preceding period of equal duration. Each period deduplicates independently. Null for lifetime.
All counts are non-negative JSON integers. An empty period returns zero for every count. Counts use native Talvess records and exclude imported provider history. Anonymous visitor identifiers represent observed traffic, not verified people; missing identifiers can make visitor and session totals lower than pageviews. Visitor totals deduplicate across the whole range, so adding daily visitor counts can overcount the period total. Session behavior counts use only pageviews inside each period.
Example response for the request above:
Use period=lifetime for all retained native traffic before period.asOf, including history older than 365 days. Do not combine it with days, explicit dates, or interval. The response sets period.range to lifetime and period.start to the first recorded pageview timestamp, or null when empty. period.endExclusive and period.seriesEnd equal the calculation time.period.interval and previous are null. Lifetime uses the same 900-second cache and counts distinct recorded visitor identifiers across the whole history, rather than summing daily visitor totals.
Matching reports are cached for 900 seconds. Each key allows 60 requests per minute, including cache hits. Read the shared freshness and limits and errors and retries before integrating. An empty report is a successful response; a failed calculation returns an error.