Skip to main content
Embedded Cube surfaces — dashboards, Analytics Chat, and the full app in Creator Mode — bucket time in a zone you control. You can set a default for the whole account, override it per embed with a URL parameter, or switch it at runtime from the host page. This matters most when your end users are not in your deployment’s zone: without it, “today” in an embedded dashboard means today in the deployment’s default time zone, not in your customer’s.
Available on Premium and above plans.
Embedded time zones require user time zones to be enabled for the account. See Time zones for the account-wide policy, what a zone changes, and the console-side behavior.

​
How the zone is resolved

The time zone of an embedded surface is resolved from the following sources, highest priority first:
  1. Runtime override — a cube:action:set-timezone message sent from the host page (see At runtime).
  2. URL parameter — the ?timezone= query parameter on the embed URL (see Per embed via URL).
  3. Session setting — settings.timezone on the Generate Session API, for a zone that belongs to the viewer rather than to one placement. Set it once when you mint the session and every iframe that session opens buckets time in it.
  4. Dashboard’s own zone — a dashboard pinned to a named zone, or set to resolve per viewer (see dashboard time zone). In signed embedding the viewer has no Cube account and therefore no personal zone, so a viewer-resolved dashboard falls through to the next step — supply settings.timezone or ?timezone= if you want each end user’s own zone.
  5. Account default — the zone configured in Embed → Settings (see Account-wide default).
  6. Account-wide zone, then the deployment’s default time zone.
A bare UTC offset (+05:00) or an unknown zone name falls through to the next source rather than failing. Cube cannot compute in such a zone — it would fall back to UTC and report nothing about it — so ignoring the value is safer than forwarding it. Everything the integrator supplies — the runtime message, the URL parameter, the session setting — outranks a dashboard’s pinned zone by design: you are speaking for the whole frame, and you know your user’s zone better than the dashboard’s author does.
If the account policy is disabled, none of this applies — Cube sends no zone and the deployment’s default time zone is used, exactly as before.

​
Account-wide default

Set a default time zone for all embedded surfaces:
  1. Go to Embed → Settings.
  2. In the Time Zone card, pick a zone from the dropdown.
The selected zone applies to every embedded surface across the account, unless something higher in the ladder above overrides it: a session’s own settings.timezone, a ?timezone= URL parameter, a runtime cube:action:set-timezone message, or a zone the dashboard’s author pinned. Re-selecting the account-wide zone clears the embed-specific value, so embeds follow the account-wide zone again. The picker is inert while user time zones are off for the account — a zone stored there would be one nothing applies.

​
Per embed via URL

Override the account default for an individual embed by adding the ?timezone= query parameter to the embed URL:
The parameter is read once when the embed loads and pinned for the session, so in-app navigation won’t drop it. Values must be IANA time zone names. An unusable value — including a bare UTC offset like +05:30 — is ignored, and the embed falls through to the next source in the ladder above (settings.timezone, then the dashboard’s own zone, then the account default) rather than quietly shifting every number.

​
At runtime

Switch the zone after the embed has loaded by sending a cube:action:set-timezone message from the host page. This takes precedence over every other source — the URL parameter, a session’s settings.timezone, a dashboard’s own pinned zone, and the account default — use it when your own user changes their zone:
See Events and actions for the full host ↔ embed messaging contract.