Time Windows

Shape

type TimeWindow =
  | { period: Period; timezone: IANATimezone }
  | { start: ISO8601; end: ISO8601; timezone: IANATimezone }

type Period =
  | "today"
  | "this_week"        // Mon-Sun in the given timezone
  | "this_month"
  | "this_quarter"
  | "this_year"
  | "last_7_days"
  | "last_30_days"
  | "last_90_days"
  | "mtd"              // month-to-date
  | "qtd"              // quarter-to-date
  | "ytd"              // year-to-date

type IANATimezone = string  // e.g., "America/Chicago", "UTC"

Inclusivity

• start is inclusive, end is exclusive.
• Periods resolve to the same inclusivity at server time.
• Documented per-endpoint where the convention is broken (rare — aggregations whose source data is calendar-bucketed may have different boundaries).

Timezone — always required

No default. No "server time." IANA strings only — UTC-06:00 style offsets are rejected.

The timezone determines week-start, month boundaries, and business-hours interpretations. A "this_month" insight in America/Chicago returns a different result from the same insight in America/Los_Angeles over the same span of wall-clock time.

Query-string encoding

GET /v2/partner/insights/objective-completion-rate?period=this_month&timezone=America/Chicago

GET /v2/partner/insights/added-value?start=2026-01-01&end=2026-04-01&timezone=America/Chicago

Errors

Code	HTTP	Meaning
invalid_timezone	400	Not a valid IANA identifier
invalid_period	400	Period not in the enum
invalid_window	400	end is before or equal to start
window_too_large	400	Endpoint-specific max window exceeded