Skip to main content
Glama
arttus

umami-mcp-server

by arttus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Get pageview time series

umami_get_pageviews_series
Read-onlyIdempotent

Retrieve pageviews and sessions bucketed over time to analyze traffic trends, spikes, and seasonal patterns. Choose custom date ranges, units, and filters for targeted insights.

Instructions

Get pageviews and sessions bucketed over time, for trend and seasonality questions.

Use this when the question is about shape over time rather than a single total: which day spiked, whether traffic is trending up, what the weekday pattern looks like.

Args:

  • website (string, optional): Website ID, name, or domain.

  • range (string): Date range, default '7d'.

  • start_date / end_date (string, optional): Explicit bounds, overriding 'range'.

  • unit ('minute' | 'hour' | 'day' | 'month' | 'year', optional): Bucket size. Chosen automatically if omitted. Umami caps minute at 60 minutes, hour at 30 days, day at 6 months.

  • filters (object, optional): Segment filters.

  • timezone (string, optional): IANA timezone for bucket boundaries.

  • response_format ('markdown' | 'json'): Output format (default: 'markdown').

Returns: JSON shape: { "website_id": string, "unit": string, "points": [ { "timestamp": string, "pageviews": number, "sessions": number } ], "totals": { "pageviews": number, "sessions": number }, "peak": { "timestamp": string, "pageviews": number } }

Examples:

  • "Show daily traffic for the last 30 days" -> range="30d", unit="day"

  • "What hour of the day is busiest?" -> range="24h", unit="hour"

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
unitNoBucket size for the series. Omit to pick automatically from the range. Umami caps: minute up to 60 minutes, hour up to 30 days, day up to 6 months.
rangeNoDate range for the query, default '7d'. Relative ("30m", "24h", "7d", "4w", "3mo", "1y"), named ("today", "yesterday", "this_week", "last_week", "this_month", "last_month", "this_year", "last_year", "mtd", "ytd", "all_time"), or an explicit ISO date via start_date/end_date.
filtersNoOptional segment filters. Supported keys: path, referrer, title, query, browser, os, device, country, region, city, language, hostname, tag, event, distinctId, utmSource, utmMedium, utmCampaign, utmContent, utmTerm, segment, cohort. Example: { country: 'US', device: 'mobile' }.
websiteNoWebsite ID (UUID), name, or domain. Optional if UMAMI_DEFAULT_WEBSITE is set. Use umami_list_websites to discover values.
end_dateNoExplicit end date (YYYY-MM-DD, ISO 8601 timestamp, or epoch ms). Overrides 'range'.
timezoneNoIANA timezone for bucketing and day boundaries, e.g. 'America/New_York'. Defaults to UMAMI_TIMEZONE.
start_dateNoExplicit start date (YYYY-MM-DD, ISO 8601 timestamp, or epoch ms). Overrides 'range'.
response_formatNoOutput format: 'markdown' for a readable summary, 'json' for raw structured data.markdown

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.0

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: bucket-size caps, automatic unit selection, start_date/end_date overriding range, timezone handling, and the exact JSON return shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded: the core purpose and when-to-use guidance come first, followed by concise Args, Returns, and Examples sections. Every section earns its place, and the examples are compact and directly illustrative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 8 parameters, no output schema, and nested filter objects, the description is remarkably complete. It documents the return shape, provides example mappings, covers optionality and defaults, and clarifies important edge behavior like bucket caps and date overrides. An agent has enough information to call this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds useful semantic value on top: it maps examples to parameter choices, explains that unit is chosen automatically when omitted, and documents the Umami caps for each unit. This goes beyond what the schema alone provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Get pageviews and sessions bucketed over time') and explicitly frames the purpose around trend and seasonality questions. It also distinguishes itself from single-total queries, which separates it from sibling tools like umami_get_stats.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: 'Use this when the question is about shape over time rather than a single total' and lists concrete question types. It does not explicitly name an alternative tool like umami_get_stats, but the contrast with 'a single total' makes the intended usage clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools