traffic.timeseries
Track website metrics over time with hourly, daily, weekly, or monthly buckets. Choose from pageviews, visitors, sessions, bounce rate, or custom events.
Instructions
Traffic metrics over time as date buckets. Returns [{ date, count }] sorted ascending, where count is the chosen metric's value per bucket. By default charts pageview counts; set metric to chart unique visitors, sessions, bounce rate, or average session duration instead — the same KPIs as traffic.overview, broken out over time. Alternatively set event to count occurrences of a custom event. Granularity is automatic based on period length (hourly for ≤2 days, daily for ≤90 days, weekly for ≤365 days, monthly beyond) and can be overridden via granularity.
Examples:
"pageview trend last week" → period="7d"
"unique visitors per day this month" → metric="visitors", period="30d"
"is bounce rate climbing?" → metric="bounce_rate", period="90d"
"signups per day this month" → event="signup", period="30d", granularity="day"
"hourly pageviews yesterday" → period="1d", granularity="hour"
Limitations: metric and event are mutually exclusive — when metric is set it always scopes to pageviews and ignores event/property/value. bounce_rate is a percentage (e.g. 47.2), avg_duration is in seconds. Forcing granularity="hour" over a 90-day period produces hundreds of buckets and may be truncated server-side. Buckets with no matching events return zero (the series does not skip missing dates).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. | |
| period | No | Time period. Use "today", "yesterday", "7d", "30d", "90d", or a custom range as "YYYY-MM-DD:YYYY-MM-DD" (e.g. "2026-01-01:2026-03-31"). Defaults to "30d". | |
| metric | No | Which traffic metric to chart over time, mirroring the overview KPIs: "pageviews", "visitors" (unique), "sessions", "bounce_rate" (% of single-pageview sessions), or "avg_duration" (avg session length in seconds). When set, the metric is always scoped to pageviews and `event`/`property`/`value` are ignored. Omit to chart raw counts of a custom `event` instead. | |
| event | No | Event name to chart raw counts of (defaults to "pageview"). Ignored when `metric` is set. Use any custom event name to see its trend over time. | |
| granularity | No | Override the automatic granularity. "hour" for hourly buckets, "day" for daily, "week" for weekly, "month" for monthly. If omitted, chosen automatically based on the period length. | |
| property | No | Filter by this custom property key (used with value). | |
| value | No | Filter to events where the property key equals this value. | |
| pathname | No | Filter to a specific page path (e.g. "/pricing", "/blog/my-post"). Must start with /. | |
| utm_source | No | Filter by UTM source (e.g. "google", "twitter", "newsletter"). Case-sensitive, must match the value in the tracking URL. | |
| utm_medium | No | Filter by UTM medium (e.g. "cpc", "email", "social"). Case-sensitive. | |
| utm_campaign | No | Filter by UTM campaign name (e.g. "spring-launch", "product-hunt"). Case-sensitive. | |
| utm_content | No | Filter by UTM content (e.g. "hero-cta", "sidebar-banner"). Case-sensitive. | |
| utm_term | No | Filter by UTM term (e.g. "running+shoes"). Case-sensitive. | |
| referrer_host | No | Filter by referrer hostname (e.g. "news.ycombinator.com", "twitter.com", "github.com"). Use this to see what traffic from a specific source did. Must match the value returned by `traffic.breakdown(dimension="referrer_host")` exactly (lowercase, no protocol or path). | |
| country | No | ISO 3166-1 alpha-2 country code, uppercase (e.g. "US", "GB", "DE", "NL", "JP"). Filter results to visitors from this country. | |
| region | No | Administrative region inside a country (e.g. "California", "Bavaria"). Case-sensitive; must match the stored region exactly. Use traffic.breakdown(dimension="region") to discover values. | |
| city | No | City name (e.g. "San Francisco", "London"). Case-sensitive; must match the stored value. Use traffic.breakdown(dimension="city") to discover values. | |
| device_type | No | Device category. One of: "desktop", "mobile", "tablet". | |
| browser | No | Browser family (e.g. "Chrome", "Safari", "Firefox"). Use traffic.breakdown(dimension="browser") to discover the exact stored values. | |
| browser_version | No | Browser version string (e.g. "120.0"). Case-sensitive. | |
| os | No | Operating system family (e.g. "macOS", "iOS", "Windows", "Android"). Use traffic.breakdown(dimension="os") to discover stored values. | |
| os_version | No | OS version string (e.g. "14.2"). Case-sensitive. | |
| channel | No | Traffic channel. One of: "direct", "organic_search", "organic_social", "paid", "email", "referral". |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| series | Yes |