Historical metadata

Last updated:

When viewing visitor and account metadata in Pendo, you can see details related to the last event Pendo processed for a visitor. If you want to view historical data to better understand the context for how a visitor or account was using your app when a Feature, Page, Track Event, or guide event was recorded, you can enable historical metadata.

When you update your user metadata as historical metadata, this allows the data to also function as a global event property, which means you can see the metadata values at the time they were stored for each event. This provides a more accurate view of user activity and allows you to track changes in behavior over time, rather than only seeing the value recorded on the latest event.

Note: For mobile users, historical metadata is supported on versions 2.21.0 and above.

Understand historical metadata

Historical metadata allows you to capture the past values of up to 25 metadata fields, instead of just the current value associated with a visitor or account. This feature gives you the ability to track changes in metadata values over time.

We recommend being selective about which data mapping fields you enable historical metadata for. To best utilize this feature, focus on fields where the values change over time but don't change constantly. As a best practice, consider choosing fields that describe visitors or accounts at a high level, rather than fields that capture temporary or narrowly-scoped assignments, such as project or task IDs. We also recommend keeping track of which metadata fields you enable or disable and when.

To better understand the benefits of historical metadata, consider the overview video and example below.

Imagine you have a visitor in your product named Alice and a metadata field in your subscription related to Account Type with values of Free and Paid.

On Alice's first three visits to the application, she was using a Free plan and visited the "Account Page" on three separate occasions: January 1, January 4, and January 7. After January 7, Alice upgraded her account to a Paid plan and made two more visits to the Account Page in the month of January.


If the Account Type metadata field wasn't enabled as historical during Alice's activity, you would only be able to see the most recent value of her Account Type, which was Paid. All of Alice's previous activity would be associated with Paid as the metadata value since that was the most recently recorded value.

If the Account Type metadata field was enabled as historical during Alice's activity, you could view the unique metadata value for each event at the time it occurred. This means you could see exactly what Alice did in your product when she was on a Free plan and compare it to her activity when she was on a Paid plan.

Tip: When enabling historical metadata, it's important to balance your selection of fields with values that change over time and values that don't change too often. Aim to choose fields that provide high-level descriptions of visitors or accounts, rather than those that capture temporary or narrowly-scoped assignments, like project or task IDs.

Unsupported metadata

Historical metadata isn't supported for:

  • Default fields of Visitor ID and Sample Group.
  • Metadata with a list, date, time, or undefined data type.
  • Segment.com metadata.

In addition, Pendo only shows up to five value changes for non-agent metadata within a rolling 24-hour period. For example, consider that you're tracking a historical metadata value related to a visitor's environment. If a visitor accesses your application in multiple environments and switches between those environments throughout the day, Pendo stops tracking the metadata value historically after the visitor switches environments for the sixth time that day. Note that this limitation doesn't apply to agent metadata.

Enable historical metadata

If you're a Pendo Admin, you can enable historical metadata for up to 25 data mappings across all levels of data (visitor, account, parent account) and across all apps in your subscription to function as a global event property. If you need to enable historical metadata for more than 25 fields, contact your Pendo account representative or Pendo Support.

  1. Navigate to Settings > Data Mappings in Pendo.
  2. By default, you're taken to all visitor-level data. If you want to enable account-level data, select the Account Level Data tab.
  3. In the Metadata table, find the Enable Historical column and select the checkbox next to an event you'd like to enable to function as a global event property.


  4. Select Enable in the confirmation dialog.


  5. Repeat steps 3 and 4 for each metadata field you'd like to enable as historical, up to 25 fields across all levels of data.

After you enable historical metadata for a field, it applies to all future events going forward. You can't view historical metadata values for past events.

Note: You can only enable historical metadata for a specific field three times in a 24-hour period.

To disable historical metadata for a data mapping, deselect the checkbox and select Disable in the confirmation dialog. After disabling, the metadata still displays with event properties (such as in Data Explorer, the segment rule builder, and the Event Properties tables) so that you can track the values related to when that field was enabled as historical metadata.

Use historical metadata

When you enable historical metadata, the metadata field begins to function as an event property from that point onward, which allows you to:

  • Incorporate historical metadata in segment rules based on product usage.
    • If you choose to segment by the metadata listed under Visitor Data, segment eligibility is based on the most current metadata value.
    • If you choose to segment by product usage with a Page, Feature, or Track Event, add an event property, and select the metadata listed under Historical Metadata, segment eligibility is based on the time at which that product event was generated by a visitor.
  • Filter and group by historical metadata values in funnels and Data Explorer reports.

To learn more about how to view and report on historical metadata, refer to our article on Event properties or watch the following video. (The video uses the former name for this feature: promoted metadata, but the functionality hasn't changed.)

To track historical metadata for agent metadata, values must be set and updated through the agent. Values updated with the API for agent metadata won't be tracked as historical.

Note: When using historical metadata, the metadata must be included in the initialize function of your install script. If you have a multi-page app architecture or iFrames, consider verifying that your install script is configured to capture this data each time you initialize Pendo.

Was this article helpful?
3 out of 5 found this helpful