GAGA4 MCPv2.11.9

Agent skill

GA4 API Date Ranges: Syntax, Offsets & Comparisons

How to specify date ranges in the Google Analytics 4 Data API and structure period-over-period comparisons without triggering syntax or parsing errors.

Supported Date String Formats

The GA4 Data API accepts four formats for start and end dates:

Format StringDescriptionExample
YYYY-MM-DDExact calendar date"2026-10-15"
todayCurrent calendar day (partial data)"today"
yesterdayMost recent complete calendar day"yesterday"
NdaysAgoRelative offset from current day"7daysAgo", "30daysAgo", "90daysAgo"

⚠️ Common Syntax Errors: Strings like "last7days", "last-week", or "lastMonth" are invalid and will cause an API parse error. Always use NdaysAgo or exact ISO dates (YYYY-MM-DD).


Standard Comparison Windows

Analysis WindowRecommended Start DateRecommended End Date
Last 7 Complete Days"7daysAgo""yesterday"
Last 28 Complete Days"28daysAgo""yesterday"
Last 90 Complete Days"90daysAgo""yesterday"
Current Month to Date"YYYY-MM-01""today"
Full Prior MonthPrior month 1stPrior month last day
Year to Date (YTD)"YYYY-01-01""yesterday"

Structuring Period-Over-Period Comparisons

To compare two non-overlapping timeframes (e.g., week-over-week or month-over-month), execute two separate get_ga4_data calls:

Week-Over-Week Example

  • Current Week (Call 1): start_date="7daysAgo", end_date="yesterday"
  • Prior Week (Call 2): start_date="14daysAgo", end_date="8daysAgo"

Delta Calculation: ((current_value - prior_value) / prior_value) * 100

Beware of Day-of-Week Seasonality

Never compare an incomplete current week against a full prior week, and avoid comparing weekends to weekdays directly. Traffic on Mondays often differs substantially from Saturdays. Always compare identical day-of-week groupings.


The Intra-Day "Today" Rule

today contains partial-day data up to the current hour. Comparing today to yesterday directly will always show an artificial traffic drop because yesterday represents 24 hours of data while today covers only elapsed hours. For daily trend tracking, use "yesterday" as your end boundary.