Advanced History API

Advanced History API

Advanced History exposes a small browser API that lets another Home Assistant custom card open its entities in the Advanced History panel.

This is intended for card authors who want to add an optional Open in Advanced History action.

Choose the correct integration

There are two deliberately different ways to call the API:

Calling card	Supply	Advanced History restores
Statistics Graph Chart Card	config and optional period	Entities, hidden entities, compatible graph settings and the date range
Any other card	entities and optional period	Entity IDs and the date range only

Important

A card other than Statistics Graph Chart Card must not pass its card configuration or entity-row configuration. Configuration formats differ between cards and cannot be safely translated. Extract the Home Assistant entity IDs as plain strings instead.

Availability

The API is installed as:

window.advancedHistory

Check that openCard is available before showing or enabling an integration button:

const advancedHistoryAvailable =
  typeof window.advancedHistory?.openCard === "function";

The API is present when Advanced History is installed and its frontend module has loaded. If the Advanced History panel is restricted to administrators, a non-administrator may still see the browser API but cannot open the protected panel. A card that has access to hass can also check:

const panelAvailable = Boolean(this.hass?.panels?.["advanced-history"]);

Option A: Statistics Graph Chart Card

Statistics Graph Chart Card can pass its complete current configuration:

window.advancedHistory.openCard({
  config: this._config,
  period: {
    start: this._start,
    end: this._end,
    compare: this._compare,
  },
});

Advanced History imports:

• valid entities from config.entities;
• compatible chart settings;
• compatible Statistics Graph Chart Card entity settings, including attribute and state_map;
• the original card_header;
• the original chart_mode;
• enabled: false as the entity's initial hidden state;
• the optional displayed period.

Both entity strings and Statistics Graph Chart Card entity configuration objects are accepted:

entities:
  - sensor.outdoor_temperature
  - entity: sensor.indoor_temperature
    color: "#ff6251"
    enabled: false
  - entity: climate.lounge
    attribute: current_temperature
    name: Current
  - entity: climate.lounge
    attribute: temperature
    name: Target

An entity with enabled: false remains selected in Advanced History but starts hidden.

Multiple rows for the same entity are retained as that entity's selected attributes. Compatible per-row presentation settings are stored against the entity-and-attribute combination, and categorical state_map definitions are preserved. The normal entity state can be included alongside attributes by supplying a row without attribute.

Dashboard-only layout fields and properties managed by the panel itself are intentionally omitted, including type, grid_options, layout_options, view_layout, visibility and show_advanced_history_button.

Advanced History keeps a handed-off Statistics Graph Chart Card as a single graph when all imported rows use the same graph type, preserving its compatible presentation settings while adding the larger workspace, target controls, Energy date picker and comparisons. If the card mixes numeric and categorical rows, Advanced History separates them into Numeric history and State history graphs so each can use its correct chart mode and settings.

For a handed-off numeric graph, Advanced History preserves the compatible height setting from the originating card. height: auto uses the responsive panel layout, while an explicit numeric height remains a fixed override. State-timeline height is calculated automatically from the rows and labels it renders.

Complete Statistics Graph Chart Card helper

The following helper uses the card's full current configuration:

function openStatisticsCardInAdvancedHistory(card) {
  const api = window.advancedHistory;
  if (typeof api?.openCard !== "function") {
    return false;
  }

  return api.openCard({
    config: card._config,
    period: {
      start: card._start,
      end: card._end,
      compare: card._compare,
    },
  });
}

The property names holding the card's active start, end and comparison values depend on its implementation.

Open as a new panel

By default, openCard replaces the active Advanced History chart. Pass newPanel: true to preserve the current panel session and append the handed-off chart as a new active panel. panelName optionally supplies its tab label and is limited to 40 characters:

window.advancedHistory.openCard({
  config: this._config,
  period: {
    start: this._start,
    end: this._end,
    compare: this._compare,
  },
  newPanel: true,
  panelName: "Outdoor temperature",
});

These options work with either the config or entities integration path. New-panel handoff requires Statistics Graph Chart Card v4.02 or newer. On an older supported card version, Advanced History opens the handoff in the current panel instead. If Maximum tabs has already been reached, the receiving panel displays a notification and does not replace an existing chart.

Option B: Any other card

Every other card must call the API with entities, not config:

window.advancedHistory.openCard({
  entities: [
    "sensor.outdoor_temperature",
    "sensor.indoor_temperature",
  ],
  period: {
    start: this._start,
    end: this._end,
  },
});

Rules for other cards:

1. Extract entity IDs according to that card's own configuration format.
2. Pass the result as an array of plain entity ID strings.
3. Do not pass the card's _config object.
4. Do not pass its entity-row objects, colors, display settings or other options.
5. Pass period only when the card knows its currently displayed start and end.

Advanced History applies its configured numeric or state chart options, as appropriate, after receiving these entities.

Generic helper

Because every custom card stores entities differently, getDisplayedEntityIds() below represents logic supplied by that card's author:

function openOtherCardInAdvancedHistory(card) {
  const api = window.advancedHistory;
  if (typeof api?.openCard !== "function") {
    return false;
  }

  const entityIds = card.getDisplayedEntityIds();

  return api.openCard({
    entities: entityIds,
    period: {
      start: card._start,
      end: card._end,
    },
  });
}

If the card does not track a date range, omit period:

window.advancedHistory.openCard({
  entities: ["sensor.outdoor_temperature"],
});

Period format

period is optional for both integration paths:

{
  start: Date | string,
  end: Date | string,
  compare: string
}

• start is required when a period is supplied.
• end is optional.
• Dates may be JavaScript Date objects or values accepted by the Date constructor.
• compare is optional and may contain the active comparison value.

When period is omitted, Advanced History retains the current Energy date-picker selection.

Return value

openCard returns:

• true when the handoff was created and navigation started;
• false when the Statistics Graph Chart Card configuration or generic entity list was invalid, or the handoff could not be created.

The handoff is local to the current browser tab/session. It is transferred through sessionStorage, consumed once by Advanced History and is not sent to a third-party service.

Optional button

The following example uses the same icon as the Advanced History sidebar:

const ADVANCED_HISTORY_ICON = "mdi:chart-timeline-variant-shimmer";

A card author can conditionally render a button containing Home Assistant's icon component. This example shows the Statistics Graph Chart Card call; another card must replace the click handler with its entities call from Option B.

const apiAvailable =
  typeof window.advancedHistory?.openCard === "function" &&
  Boolean(this.hass?.panels?.["advanced-history"]);

return apiAvailable && this._config.show_advanced_history_button
  ? html`
      <button
        class="advanced-history-button"
        title="Open in Advanced History"
        aria-label="Open in Advanced History"
        @click=${() => {
          window.advancedHistory.openCard({
            config: this._config,
            period: {
              start: this._start,
              end: this._end,
              compare: this._compare,
            },
          });
        }}
      >
        <ha-icon icon="mdi:chart-timeline-variant-shimmer"></ha-icon>
      </button>
    `
  : nothing;

The card can style advanced-history-button to match its existing header actions. If it already has a standard helper for icon buttons, use that helper with:

<ha-icon icon="mdi:chart-timeline-variant-shimmer"></ha-icon>

Recommended behavior for card authors:

1. Make the button opt-in, for example with show_advanced_history_button: true.
2. Show it only when window.advancedHistory.openCard is available.
3. Use config only for Statistics Graph Chart Card; use plain entities for every other card.
4. Pass the currently displayed period when the card can determine it.
5. Keep the card usable when Advanced History is not installed.
6. Use the Boolean return value to detect a rejected handoff.