Get Visitors by Country
get_countriesRead-only
Retrieve visitor counts grouped by country for a specified date range, sorted by visitors descending. Supports optional filters and pagination.
Instructions
Get visitors grouped by country, ranked by visitors descending, for a date range. Coarsest of the three geographic tools: use get_regions for states or provinces and get_cities for cities, and add filter_country to either to drill into one country. Use get_realtime_map for where visitors are right now instead of over a range. Rows carry value, visitors, revenue, and percentage with pagination.total; limit defaults to 100 (max 1000). Dates default to the last 30 days; all filter_* arguments apply. Requires websiteId or domain with a workspace token.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| endAt | No | ISO 8601 end of the reporting window (e.g. "2026-01-31"). Defaults to now. | |
| limit | No | Max rows to return (1-1000, default 100). | |
| domain | No | Website domain from list_websites (e.g. "example.com"). Alternative to websiteId with a workspace token. | |
| offset | No | Rows to skip for pagination (default 0). Compare offset + limit against pagination.total in the response. | |
| startAt | No | ISO 8601 start of the reporting window, date or datetime (e.g. "2026-01-01" or "2026-01-01T00:00:00Z"). Defaults to 30 days ago. | |
| timezone | No | IANA timezone used to bound and bucket the window (e.g. "America/New_York"). Defaults to the website timezone from get_metadata. | |
| filter_os | No | Filter by operating system name as returned by get_operating_systems (e.g. "iOS") | |
| websiteId | No | Website ID from list_websites. Required with a workspace token unless domain is given; ignored with a website key. | |
| filter_ref | No | Filter by ref URL parameter | |
| filter_via | No | Filter by via URL parameter | |
| filter_city | No | Filter by city name as returned by get_cities | |
| filter_goal | No | Filter to visitors who completed this goal name (as returned by get_goals) | |
| filter_page | No | Filter by page path as returned by get_pages (e.g. "/pricing") | |
| filter_device | No | Filter by device type: desktop, mobile, tablet | |
| filter_region | No | Filter by region code as returned by get_regions (e.g. US-CA) | |
| filter_source | No | Filter by source URL parameter | |
| filter_browser | No | Filter by browser name as returned by get_browsers (e.g. "Chrome") | |
| filter_channel | No | Filter by marketing channel as returned by get_channels (e.g. "Organic Search") | |
| filter_country | No | Filter by country name as returned by get_countries (e.g. "United States"). Every filter_* value accepts the same operators: "v" is, "!v" is not, "~v" contains, "!~v" does not contain, "a|b" any of. Filters combine with AND. | |
| filter_hostname | No | Filter by hostname as returned by get_hostnames (e.g. "app.example.com") | |
| filter_referrer | No | Filter by referrer domain as returned by get_referrers (e.g. "google.com") | |
| filter_utm_term | No | Filter by UTM term | |
| filter_entry_page | No | Filter by entry/landing page | |
| filter_utm_medium | No | Filter by UTM medium | |
| filter_utm_source | No | Filter by UTM source | |
| filter_utm_content | No | Filter by UTM content | |
| filter_utm_campaign | No | Filter by UTM campaign |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | No | Object with status, data (country rows with value, visitors, revenue, percentage, ordered by visitors descending), and pagination {limit, offset, total}. |