# Amplitude Documentation — Data # Generated: 2026-10-16T22:56:27Z # Pages included: 92 of 108 # Source: https://amplitude.com/docs/llms.txt # Product feed: llms-data.txt > Data planning, sources, destinations, governance, and CDP workflows. > Token budget (150,000 tokens) reached. Use Docs MCP or `/docs/api/content/` for pages not included here. > For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`. ================================================================================ # Data URL: https://amplitude.com/docs/data Updated: 2026-07-28 ================================================================================ # Data Send data into Amplitude, organize and clean it, and activate it across your downstream tools. Connect sources, resolve identities across devices, govern your taxonomy, and stream behavioral data to the rest of your stack. **Outcome:** [Get every event into Amplitude](https://amplitude.com/docs/data/source-catalog) Stream activity from SDKs, servers, warehouses, and pre-built sources so no behavior goes uncounted. **Outcome:** [Activate insights in your stack](https://amplitude.com/docs/data/destination-catalog) Send behavioral data and cohorts to the marketing, ad, and warehouse tools your team already uses. **Outcome:** [See one user, not many](https://amplitude.com/docs/data/profiles) Stitch warehouse profile data to behavioral events so each person is the same user across devices. **Outcome:** [Trust the data your team queries](https://amplitude.com/docs/data/create-tracking-plan) Lock in a tracking plan, review changes, and keep events on-spec as your product evolves. **Outcome:** [Fix data without redeploying](https://amplitude.com/docs/data/transformations) Rename, redact, or reshape events on the way in instead of waiting on an instrumentation fix. **Outcome:** [Add the context analysts need](https://amplitude.com/docs/data/lookup-tables) Join reference data like plans, regions, or accounts to events so every chart has the full picture. ## Plan and collect data Start with an implementation plan that defines the events, users, and properties your team needs. - [Plan your implementation](https://amplitude.com/docs/get-started/plan-your-implementation) to connect product questions to the events you track. - [Create a tracking plan](https://amplitude.com/docs/data/create-tracking-plan) to document event names, properties, and ownership. - [Choose client-side or server-side tracking](https://amplitude.com/docs/data/client-side-vs-server-side) to match your product architecture. - [Use Autocapture](https://amplitude.com/docs/data/autocapture) to collect website interactions before you manually instrument every event. ## Govern and activate data Keep your taxonomy healthy, then send trusted data to the teams and tools that need it. - [Configure schema](https://amplitude.com/docs/data/configure-schema) to monitor event volume, property types, and unexpected changes. - [Transform incoming events](https://amplitude.com/docs/data/transformations) to rename, redact, or reshape data after ingestion. - [Manage data access controls](https://amplitude.com/docs/data/data-access-control) to limit access to sensitive events and properties. - [Forward data to destinations](https://amplitude.com/docs/data/destination-catalog) to activate behavioral data in downstream tools. ### [Get Started with Amplitude Data](https://academy.amplitude.com/getting-started-with-amplitude-data) Learn the fundamentals of Amplitude Data. ================================================================================ # Overview of Amplitude Data URL: https://amplitude.com/docs/data/data-overview Updated: 2026-09-02 ================================================================================ # Overview of Amplitude Data Amplitude Data governs the event taxonomy behind your Amplitude project. It defines events and properties in a shared plan, validates incoming data against that plan, and provides tools to clean, enrich, and monitor data after ingestion. Use it when multiple teams instrument the same product and you need one source of truth for what every event means. ## Planning and instrumentation - Create a plan directly in Amplitude. Define your events, properties, and taxonomy standards directly in Amplitude. This information appears when you select events and properties. Amplitude Analytics monitors this information to make sure your incoming data matches your spec. - Use the Ampli developer toolkit. Ampli uses your plan to generate a type-safe tracking library and lints code to ensure proper tracking of your events and properties. Planning directly in Amplitude Data gives you an up-to-date plan your company can use instead of one-off spreadsheets or wiki pages that can quickly become outdated. Refer to the walkthrough of the [complete planning workflow](https://amplitude.com/docs/data/data-planning-workflow) for the process from start to finish. ## Data management For data Amplitude has ingested: - Improve data discoverability by enriching the metadata on your events and properties. Ensure your company has a shared definition and understanding of all your tracking. - Clean up your data with tools to transform existing events and properties, drop incorrect data from your queries, and block or delete data you no longer want to collect. - Enrich your data by using your existing events and properties to create new custom events, map existing properties to values with lookup properties, and generate new derived properties based on formulas. - Monitor your data with observability, which monitors your incoming data and compares it to your plan in real time. Amplitude also provides Data Assistant, which recommends and automates changes that improve your data quality. ================================================================================ # Getting started with Amplitude URL: https://amplitude.com/docs/data/data-get-started Updated: 2026-09-09 ================================================================================ # Getting started with Amplitude Send data to Amplitude with one of the SDKs or a third-party integration like Segment, mParticle, or Tealium, then instrument events, user properties, and group types so charts reflect real product usage. Set up at least two projects (one for staging, one for production) before you ship instrumentation, because Amplitude can't retroactively rename or change historical event data. Start here if you're standing up a new Amplitude project from scratch. If you already send data and need to model it for analysis, go to the [Data Planning Playbook](https://amplitude.com/docs/data/data-planning-playbook) instead. ## Instrumentation best practices Follow these recommended best practices when instrumenting Amplitude: - **Always test your instrumentation**: Amplitude recommends having a testing project for every production project in your organization. A testing project gives you a reliable way to test your instrumentation before sending production data to Amplitude. - **Amplitude can't retroactively change historical data**: If your instrumentation is wrong, you can't clean up the data you collect later. - **Set up at least two Amplitude projects**: One for your development or staging environment, and one for your production environment. Two projects keep testing data separate from production data. - **Send the right keys**: If you send data server-side with the HTTP API, send a `session_id` and `insert_id` with each event. ## How Amplitude receives data You can send data to Amplitude through SDKs or through a third party: - [SDK Catalog](https://amplitude.com/docs/sdks/analytics). - A third party like [Segment](https://segment.com/), [mParticle](https://www.mparticle.com/), or [Tealium](https://tealium.com/). ## Amplitude APIs Amplitude has many APIs you can use with the platform. Refer to all the [API references](https://amplitude.com/docs/apis). ## Amplitude schema The [Data Planning Playbook](https://amplitude.com/docs/data/data-planning-playbook) explains how the Amplitude schema fits together. Refer to it for a deeper look at taxonomy design. ### Naming conventions for events After you instrument an event, you can never change the name of that event type in the raw data. For example, in v1.0 of your app, a developer instruments the following event type: `Amplitude.getInstance().logEvent('Play song');` Later, in v2.0 of your app, a developer instruments this event type: `Amplitude.getInstance().logEvent('play song');` Strings passed to Amplitude are case-sensitive, so Amplitude interprets these two event types as separate events. Make sure your event names follow a consistent syntax during instrumentation. ### Instrument user properties [User properties](https://amplitude.com/docs/data/user-properties-and-events) are attributes specific to individual users. Examples of user properties include location, language, account type, money spent, or player type. For recommendations on which user properties to track, refer to [the Data Planning Playbook](https://amplitude.com/docs/data/data-planning-playbook#properties). Amplitude SDKs include several user property operations you can use to update user property values: - **`set`**: Set or overwrite the property value. - **`setOnce`**: Set the value only if the value isn't already set. - **`unset`**: Unset the value to `null`. - **`add`**: Increment the numerical value by a specified number. - **`append`**: Append the value to the property array. - **`prepend`**: Prepend the value to the property array. You can also use the [Identify API](https://amplitude.com/docs/apis/analytics/identify) to update the values of a user's user properties without sending another event. The new values apply to the next event the user sends organically. ### Instrument group types To use Amplitude's [account-level reporting](https://amplitude.com/docs/analytics/account-level-reporting) feature, instrument group types. Account-level reporting lets you count by a distinct user property group, which lets you process data at the groups level instead of the individual users level. Amplitude allows a maximum of five group types. If you use a third-party tool to instrument Amplitude (mParticle, Segment, Tealium), this maximum threshold might be lower based on the partner's limitations. ## How Amplitude tracks unique users and sessions Amplitude tracks unique users through a system of user IDs, device IDs, and Amplitude IDs. To learn more, refer to [tracking unique users](https://amplitude.com/docs/data/sources/instrument-track-unique-users). In Amplitude, a session is a single continuous period of time a user is active within your product. Amplitude sends a session ID with every event, which lets it track sessions. For more information, refer to [tracking sessions in Amplitude](https://amplitude.com/docs/data/sources/instrument-track-sessions). ## Popular SDK configuration options This section details Amplitude SDK configuration options that users commonly modify. - **`minTimeBetweenSessions` (iOS/Android)**: The minimum time you must background your app before a new session begins. - **`sessionTimeout` (Web)**: The minimum time between events that must elapse before a new session begins. - **`batchEvents`**: Enabled by default for mobile SDKs and optional for Web. - **`eventUploadPeriodMillis`**: If `batchEvents` is enabled, this option sets the time between event batch uploads. - **`eventUploadThreshold`**: If `batchEvents` is enabled, this option sets the minimum number of events per batch. - **`optOut`**: When enabled, opts the current user out of tracking. - **`offline`**: Prevents the sending of events. - **`saveEvents`**: Enabled by default for all SDKs. Lets the SDK save unsent events onto the device. - **`savedMaxCount`**: The maximum number of unsent events saved on a device. The default is 1000. ## Backfilling data Consider backfilling data if: 1. You want to analyze historic data in Amplitude. For detailed instructions on backfilling data into Amplitude, refer to the [Data Backfill Guide](https://amplitude.com/docs/data/data-backfill). 2. Your product already has existing users. You want to accurately reflect when these [users were new](https://amplitude.com/docs/analytics/charts/event-segmentation/event-segmentation-build) in Amplitude. ================================================================================ # Data Assistant user solutions URL: https://amplitude.com/docs/data/data-assistant-user-solutions Updated: 2026-09-22 ================================================================================ # Data Assistant user solutions Data Assistant reviews your taxonomy and fixes many issues for you. A few problems sit outside what it can do. It can't spot them, and it can't apply the fix. These guides cover those cases. They're written for people who want to solve a problem, not read about a product. Every guide starts with the part you can do yourself, without code. You confirm the problem is real and capture the exact facts. From there, the path splits. Some problems are yours to finish. Others come down to how your product sends data, so the fix belongs to an engineer. Each guide is clear about which situation you're in. When code is the answer, you get a short message you can copy and send to whoever owns your tracking, plus a path to follow if you have no engineering help at all. When another Amplitude product or a higher plan solves the problem more easily, the guide says so. Reach for these guides when you already suspect an issue, or when you run a scheduled data-quality review. For problems Data Assistant already surfaces, use [Data Assistant](https://amplitude.com/docs/data/use-ai-data-assistant) instead. > **Note:** Some solutions require engineering access > > You may need engineering resources as some of these solutions require changes to your backend code. Always start with confirming the problem. If you don't need engineering changes, the confirmation page also carries the no-code solution. If the solution does require code changes, move on to the engineering solution page. ## Choose a user solution | Use case | Confirm the problem | Code fix | | --- | --- | --- | | Missing User IDs after sign-in | [Confirm the problem](https://amplitude.com/docs/data/data-assistant-user-solutions/missing-user-ids-audit) | [Engineering solution](https://amplitude.com/docs/data/data-assistant-user-solutions/missing-user-ids-engineering) | | User IDs set too early | [Confirm the problem](https://amplitude.com/docs/data/data-assistant-user-solutions/early-user-ids-audit) | [Engineering solution](https://amplitude.com/docs/data/data-assistant-user-solutions/early-user-ids-engineering) | | Anonymous activity lost at login | [Confirm the problem](https://amplitude.com/docs/data/data-assistant-user-solutions/login-identity-merge-audit) | [Engineering solution](https://amplitude.com/docs/data/data-assistant-user-solutions/login-identity-merge-engineering) | | One person with many User IDs | [Confirm the problem](https://amplitude.com/docs/data/data-assistant-user-solutions/multiple-user-ids-audit) | [Engineering solution](https://amplitude.com/docs/data/data-assistant-user-solutions/multiple-user-ids-engineering) | | Profiles that don't join across devices | [Confirm the problem](https://amplitude.com/docs/data/data-assistant-user-solutions/cross-device-identity-audit) | [Engineering solution](https://amplitude.com/docs/data/data-assistant-user-solutions/cross-device-identity-engineering) | | Planned events that never arrived | [Confirm the problem](https://amplitude.com/docs/data/data-assistant-user-solutions/planned-unseen-events-audit) | [Remove the plan entry](https://amplitude.com/docs/data/data-assistant-user-solutions/planned-unseen-events-engineering) | | Failures you can't see | [Confirm the problem](https://amplitude.com/docs/data/data-assistant-user-solutions/error-event-coverage-audit) | [Engineering solution](https://amplitude.com/docs/data/data-assistant-user-solutions/error-event-coverage-engineering) | | No activation event | [Choose an activation event](https://amplitude.com/docs/data/data-assistant-user-solutions/activation-event-audit) | Often none. [Instrument it](https://amplitude.com/docs/data/data-assistant-user-solutions/activation-event-engineering) only if no event fits | | Missing or mistimed experiment exposure | [Confirm the problem](https://amplitude.com/docs/data/data-assistant-user-solutions/experiment-exposure-audit) | [Engineering solution](https://amplitude.com/docs/data/data-assistant-user-solutions/experiment-exposure-engineering) | | No account-level analysis | [Decide whether you need groups](https://amplitude.com/docs/data/data-assistant-user-solutions/group-types-audit) | Only if you need groups. [Set them up](https://amplitude.com/docs/data/data-assistant-user-solutions/group-types-engineering) | | Missing shared context | [Confirm the problem](https://amplitude.com/docs/data/data-assistant-user-solutions/shared-properties-audit) | [Engineering solution](https://amplitude.com/docs/data/data-assistant-user-solutions/shared-properties-engineering) | | Event vs user property confusion | [Confirm the problem](https://amplitude.com/docs/data/data-assistant-user-solutions/property-classification-audit) | [Engineering solution](https://amplitude.com/docs/data/data-assistant-user-solutions/property-classification-engineering) | | Missing `insert_id` or `session_id` | [Confirm the problem](https://amplitude.com/docs/data/data-assistant-user-solutions/event-identifiers-audit) | [Engineering solution](https://amplitude.com/docs/data/data-assistant-user-solutions/event-identifiers-engineering) | ================================================================================ # Missing User IDs after sign-in: confirm the problem URL: https://amplitude.com/docs/data/data-assistant-user-solutions/missing-user-ids-audit Updated: 2026-09-23 ================================================================================ # Missing User IDs after sign-in: confirm the problem After users sign in, their events should carry a stable `user_id`. Without a `user_id`, Amplitude relies on the device's existing identity history. Activity from a new or unlinked device remains anonymous until Amplitude receives the canonical User ID on that device. If Amplitude has already associated the device with a User ID, it may attribute an event without a User ID to the last known user on that device. Missing User IDs can delay or break cross-device analysis, retention, and funnels that follow a person after login. Amplitude doesn't report an error. The events still arrive, but they lack the identity needed to link a new device to the known person. Data Assistant reviews your taxonomy, not your identity setup, so it can't detect authenticated events that lack a `user_id`. You must perform this check manually. The fix requires an instrumentation change, but the audit provides evidence for the engineers who make that change. Run this audit when you suspect an identity gap or as a scheduled check on a signed-in flow. ## Prerequisites - A test account - Permission to open [User Profiles](https://amplitude.com/docs/analytics/user-data-lookup) ![Diagram comparing a signed-in event that carries a User ID and joins the known profile against an event from a new device that remains anonymous until the device sends a User ID](https://amplitude.com/docs/images/diagrams/missing-user-id.svg) ![Diagram comparing a signed-in event that carries a User ID and joins the known profile against an event from a new device that remains anonymous until the device sends a User ID](https://amplitude.com/docs/images/diagrams/missing-user-id.dark.svg) ## Check signed-in events for a User ID 1. Open your product in a private browser window or on a test device. 2. Complete at least one action before you sign in. 3. Sign in with the test account. 4. Complete several actions that represent the signed-in experience. 5. In Amplitude, go to _Users > User Profiles_ and search for the test account's User ID. 6. Open the profile, select the _Activity_ tab, and choose a post-sign-in event. 7. Select **Raw** and confirm the event contains the expected `user_id`. 8. Repeat for each source or platform that sends authenticated activity. ## Interpret the audit result - If every post-sign-in event carries the same stable `user_id`, the sample passes. - If a post-sign-in event has no `user_id`, write down the event name, device ID, platform, time, source library, and whether the event appears on the known profile. - If you can't find the account by User ID, search by device ID and check whether the signed-in events appear on an anonymous profile. This is a spot check, not a full measurement. To find the missing-`user_id` rate across every authenticated event, ask your data team to compare your authentication signal against a privacy-approved raw export. ## Amplitude identity behavior and limitations Amplitude can't add a `user_id` to the raw event after ingestion. If a later event sends a User ID with the same device ID, Amplitude can associate earlier anonymous activity from that device with the known user. The instrumentation fix still has to happen where your product sends events. - Use [User Lookup](https://amplitude.com/docs/analytics/user-data-lookup) and the raw event view to show exactly which events are missing the ID. - Use Session Replay to confirm that the user signed in during the session before you investigate tracking. Every plan includes Session Replay with plan-specific monthly limits. Growth and Enterprise customers can purchase additional capacity and capabilities. Go to [Pricing](https://amplitude.com/pricing) for current details. ## Send findings to your instrumentation owner The fix requires a code change. Send your engineers the facts from the audit. Copy the following template and replace the bracketed text: ```text In Amplitude, our signed-in events are missing a stable user_id. After a test account signs in on a clean device, event [EVENT NAME] on [PLATFORM] arrives with no user_id. The activity remains on device [DEVICE ID] until a later event identifies that device. This started around [DATE] / has always been the case. It affects [all platforms / just iOS / just web]. Set the canonical user_id right after authentication and before we track post-sign-in events. This is splitting our retention and cross-device reporting. ``` ## Get help without engineering resources You can't fix this issue inside Amplitude. Someone must change the event-sending implementation. Use these options in order: 1. Contact your Amplitude account team or Customer Success Manager. They can scope the problem and direct you to help. 2. Contact a partner or agency that manages your website or app analytics. 3. Contact Amplitude Support at [gethelp.amplitude.com](https://gethelp.amplitude.com) for product questions. Until engineers fix the instrumentation, mark any signed-in funnel or retention chart that relies on this flow as unreliable. To correct the instrumentation, follow the [engineering solution](https://amplitude.com/docs/data/data-assistant-user-solutions/missing-user-ids-engineering). ================================================================================ # User IDs set too early: confirm the problem URL: https://amplitude.com/docs/data/data-assistant-user-solutions/early-user-ids-audit Updated: 2026-09-22 ================================================================================ # User IDs set too early: confirm the problem A `user_id` should appear only after your product reliably identifies a user. If your product sets the ID too early, Amplitude associates unrelated anonymous activity with the same identity. For example, a shared device or an ID cached from a previous account can merge events from different people into one inaccurate profile. Charts still render, so the problem isn't obvious. Merged profiles make acquisition, onboarding, and first-session analysis inaccurate. Data Assistant doesn't detect identity timing problems, so you must confirm the problem manually. Run this audit when a new visitor's profile contains more activity than expected. You can also use the audit to validate a new anonymous journey. You need a clean test environment and access to the product. Amplitude can't determine when your application considers a user authenticated. Therefore, a full audit requires raw event data and a product-specific authentication signal. This procedure tests one journey at a time. ## Create a clean anonymous journey 1. Use a private browser window, a new browser profile, or a test device with cleared app data. 2. Open the product without signing in. 3. Complete several actions that an anonymous visitor can take. 4. Find the test device in [Event Explorer](https://amplitude.com/docs/analytics/charts/event-explorer) by IP address or device ID. You can also use _Users > User Profiles_ if you know the device ID. 5. Open each pre-authentication event and inspect its raw properties. 6. Confirm `user_id` has no value before your product authenticates the user. 7. Sign in, trigger another event, and confirm the post-sign-in event uses the expected User ID. ## Read the result - If pre-authentication events have no `user_id` and post-sign-in events use the stable account ID, the sample passes the audit. - If an anonymous event carries a placeholder, an email address, a cached ID from another account, or another premature value, write down the source library and the first affected event. - If your product restores a valid signed-in session on launch, setting the known User ID during initialization isn't an error. The product must be able to identify the user reliably at that moment. ## Amplitude can't repair merged profiles No chart or agent can separate a profile created with an early User ID. In a standard event-based project, Amplitude can't split an established User ID into the different people whose events it combines. Fixing the problem requires an instrumentation change that prevents early User ID assignment. Use Amplitude to verify the incorrect timing and identify its source. ## Give the evidence to your tracking owner Send your engineers the timing evidence. Copy this and fill in the brackets: ```text In Amplitude, we're setting user_id before authentication. On a fresh anonymous session, event [EVENT NAME] from [SOURCE / SDK] arrives with user_id already set to [VALUE, e.g. a placeholder / cached email / previous account id]. That merges unrelated anonymous activity onto one identity. Leave the User ID unset for unknown visitors and assign the canonical user_id only after authentication confirms who the person is. Also confirm logout clears the User ID on shared devices. ``` ## Get help without engineering resources You can't correct the timing inside Amplitude. Reach out in this order: - Your Amplitude account team or Customer Success Manager. - A partner or agency that manages your website or app analytics. - Amplitude Support at [gethelp.amplitude.com](https://gethelp.amplitude.com) for product questions. For implementation guidance about User ID timing and logout behavior, go to the [engineering solution](https://amplitude.com/docs/data/data-assistant-user-solutions/early-user-ids-engineering). ================================================================================ # Anonymous activity lost at login: confirm the problem URL: https://amplitude.com/docs/data/data-assistant-user-solutions/login-identity-merge-audit Updated: 2026-09-22 ================================================================================ # Anonymous activity lost at login: confirm the problem When someone browses anonymously and then signs in, Amplitude should join both halves of that session into one profile. When the join breaks, everything the person did before login lands on a separate anonymous profile. Their acquisition and onboarding behavior vanishes from funnels and retention, even though you tracked it. This is easy to miss. Both sets of events exist. They're just filed under two different people. Data Assistant doesn't check this transition, so you confirm it yourself. The lasting fix is an instrumentation change, but the diagram below shows exactly what has to hold true, and you can prove whether it does. Run this audit when onboarding funnels drop off unexpectedly right at the login step, or as a check on your sign-in flow. You need a clean test environment and permission to open [User Profiles](https://amplitude.com/docs/analytics/user-data-lookup). This procedure validates representative devices. It doesn't prove that every identity across your audience joins correctly. ![Diagram showing anonymous and signed-in events joining into one profile when login keeps the device ID, versus splitting into two profiles when login replaces the device ID](https://amplitude.com/docs/images/diagrams/identity-join-at-login.svg) ![Diagram showing anonymous and signed-in events joining into one profile when login keeps the device ID, versus splitting into two profiles when login replaces the device ID](https://amplitude.com/docs/images/diagrams/identity-join-at-login.dark.svg) ## Test the anonymous-to-known transition 1. Start with a private browser window, a new browser profile, or a test device with cleared app data. 2. Record the device ID. [Event Explorer](https://amplitude.com/docs/analytics/charts/event-explorer) can locate the test device by IP address or device ID. 3. Complete two or more actions before you sign in. 4. Sign in with a test account and complete two or more authenticated actions. 5. In Amplitude, go to _Users > User Profiles_ and search for the test account's User ID. 6. Open the profile and review the _Activity_ timeline. 7. Confirm the timeline includes both the anonymous events and the signed-in events, in the expected order. 8. Search for the original device ID and confirm it resolves to the same person, not a separate anonymous profile. ## Read the result - If one profile holds the complete journey, the sample passes. - If the pre-sign-in events stay on another profile, compare the raw `device_id` values immediately before and after sign-in. - If the device ID changes at sign-in, or the first signed-in event has no `user_id`, that's the break. Record those details for your engineers. ## What Amplitude can and can't do here Amplitude joins an anonymous device to a known person going forward, once the instrumentation is right. It can't retroactively reunite activity that already split onto two profiles in a standard project. So the goal is to fix the login flow, and the audit above is how you confirm what broke. ## Hand it to whoever owns your tracking The fix is a code change in the login flow. Give your engineers the device-ID evidence. Copy this and fill in the brackets: ```text In Amplitude, anonymous activity isn't joining to the user at login. In a test session, the anonymous events show device_id [D-BEFORE], but after sign-in the events show device_id [D-AFTER] and/or the first signed-in event has no user_id. The pre-login activity is landing on a separate anonymous profile. Keep the same initialized SDK instance across login, don't regenerate the device_id, and set the canonical user_id after authentication before the next event. This is dropping onboarding activity from our funnels. ``` ## If you have no engineering resources You can't repair the join inside Amplitude. Reach out in this order: - Your Amplitude account team or Customer Success Manager. - A partner or agency that manages your website or app analytics. - Amplitude Support at [gethelp.amplitude.com](https://gethelp.amplitude.com) for product questions. When you're ready to preserve the device relationship at login, continue with the [engineering solution](https://amplitude.com/docs/data/data-assistant-user-solutions/login-identity-merge-engineering). ================================================================================ # One person, many User IDs: confirm the problem URL: https://amplitude.com/docs/data/data-assistant-user-solutions/multiple-user-ids-audit Updated: 2026-09-23 ================================================================================ # One person, many User IDs: confirm the problem One person should be one Amplitude profile. When different sources send different `user_id` values for the same human, that person shatters into several profiles. Retention undercounts, funnels break mid-journey, and your active-user numbers drift, because Amplitude is treating one person as three. It usually comes from small inconsistencies: one source sends an email, another sends an uppercase version, a third sends a legacy account ID. Data Assistant can't catch this, because Amplitude has no way to know which external identifiers belong to one real person. You confirm it against a record you trust. Run this audit on a known example or a support case, or as a sample-based check. A complete audit needs an authorized identity source outside Amplitude and a privacy-reviewed comparison with exported Amplitude data. ![Diagram showing one real person split into three separate Amplitude profiles because sources send three different User ID values](https://amplitude.com/docs/images/diagrams/multiple-user-ids.svg) ![Diagram showing one real person split into three separate Amplitude profiles because sources send three different User ID values](https://amplitude.com/docs/images/diagrams/multiple-user-ids.dark.svg) ## Audit a known person 1. Choose a test account or a support case where you have permission to inspect the person's identifiers. 2. Record the immutable account ID your backend treats as canonical. 3. List any suspected variants: different casing, old account IDs, email addresses, or platform-specific IDs. 4. In Amplitude, go to _Users > User Profiles_. 5. Search for each candidate User ID and open every matching profile. 6. Compare event times, device IDs, and non-sensitive account properties to confirm whether the profiles are the same person. 7. Record which source or platform sends each incorrect User ID. > **Warning:** Don't use personal data as a shortcut > > Follow your organization's privacy policy when you compare identities. Don't export or share email addresses or other personal data unless your policy and permissions allow it. ## Decide the next step If the profiles are different people, nothing needs fixing. If they're one person, the source that sends the alternate ID has to change, which is an instrumentation fix. ## What Amplitude can and can't do here Amplitude's standard identity resolution can't merge two established User IDs, so no in-product action combines the historical activity of those profiles in one project. Going forward, you prevent new duplicates by standardizing the ID at the source. One narrow exception exists at the cross-project level: with the Portfolio add-on, the [User Mapping API](https://amplitude.com/docs/apis/analytics/user-mapping) maps different project-level User IDs to a global User ID for cross-project analysis. It doesn't rewrite user properties or replace correct identity instrumentation. Check [Pricing](https://amplitude.com/pricing) or contact [Amplitude Sales](https://amplitude.com/sales-contact) if cross-project analysis is what you need. ## Hand it to whoever owns your tracking Send your engineers the exact variants and their sources. Copy this and fill in the brackets: ```text In Amplitude, one person is split across multiple user_id values. Account [CANONICAL ID] also appears as [VARIANT 1], [VARIANT 2] from sources [SOURCE A], [SOURCE B]. This is splitting retention and funnels for that user. Standardize every source on the immutable backend account id, with consistent casing, and stop using email/username/platform ids as the user_id. ``` ## If you have no engineering resources You can't merge the existing profiles yourself. To stop new duplicates, you still need a source change. Reach out in this order: - Your Amplitude account team or Customer Success Manager. - A partner or agency that manages your website or app analytics. - Amplitude Support at [gethelp.amplitude.com](https://gethelp.amplitude.com) for product questions. When you're ready to standardize identity and understand the historical limits, continue with the [engineering solution](https://amplitude.com/docs/data/data-assistant-user-solutions/multiple-user-ids-engineering). ================================================================================ # Profiles that don't join across devices: confirm the problem URL: https://amplitude.com/docs/data/data-assistant-user-solutions/cross-device-identity-audit Updated: 2026-09-22 ================================================================================ # Profiles that don't join across devices: confirm the problem Amplitude should represent a person who uses your product on the web and on their phone as one user. When each platform sends a different User ID for the same account, Amplitude creates separate profiles. Cross-device journeys break, retention appears lower than the actual rate, and active-user counts increase. Data Assistant doesn't compare identities across platforms. Use a two-device test to confirm an identity mismatch. Fix the mismatch in your instrumentation by sending one canonical User ID from every platform. Run this audit when you suspect that Amplitude has split one account into separate web and mobile profiles or when you add a platform. The audit requires a dedicated test account with a known canonical account ID and access to two devices or platforms. ![Diagram showing web and mobile activity joining into one user profile when both send the same User ID, versus splitting into two profiles when identity differs by platform](https://amplitude.com/docs/images/diagrams/cross-device-join.svg) ![Diagram showing web and mobile activity joining into one user profile when both send the same User ID, versus splitting into two profiles when identity differs by platform](https://amplitude.com/docs/images/diagrams/cross-device-join.dark.svg) ## Run a cross-device test 1. Choose a test account with a known canonical account ID. 2. Sign in on the first platform, such as web, and trigger several identifiable actions. 3. Sign in with the same account on the second platform, such as mobile, and trigger different identifiable actions. 4. In Amplitude, go to _Users > User Profiles_ and search for the canonical User ID. 5. Open the profile and confirm its activity timeline holds events from both platforms. 6. Open one event from each platform, select **Raw**, and compare the `user_id` values. 7. Search for any platform-specific ID you suspect and check whether it creates a separate profile. ## Interpret cross-device test results - If the same profile holds both journeys and both platforms send the identical `user_id`, the sample passes. - If each platform creates a different profile, record both User IDs, their casing, source libraries, and event times. - If one platform never sends a User ID, treat the issue as a missing-User-ID problem and use the [missing User IDs](https://amplitude.com/docs/data/data-assistant-user-solutions/missing-user-ids-audit) guide. This audit doesn't scan every account. To audit all accounts, ask your data team to compare platform identifiers against your canonical account table in a privacy-approved environment. ## Limitations of cross-device identity in Amplitude Amplitude joins a person across devices when every platform sends the same User ID. Amplitude can't merge two profiles that already formed from mismatched identity in a standard project. Align the platform instrumentation based on which platform sends the mismatched User ID in the cross-device test. ## Report the mismatch to the tracking owner Send the mismatch to the engineers who own tracking. Copy and complete this template: ```text In Amplitude, the same account shows up as separate profiles per platform. On [PLATFORM A] the user_id is [VALUE A]; on [PLATFORM B] it's [VALUE B] (or missing). Same person, two profiles, so cross-device retention and journeys are broken. Send the same immutable, case-consistent user_id from every platform for a signed-in person. ``` ## Get help without engineering resources You can't align the platforms inside Amplitude. Contact the following resources in order: - Your Amplitude account team or Customer Success Manager. - A partner or agency that manages your website or app analytics. - Amplitude Support at [gethelp.amplitude.com](https://gethelp.amplitude.com) for product questions. When you're ready to align identity across platforms, continue with the [engineering solution](https://amplitude.com/docs/data/data-assistant-user-solutions/cross-device-identity-engineering). ================================================================================ # Planned events that never arrived: confirm the problem URL: https://amplitude.com/docs/data/data-assistant-user-solutions/planned-unseen-events-audit Updated: 2026-09-22 ================================================================================ # Planned events that never arrived: confirm the problem An event can remain in your tracking plan for months even if the team never ships the code that sends it. The entry clutters your taxonomy and incorrectly indicates that the team implemented the event. To prove that an event is obsolete, you must distinguish an unimplemented event from an event with no recent activity. Data Assistant doesn't identify these entries. Observe shows whether Amplitude received an event during the selected time range, up to 14 days. Use your planning records to determine when someone planned the event. Use an approved raw-data source to check a longer history. Run this audit as part of a scheduled taxonomy review. You need permission to manage data in the project. Without a planning record, you can confirm that an event has no observed data. However, you can't establish how long the event has been in the tracking plan. ## Build the review list 1. In Amplitude Data, go to _Data > Events_ and review the events in your tracking plan. 2. Set Observe to its longest available time range and find planned entries with no observed data. 3. Use your planning record to find entries that have remained unimplemented beyond your review period, such as 90 days. 4. Ask the event owner whether the implementation still belongs on the roadmap. 5. Ask an analyst or data engineer to check an authorized raw-data export or warehouse for the exact event name. If an authorized source is unavailable, record the result as "not observed in Amplitude Data." Don't claim that the event never arrived. 6. Check the event's description, source, owner, and related branch or ticket before you approve removal. > **Warning:** No activity doesn't prove an event is obsolete > > An event might belong to a rare workflow, a disabled feature, or a future release. Confirm the decision with the product and engineering owners before you remove the event from the plan. ## Amplitude verification limits Observe shows which events arrive during the selected time range. Your planning system records which events the team planned. Planned events with no observed data form the review list. After the owner approves removal, delete the planned entry in Amplitude Data or use the Taxonomy API. Follow the [removal guide](https://amplitude.com/docs/data/data-assistant-user-solutions/planned-unseen-events-engineering). > **Tip:** Ask Global Agent > > [Global Agent](https://amplitude.com/docs/amplitude-ai/global-agent-overview) can check event volume. Try a prompt like: > > "Has the event \[EVENT NAME\] received any data in the last 180 days?" > > Review the result and its supporting data to confirm whether the event arrived during that period. Global Agent can't determine when someone planned the event. Use your planning records to find the creation date. Global Agent also can't remove the plan entry. ## Record whether to keep or remove the event If the implementation is still planned, keep the event and assign an owner and review date. If the event no longer belongs in the plan, send the exact ingested name and approval record to the person responsible for the [removal procedure](https://amplitude.com/docs/data/data-assistant-user-solutions/planned-unseen-events-engineering). ================================================================================ # Failures you can't see: confirm the coverage gap URL: https://amplitude.com/docs/data/data-assistant-user-solutions/error-event-coverage-audit Updated: 2026-09-23 ================================================================================ # Failures you can't see: confirm the coverage gap Amplitude should receive a failure event when a checkout, login, payment, or upload fails. Often, you track only the success event. A broken step then looks like a user who left. Conversion appears to drop, but no chart can identify the cause. Missing failure signals can cause teams to spend weeks optimizing a funnel that measures a product bug. Data Assistant only sees the events your product sends, so it can't identify a missing failure event. Run this audit on journeys where a failure costs revenue, access, activation, or trust. Use a Funnel Analysis chart for instrumented steps. Session Replay can provide supporting evidence of a visible failure, but a replay doesn't replace a structured failure event. ![Diagram of a two-step funnel with a large drop between checkout started and payment completed, and a callout noting that no failure event exists to explain the drop](https://amplitude.com/docs/images/diagrams/invisible-funnel-failure.svg) ![Diagram of a two-step funnel with a large drop between checkout started and payment completed, and a callout noting that no failure event exists to explain the drop](https://amplitude.com/docs/images/diagrams/invisible-funnel-failure.dark.svg) ## Audit a critical journey 1. List the journeys where a failure affects revenue, access, activation, or trust. 2. For each journey, name the successful outcome and every distinct failure outcome that requires a different response. 3. In Amplitude Data, go to _Data > Events_ and search for the matching events. 4. Review each event's description and properties. Confirm that the definition separates a completed action from a failed attempt. 5. Build a Funnel Analysis chart for the expected path and look for unexplained drop-off before the success event. 6. Reproduce a safe test failure and use [Event Explorer](https://amplitude.com/docs/analytics/charts/event-explorer) to check which events arrive. 7. Record the missing events and missing diagnostic properties in the tracking plan before implementation. > **Warning:** Drop-off doesn't prove a technical failure > > Users abandon flows without encountering an error. Confirm a missing failure signal with product behavior, support evidence, application logs, or a controlled test before you request instrumentation. ## What Amplitude can and can't do here Amplitude can't count a failure event that your product never sends, and no chart can reconstruct the event later. Amplitude can help you locate and characterize the instrumentation gap: - Use [Session Replay](https://amplitude.com/docs/session-replay/overview) to watch real sessions and check whether users encounter a visible error or leave without one. Every plan includes Session Replay with plan-specific monthly limits. Growth and Enterprise customers can purchase additional capacity and capabilities. Refer to [Pricing](https://amplitude.com/pricing) for current details. - After the failure event exists, an alert on the event volume warns you when failures spike. Availability of anomaly detection and alerts varies by plan. Refer to [Pricing](https://amplitude.com/pricing) or contact [Amplitude Sales](https://amplitude.com/sales-contact). > **Tip:** Ask Global Agent > > [Global Agent](https://amplitude.com/docs/amplitude-ai/global-agent-overview) can build the funnel and identify the drop from plain-language instructions. Try this prompt: > > "Build a funnel from Checkout Started to Payment Completed over the last 8 weeks and show me the step with the biggest drop-off." > > Review the generated funnel and supporting data to confirm where conversion falls. Global Agent can't add a failure event that your product never sends. ## Send the instrumentation gap to the tracking owner Adding a failure event requires a code change. Send your engineers the confirmed instrumentation gap. Copy and complete this template: ```text Our [FLOW NAME] flow has no failure event, so we can't see why users drop between [UPSTREAM EVENT] and [SUCCESS EVENT]. Add an event that fires when the [FLOW NAME] step fails, with safe diagnostic properties (for example flow, step, error_type, error_code). No stack traces, tokens, payment details, or emails. Add it to the tracking plan first. This is hiding real drop-off in our reporting. ``` ## If you have no engineering resources You can't create a missing failure signal inside Amplitude. Contact the following resources in order: - Your Amplitude account team or Customer Success Manager. - A partner or agency that manages your website or app analytics. - Amplitude Support at [gethelp.amplitude.com](https://gethelp.amplitude.com) for product questions. Until the failure event exists, treat the affected funnel as incomplete. Use Session Replay to understand individual cases. To instrument the missing signals, continue with the [engineering solution](https://amplitude.com/docs/data/data-assistant-user-solutions/error-event-coverage-engineering). ================================================================================ # No activation event: choose and validate one URL: https://amplitude.com/docs/data/data-assistant-user-solutions/activation-event-audit Updated: 2026-09-22 ================================================================================ # No activation event: choose and validate one Activation is the first moment a new user clearly gets value from your product. To measure activation, you need an event that marks that moment. Many teams lack an activation event or use a proxy that doesn't represent value, such as a page view. Without the right event, activation and early retention analysis use an inaccurate signal. Data Assistant can't choose an activation event for you. Activation is a business decision about your product, and Data Assistant can't detect that the event data needed to measure activation is missing. Choosing and validating an activation event requires judgment, but most of the work requires no code. Choose and validate an existing event before you ask anyone to write code. Use Funnel Analysis and Retention Analysis after you find a candidate. Compass can surface behaviors that correlate with retention. A correlation doesn't prove that a behavior causes retention. ## Choose the activation outcome 1. Describe the value the user receives, not the screen or button they select. Prefer a completed collaboration over a page view, for example. 2. Choose the earliest outcome that reflects real value and that your team can influence. 3. In _Data > Events_, search for an event whose definition matches that outcome. 4. If a candidate exists, open the event details and confirm the trigger, source, owner, and properties. 5. Build a Funnel Analysis chart from a new-user starting event to the candidate event. 6. Build a Retention Analysis chart or a [Compass chart](https://amplitude.com/docs/analytics/charts/compass/compass-find-inflection-metrics) to check whether users who reach the candidate return or convert at a different rate. 7. Review the result with product, data, and engineering owners before you adopt the event as the activation signal. ## Amplitude options and limitations If one existing event already describes the full activation outcome, use the event directly. When any of several existing events qualifies, a [custom event](https://amplitude.com/docs/data/custom-events) combines the events with an `OR` condition. The custom event can serve as the analysis signal without an application release. A custom event doesn't create raw telemetry or combine an ordered sequence of actions into a new event. If the outcome isn't captured anywhere, no in-product tool can invent the signal. In that case, you need new instrumentation. > **Tip:** Ask Global Agent > > [Global Agent](https://amplitude.com/docs/amplitude-ai/global-agent-overview) can find relevant existing events and build analyses that compare them. Try prompts like: > > "Is there an event that represents when a new user first gets value from the product?" > > "For users who signed up in the last 90 days, which early actions correlate with staying active after four weeks?" > > Review the generated analysis and supporting data before you choose a signal. Global Agent can't create a signal you never tracked. ## Send requirements to the tracking owner When you need a new signal, send your engineers a precise definition. Copy this and fill in the brackets: ```text We need an activation event that fires when a new user reaches [OUTCOME, in product terms, not a screen]. Trigger: [WHEN EXACTLY]. It should carry [USER ID + these properties]. No existing event represents this outcome. Add it to the tracking plan and instrument it. We need it for activation and retention analysis. ``` ## If you have no engineering resources If a custom event can't cover the outcome, you need a source change. Contact the following in order: - Your Amplitude account team or Customer Success Manager. - A partner or agency that manages your website or app analytics. - Amplitude Support at [gethelp.amplitude.com](https://gethelp.amplitude.com) for product questions. When you need to instrument a new activation signal, continue with the [engineering solution](https://amplitude.com/docs/data/data-assistant-user-solutions/activation-event-engineering). ================================================================================ # Missing or mistimed exposure: confirm the problem URL: https://amplitude.com/docs/data/data-assistant-user-solutions/experiment-exposure-audit Updated: 2026-09-22 ================================================================================ # Missing or mistimed exposure: confirm the problem An experiment result is trustworthy only if the exposure event fires when a user encounters the variant. Missing or early exposure events, or events from users who didn't see the variant, cause the analysis to measure the wrong population. Data Assistant doesn't perform this experiment-specific check. Use Experiment diagnostics and individual user timelines to confirm exposure timing. Use Experiment diagnostics for Amplitude experiments. If another system assigns variants, compare that system's assignment records with the exposure event in Amplitude. ## Review aggregate diagnostics 1. Open the running experiment and find the _Diagnostics_ card. 2. Review cumulative exposures for unexpected gaps, spikes, or diverging variant lines. 3. Review the assignment-to-exposure funnel when it appears. 4. Review _Exposures without Assignments_ when it appears. The chart doesn't appear when the assignment event serves as the exposure event or the experiment uses local evaluation. 5. Segment `[Experiment] Exposure` by flag key in an Event Segmentation chart when you need to isolate one flag's trend. ## Inspect representative users 1. Choose test users from each variant, including important identity transitions such as sign-in or account switching. 2. Go to _Users > User Profiles_ and open each account's event timeline. 3. Confirm that assignment precedes exposure when your evaluation mode produces both events. 4. Confirm exposure fires when the user encounters the variant, not when code fetches an unused variant or returns a fallback value. 5. Compare the `user_id` and `device_id` values on assignment, exposure, and surrounding metric events. Some assignment and exposure events arrive on different days. A delay is a problem if identity or targeting properties change between the events. ## Exposure correction limits in Amplitude Amplitude can't create or retime exposures that your implementation never sent. Changing an analysis setting doesn't recover missing or mistimed exposures. Use diagnostics and timelines to identify where exposure timing breaks so engineers can correct exposure for the applicable evaluation mode. ## Send findings to the experiment owner Correcting exposure requires a code or configuration change. Send engineers the findings. Copy this template and replace the brackets: ```text Our experiment [NAME / FLAG KEY] has an exposure problem. In diagnostics/user timelines, [describe: exposure is missing / fires before the variant renders / fires for users with no assignment / identity changes between assignment and exposure]. Evaluation mode is [client / remote / server-side local]. Make exposure fire only when the user actually encounters the variant, with the same user_id and device_id as the metric events. Our experiment metrics are unreliable until this is fixed. ``` ## If you have no engineering resources Exposure tracking is instrumentation, so someone who can change the experiment integration must complete this work. Contact these resources in order: - Your Amplitude account team or Customer Success Manager. - A partner or agency that manages your experimentation setup. - Amplitude Support at [gethelp.amplitude.com](https://gethelp.amplitude.com) for product questions. To correct exposure for your evaluation mode, continue with the [engineering solution](https://amplitude.com/docs/data/data-assistant-user-solutions/experiment-exposure-engineering). ================================================================================ # No account-level analysis: decide whether you need groups URL: https://amplitude.com/docs/data/data-assistant-user-solutions/group-types-audit Updated: 2026-09-23 ================================================================================ # No account-level analysis: decide whether you need groups If you sell to companies, some of your most important questions are about accounts, not people: how many accounts activated, which teams adopted a feature, whether a company is healthy at renewal. By default, Amplitude counts individual users. To count accounts, you need group types and the Accounts add-on. Data Assistant can't infer your B2B model, so it won't tell you this is missing. This page is a decision first, not an instrumentation task. Groups add real value, but they're also an add-on and an implementation project, so it's worth confirming you actually need account-level counting before you commit. Use individual-user analysis when one person completes the behavior you measure. Use account-level reporting when several people contribute to one account outcome, or when the question is how many accounts act, retain, or convert. ![Diagram contrasting Amplitude counting six individual users by default with grouping those users into two accounts after you add group types](https://amplitude.com/docs/images/diagrams/users-into-accounts.svg) ![Diagram contrasting Amplitude counting six individual users by default with grouping those users into two accounts after you add group types](https://amplitude.com/docs/images/diagrams/users-into-accounts.dark.svg) ## Evaluate the reporting need 1. List the decisions that need account-level data, such as account activation, team adoption, renewal health, or company conversion. 2. For each one, identify the stable business object that owns the outcome. 3. Confirm the object has a durable identifier, such as an internal `account_id`, rather than a display name. 4. Decide whether each relevant event belongs to the group only for that event, or whether the person's group membership should persist across future events. 5. In Amplitude Data, go to _Data > Groups_ and check whether the project already defines that group type. 6. If the group exists, open _Users > Group Profiles_ and confirm test accounts have recent activity. > **Note:** Accounts is an add-on > > Account-level reporting requires the Accounts add-on. Group fields in the HTTP V2 API require the Growth or Enterprise plan plus that add-on. Check [Pricing](https://amplitude.com/pricing) or contact [Amplitude Sales](https://amplitude.com/sales-contact) before you plan implementation. ## What Amplitude can and can't do here Amplitude can't add group context to events after they arrive, and there's no no-code shortcut that turns user-level data into true account-level counting. If you only need to segment by a company attribute occasionally, a user property such as `company_name` on each person may answer the question without the full groups model. If you need to count and retain accounts as first-class objects, groups and the Accounts add-on are the right tool. Refer to [account-level reporting](https://amplitude.com/docs/analytics/account-level-reporting) for what the add-on unlocks. > **Tip:** Ask Global Agent > > [Global Agent](https://amplitude.com/docs/amplitude-ai/global-agent-overview) understands your project's taxonomy, so it can inform the decision. Try a prompt like: > > "Which group types does this project define, and which have recent activity?" > > It tells you what account-level structure already exists, but it can't create group types or enable the Accounts add-on. ## Decide and route If the business can answer its questions at the individual level, don't add a group type. If account-level analysis is genuinely necessary, confirm the add-on with your Amplitude account team, then continue with the [engineering solution](https://amplitude.com/docs/data/data-assistant-user-solutions/group-types-engineering). ================================================================================ # Missing shared context: confirm the coverage gap URL: https://amplitude.com/docs/data/data-assistant-user-solutions/shared-properties-audit Updated: 2026-09-22 ================================================================================ # Missing shared context: confirm the coverage gap Shared properties should appear on nearly every event. Examples include platform, app version, product area, tenant, and release channel. When some events or sources omit a shared property, you can't reliably break down analysis by that property. When you group by a missing event or user property, Amplitude places the affected events or users in the `(none)` bucket. Your analysis requirements determine which properties count as shared context, so Data Assistant doesn't identify missing shared context. Define the shared-property standard, then compare the standard against your tracking plan and observed data. The audit requires no code, but closing coverage gaps usually requires an instrumentation change. Run this audit when breakdowns by a key dimension look incomplete or as part of a taxonomy review. Use Amplitude's default SDK properties when they answer your analysis question. Add a custom shared property only for a specific analysis or governance need. ## Define the shared property set 1. List the analysis questions that need context across many events. 2. For each question, decide whether the context describes the person or an event occurrence. Use a user property for a persistent person-level attribute. Use an event property for context at the time of the action. 3. Remove fields that duplicate Amplitude's [default user properties](https://amplitude.com/docs/data/user-properties-and-events#user-properties). 4. Agree on the property name, type, allowed values, owner, and privacy classification. 5. Identify the events and sources that must send the property. ## Check coverage in Amplitude Data 1. Go to _Data > Properties_ and search for each approved property. 2. Open the property and review which events and sources use the property. 3. Create a [property group](https://amplitude.com/docs/data/property-updates-property-groups) when many planned events need the same event properties. 4. Mark each required event-property relationship in the tracking plan. 5. Open [Observe](https://amplitude.com/docs/data/validate-events) and review the `% Seen` indicator for each required property and source. 6. Record events where the property is absent, has the wrong type, or appears only on some sources. > **Note:** The tracking plan doesn't populate values > > Adding a property or property group to the plan defines the expected schema. The tracking plan doesn't add the property to incoming events. Engineering has to update each affected source. ## How Amplitude can address missing shared properties Amplitude can't add a property to historical events that never included the property. The tracking plan defines expectations rather than data. If existing raw properties already contain the value, a [derived property](https://amplitude.com/docs/data/derived-properties) can compute the value at query time. A derived property supports analysis but doesn't change the source payload or fill the ingestion gap for the original property. > **Tip:** Ask Global Agent > > [Global Agent](https://amplitude.com/docs/amplitude-ai/global-agent-overview) can quantify the coverage gap. Try this prompt: > > "Build a chart of \[EVENT\] grouped by \[PROPERTY\] for the last 30 days and show the share of events with no value for \[PROPERTY\]." > > Review the generated chart and supporting data to measure the `(none)` bucket. Global Agent can't add the property to events that don't send the property. ## Send coverage gaps to your tracking owner Closing shared-property coverage gaps requires a source change. Send your engineers the property contract and affected sources. Copy this template and fill in the brackets: ```text We need shared property [NAME] ([user property / event property], type [TYPE], allowed values [VALUES]) on [these events / all events] from [these sources]. In Observe it's missing or partial on [SOURCES / EVENTS]. Send it consistently, with the same name, type, and values across web, mobile, backend, and any CDP mapping. It's blocking breakdowns by [DIMENSION]. ``` ## If you have no engineering resources If a derived property can't meet the analysis need, meeting the need requires a source change. Contact these resources in order: - Your Amplitude account team or Customer Success Manager. - A partner or agency that manages your website or app analytics. - Amplitude Support at [gethelp.amplitude.com](https://gethelp.amplitude.com) for product questions. When you're ready to fix the missing sources, continue with the [engineering solution](https://amplitude.com/docs/data/data-assistant-user-solutions/shared-properties-engineering). ================================================================================ # Event vs user property confusion: confirm the problem URL: https://amplitude.com/docs/data/data-assistant-user-solutions/property-classification-audit Updated: 2026-09-23 ================================================================================ # Event vs user property confusion: confirm the problem An event property describes one action, such as the item purchased or the error code returned. A user property describes the user at the time of an event, such as their plan or account role. User property values can change. Amplitude applies a new value to later events without rewriting earlier events. When a property has the wrong type, filters and groupings can return an answer that doesn't match the analysis question. Data Assistant doesn't detect this modeling error. Review the property manually without changing code. If the property type is wrong, correcting the source requires an instrumentation change. The diagram shows how each property type applies over time. Choose the type based on the analysis question. ![Diagram contrasting an event property that belongs to one event occurrence with a user property that applies to later events until its value changes](https://amplitude.com/docs/images/diagrams/event-vs-user-property.svg) ![Diagram contrasting an event property that belongs to one event occurrence with a user property that applies to later events until its value changes](https://amplitude.com/docs/images/diagrams/event-vs-user-property.dark.svg) ## Review a property's classification 1. Write the analysis question the property has to answer. 2. Determine whether the value belongs only to its event or applies to later events from the same user. 3. In Amplitude Data, go to _Data > Properties_ and search both the **Event Properties** and **User Properties** tabs. 4. Check whether the same or a similar name appears under both types. 5. Open [User Profiles](https://amplitude.com/docs/analytics/user-data-lookup) for representative users. Compare the value on individual events with the current user property value at the top of each profile. 6. Build an Event Segmentation chart that compares the event property and user property versions. Confirm which version answers the analysis question. 7. Record the intended type, source, owner, and whether historical analysis needs a temporary workaround. > **Warning:** Amplitude can't directly convert the property type > > Transformations merge event properties with event properties and user properties with user properties. Transformations don't convert an ingested event property into a regular user property or the reverse. ## Analysis-layer alternatives to a property type correction A property type correction happens at the source. Before changing instrumentation, check these analysis-layer options, which don't require an application release: - For numeric aggregates, counts, or first and last values, [Computations](https://amplitude.com/docs/analytics/computations) can create a computed user property from existing event data. Availability varies by plan, so check [Pricing](https://amplitude.com/pricing) if the feature doesn't appear. - A [derived property](https://amplitude.com/docs/data/derived-properties) can reshape existing data at query time. Computations and derived properties support analysis, but they don't replace correct source modeling or rewrite raw history. > **Tip:** Ask Global Agent > > [Global Agent](https://amplitude.com/docs/amplitude-ai/global-agent-overview) can build a comparison that reveals the modeling problem. Try this prompt: > > "Compare \[PROPERTY\] as an event property and as a user property for \[your question\], and tell me which one answers it correctly." > > Review the generated comparison and its supporting data. You decide which property type fits the business question. Global Agent can't change a property's type. ## Send the correction to your tracking owner When the source model must change, send your engineers the intended classification. Copy and complete this template: ```text Property [NAME] is modeled as an [event property / user property] but should be a [user property / event property], because we need to answer [QUESTION]. Send future values as the correct type (target name [NAME]) per the migration plan. Note this affects new data only and doesn't rewrite history. ``` ## If you have no engineering resources If Computations or a derived property can't answer the question, you need a source change. Contact these resources in order: - Your Amplitude account team or Customer Success Manager. - A partner or agency that manages your website or app analytics. - Amplitude Support at [gethelp.amplitude.com](https://gethelp.amplitude.com) for product questions. When the source model needs correcting, continue with the [engineering solution](https://amplitude.com/docs/data/data-assistant-user-solutions/property-classification-engineering). ================================================================================ # Missing insert_id or session_id: confirm the problem URL: https://amplitude.com/docs/data/data-assistant-user-solutions/event-identifiers-audit Updated: 2026-09-22 ================================================================================ # Missing insert_id or session_id: confirm the problem `insert_id` and `session_id` protect event counts and session metrics. `insert_id` lets Amplitude discard duplicate copies of a retried event when the copies have the same `device_id`. This prevents network retries from inflating event counts. `session_id` groups a user's events into a session for Session Analysis. Missing values can cause incorrect counts and session metrics. Data Assistant doesn't check these fields. Requirements vary by source. Amplitude SDKs manage `session_id` automatically for supported client platforms. Events sent through the HTTP API need an explicit `session_id` to join session metrics. `insert_id` matters most for retried server-side events. Audit representative events to confirm both fields. Run this audit if event counts seem inflated or Session Analysis results seem incorrect. Also run the audit when you add a server or HTTP API source. You need access to [User Profiles](https://amplitude.com/docs/analytics/user-data-lookup). ![Diagram showing Amplitude storing one copy when a retry has the same device_id and insert_id, versus dropping a second real event when the same device reuses those identifiers within seven days](https://amplitude.com/docs/images/diagrams/insert-id-dedup.svg) ![Diagram showing Amplitude storing one copy when a retry has the same device_id and insert_id, versus dropping a second real event when the same device reuses those identifiers within seven days](https://amplitude.com/docs/images/diagrams/insert-id-dedup.dark.svg) ## Audit representative events 1. List each client SDK, server, and customer data platform source in the project. 2. Choose at least one active test event from each source. 3. Trigger the test event and open the user's profile in _Users > User Profiles_. 4. Select the event, choose **Raw**, and record its source library, `insert_id`, and `session_id`. 5. For server events that your system retries, confirm that each logical event has a non-empty `insert_id`. Retries of the same event must reuse the `insert_id` value. Different events must use different `insert_id` values. 6. For client SDK events that belong to an in-product session, confirm that `session_id` contains a positive session start time. The `session_id` value must remain the same throughout one session. 7. For HTTP API events that should join Session Analysis, confirm that `session_id` isn't missing or `-1`. 8. Confirm that `session_id: -1` is intentional for out-of-session events, such as some push-notification events. > **Note:** A sample doesn't measure project-wide coverage > > User Profiles and Event Explorer support targeted QA. To calculate missing-field rates across every source, ask your data team to query an authorized export or warehouse copy of the raw events. ## How Amplitude handles missing identifiers Amplitude can't populate `insert_id` or `session_id` after ingestion. You must correct the SDK, server, or CDP mapping. For sessions, Amplitude provides one analysis-layer option. An Admin or Manager can define a [custom session](https://amplitude.com/docs/data/sources/instrument-track-sessions) from another property, from start and end events, or from a timeout. Custom sessions can support Session Analysis without changing every payload. However, custom sessions don't add missing raw `session_id` values. Custom session definitions also affect session-based charts across the whole project. ## Send requirements to the tracking owner Correcting these fields is an instrumentation change. Send the affected sources to the team that owns your tracking. Copy this message and fill in the brackets: ```text Some of our events are missing event identifiers. On source [SOURCE], event [EVENT] arrives with [insert_id missing/duplicated / session_id missing or -1]. For retried server events, send a unique insert_id and reuse it on retries. For HTTP API events that should join sessions, send session_id as the session start time in epoch milliseconds. This is [inflating our counts / breaking Session Analysis]. ``` ## Get help without engineering resources You can't add these fields to incoming events yourself. Contact these resources in order: - Your Amplitude account team or Customer Success Manager. - A partner or agency that manages your website or app analytics. - Amplitude Support at [gethelp.amplitude.com](https://gethelp.amplitude.com) for product questions. To correct the affected sources, continue with the [engineering solution](https://amplitude.com/docs/data/data-assistant-user-solutions/event-identifiers-engineering). ================================================================================ # Getting set up with Amplitude Data URL: https://amplitude.com/docs/data/amplitude-data-get-started Updated: 2026-09-01 ================================================================================ # Getting set up with Amplitude Data Setting up event tracking means designing a tracking plan, implementing it with typed SDK code, catching instrumentation drift in QA, and retiring events as your product changes. Amplitude Data covers this full data lifecycle: planning, instrumenting, validating, and deprecating the events your product sends to Amplitude. ## Get data into Amplitude Amplitude supports several methods for ingesting data. You can collect data from your app using [SDKs](https://amplitude.com/docs/get-started/get-data-in). ### Choose an ingestion method Consider these factors when deciding which ingestion method works best for your organization. #### Use Amplitude SDKs Amplitude SDKs are a good way to integrate if you're getting started with analytics. You can use Ampli to keep your instrumentation clean from the start while retaining the flexibility to send data to [various destinations](https://amplitude.com/docs/data/destination-catalog) later. When using Amplitude SDKs, decide whether to send events from front-end clients or back-end servers: - **Client-side tracking**: Add client-side SDKs to your web and mobile apps. This method can be more direct because you can use default event tracking and capture both client-side and server-side interactions with your application. However, events that span all your clients require deployment changes across all your apps. On mobile, updates can take time depending on how long it takes your customers to update their apps. - **Server-side tracking**: Send events directly from your servers to Amplitude. For example, when tracking an order completion, send the event from the back-end server that processes the order. This centralized approach is generally the most reliable because a single place in your control sends the events. You also don't have to wait for customers to update their app version. Amplitude recommends server-side tracking for events that require high precision and client-side tracking for everything else. #### Use cloud storage, warehouses, and event streaming If you already have a reliable data source, connecting to that source can be the fastest way to get started with Amplitude. Customers often use these methods to connect with current sources of truth and use Amplitude's self-serve capabilities to expand data access across their company. You can use Amplitude's data management capabilities even when you connect through an existing source. ## What to track Identifying and planning the events and properties you want to track is essential to maximizing your data. A solid tracking plan helps you answer business questions and prevents gaps in your analyses. Use these resources to help decide what to track: - To get started quickly, read about [what events you need](https://amplitude.com/docs/get-started/select-events). That article recommends events and properties commonly tracked in each industry. - Refer to the [data planning playbook](https://amplitude.com/docs/data/data-planning-playbook) for a deeper understanding of creating a taxonomy from scratch. - If you've identified events and properties to track and want to get them into Amplitude, refer to [creating your tracking plan](https://amplitude.com/docs/data/create-tracking-plan). ## Best practices These practices help ensure good results both initially and as you scale with Amplitude Data. ### Establish a naming convention Simple, self-explanatory names that follow a consistent convention make your plan understandable across your organization. Consistent naming also prevents data quality issues. Two events with different capitalizations, such as `Song Played` and `song played`, appear as two separate events. Set your naming convention in [Settings](https://amplitude.com/docs/data/amplitude-data-settings), and Amplitude Data prompts anyone who creates events to follow that convention. ### Use a separate environment for testing Keep your data clean by using separate projects for development and production. Separate projects let you test your implementation without affecting your final business reports. They're also a good place to try data management tools before applying them to production data. Refer to [creating a project in Amplitude](https://amplitude.com/docs/get-started/create-project). ================================================================================ # Autocapture URL: https://amplitude.com/docs/data/autocapture Updated: 2026-09-09 ================================================================================ # Autocapture Autocapture collects a predefined set of user interactions from your website or app with one SDK snippet, no event-by-event instrumentation. On web, it captures sessions, page views, clicks, form interactions, file downloads, marketing attribution, and page URL enrichment through the [Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2); on iOS and Android, it captures installs, upgrades, sessions, and screen views through the [iOS Swift SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk) and [Android-Kotlin SDK](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk). Turn it on when you want baseline product analytics quickly, before you scope custom event tracking. Use Autocapture when you want broad baseline coverage immediately with no instrumentation work. Use precision tracking when you need custom events or properties tied to specific business logic, such as purchases or feature-specific actions. The two work together, so most teams run both. On the web, you can also use visual labeling to navigate your site and create new events from the click information. ## Autocapture and precision tracking Amplitude offers two primary ways to capture events: - Autocapture automatically collects a predefined set of events and properties in a standardized taxonomy using Amplitude SDKs. - Precision tracking instruments events and properties specific to your business needs and analyses. From the moment you install the SDK, Amplitude automatically collects data to provide insights into feature usage, funnel conversion rates, and click analysis on the web. The Browser SDK also enriches all events with page URL information, including previous page tracking and page type classification. Autocapture minimizes setup time, so you can move straight to analysis. To investigate specific actions in your application that require additional metadata, or to track events such as a purchase event that may be core to your business, use precision tracking. Precision tracking in code sends these events with a robust set of properties for deeper analysis. For example, imagine you're releasing a new feature and don't have time to implement precision tracking. Autocapture can serve as a safety net for collecting baseline metrics and answering engagement questions. After you have these insights and want to go deeper, work with your team to implement precisely tracked events and get the best of both approaches. ## Optimize your event volume Autocapture provides several configuration options to help you adjust your implementation to your needs. You can turn individual Autocapture events on and off as needed and tune those events further to optimize your event volume. The default configuration provides the right balance of automatically capturing events that matter while excluding ones that don't. This balance is critical when capturing clicks. By default, Amplitude captures clicks on interactive elements (for example, links, text fields, dropdowns, and other form elements). Amplitude also captures clicks on elements that result in a change on the page (for example, a new visual element) or a navigation to a new page. This configuration excludes clicks on blank areas, text highlighting, and similar actions to ensure you don't pay for low-value user behaviors. Amplitude recommends monitoring your event volume (go to _Settings > Plans & Billing_) as you make changes to ensure it matches your expectations. You can change your configuration to capture clicks only on specified elements (or elements with certain classes), track only on specific pages, or turn click tracking off while still using other Autocapture data such as page views and sessions. ## Your taxonomy with Autocapture Keeping your taxonomy clean and organized ensures users can find what they need. When you enable Autocapture, you get a predefined set of event and property types for ingestion. For example, the SDK captures click interactions as two events ("Element Clicked" and "Element Changed") with a predefined set of properties rather than a stream of noisy user interactions. With [visual labeling](https://amplitude.com/docs/data/visual-labeling), users in your organization create events directly from the UI. Consider the following when you plan your taxonomy: - Set up the correct permissions for each user. Users with a Member role or higher can create labeled events. - Align your naming convention with your existing taxonomy for labeled events. - Add descriptions to your labeled events to help other users understand their purpose. Additional details about labeled events: - Labeled events have a separate tab in _Data > Events_ to help you manage them differently from your raw ingested events. This tab displays who created the labeled events and the creation date for each event. - Labeled events have a different icon in the event dropdown so you and your users can distinguish them from other events. ## Privacy and security For many organizations, data privacy, security, and personally identifying information (PII) are critical factors when setting up data collection. Business needs, the purpose of your digital products, and compliance requirements between jurisdictions may vary. There's no one-size-fits-all solution that works in every situation. Autocapture provides flexible configuration options to help you adhere to your company's privacy and security policies and requirements. While ensuring your use of Amplitude complies with your data privacy policies and requirements is your responsibility, these settings help you reach compliance. ### Default Autocapture protections You control what information Autocapture collects and sends to the Amplitude platform. To update the events that Autocapture sends to Amplitude, refer to [Browser SDK | Disable Autocapture](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#disable-autocapture). The following list describes Autocapture's default settings for capturing clicks and changes on page elements ("Element Clicked" and "Element Changed" events). The list also includes the following privacy and security considerations. You don't need to do anything to turn these protections on. They're always active. - For sensitive elements such as end user text inputs, selects, text area elements, and any HTML elements with `contenteditable="true"` as an attribute, the SDK only collects class names and the type attribute. Autocapture excludes any end user-inputted text. - Autocapture's default settings further restrict collection of sensitive input fields, such as passwords or form fields with the hidden attribute, and only capture class and type attribute values. Autocapture doesn't capture other details about these elements, including any content an end user populates in the input fields. - Autocapture captures the text your website or app displays. For example, the content (`textContent`) of the element clicked and its children. Amplitude doesn't recommend using Autocapture's element interaction tracking on pages that may contain sensitive information. Amplitude uses pattern matching to automatically mask any text content that looks like a credit card number, social security number, or email address. - The exception to these attribute collection rules is when an element has an explicit attribute added with the prefix `data-amp-track-`. This exception lets data in these attributes pass back to Amplitude intentionally. - Autocapture automatically removes value, event handlers, style, and react attributes. - Mask page titles in page view events by adding the `data-amp-mask` attribute to the `` element. This replaces the actual title with a masked value to protect sensitive information. For implementation details, refer to [Browser SDK page title masking](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#page-title-masking). ### Manual Autocapture protections Amplitude offers the following Autocapture protections if you choose to implement them. By default, Amplitude doesn't enable them. You can enable all or some of the protections listed below. For some of these protections, you must add an attribute to your elements. You enable some of these protections through the _Data Settings > Autocapture_ page. The documentation for each protection indicates how to enable it. #### Precise text masking Precise text masking redacts text capture from specific elements on the page. This attribute tracks clicks while redacting the text displayed in those elements. To mask an element's text, add the attribute `data-amp-mask` to it. For example, if you have the following on a button: ```html <div data-amp-mask>John Doe</div> ``` Autocapture still tracks the click on the div element. However, the text content "John Doe" appears as `*****` in the Autocapture data. This exclusion works at the SDK level. Precise text masking works recursively, so Autocapture masks any text contained in an element. For example: ```html <div data-amp-mask> John Doe <div>Jane Doe</div> </div> ``` In this example, Autocapture masks both names with `*****`. #### Precise attribute masking Precise attribute masking redacts specific HTML attributes from capture. When you define which attributes to mask, Autocapture tracks clicks while redacting those attributes in your HTML. Specifying attributes on an element masks that attribute on all child elements as well. For example, if you include the following attribute: ```html <div data-amp-mask-attributes="name"> <span name="John D">Account</span> </div> ``` on a button or link, Autocapture masks the name "John D" with `*****`. You can also use a list to specify more than one attribute to mask. When using a list, format the masking attributes as `data-amp-mask-attributes="name,ssn"`. > **Note:** > > You can't mask information from ID and Class attributes because of their importance for [visual labeling](https://amplitude.com/docs/data/visual-labeling). #### Pattern (RegEx) masking You can mask information based on patterns you specify (regular expressions or RegEx). If you aren't familiar with RegEx, review this page on [regular expressions](https://www.regular-expressions.info/quickstart.html). Specify a pattern of information for Autocapture to mask. This configuration occurs in the [SDK](https://amplitude.com/docs/sdks) and provides an additional layer of protection to the default patterns Amplitude uses to mask email, credit cards, and social security numbers. RegEx filters mask values in any fields where this data may appear, including both visible fields and hidden attributes on the page. For example, you can set a RegEx pattern to filter out credit card numbers such as `****-**** **** 1234`. In this example, you want to fully mask the credit card information, including the final four digits. Add the RegEx filter `/(?i)ends\s*in\s*[0-9]{4}/`. If Amplitude finds credit card information that matches the pattern, Autocapture masks those numbers as `*****`. Enable this through the _Data Settings > Autocapture > Element Interactions_ page. #### Page URL exclude and allow lists Use page URL exclude and allow lists to specify unique URL patterns to exclude from or include in Autocapture. Use these capabilities if your organization requires stronger restrictions or safeguards, or if your website or app may contain pages with highly sensitive data such as those in financial services, healthcare, and medical technologies. For example, you can exclude user activity from specific sub-domains on your URL, such as your user's account settings or URLs that only include testing data. If you host your site on multiple domains such as `.com` and `.co.uk`, specify that you only want to include data from the `.co.uk` domain. ##### Examples Using the example of `.com` and `.co.uk` above, here are examples of the exclude and allow lists: ###### Exclude list - Add `https://example.co.uk/account/*` as a glob pattern to the exclude list. This pattern captures everything on the `.co.uk` domain except for the account section. ###### Allow list - Add `https://example.co.uk/*` as a glob pattern to the allow list. Amplitude only captures data from the `.co.uk` domain. Amplitude doesn't capture data from the `.com` domain. > **Note:** > > The exclude list always takes priority over the allow list. This priority prevents you from capturing data that you don't want. If you include the same pattern in both the exclude and allow lists, Autocapture excludes that pattern. Enable this through the _Data Settings > Autocapture > Element Interactions_ page. #### Limit click tracking To support visual labeling, Autocapture captures interaction information about the elements clicked or changed and information about the element's parents in the HTML structure. Depending on your site's structure, you can: - Refine the elements allowed for click and change tracking. Configure the `cssSelectorAllowlist` and `actionClickAllowlist` options to change the list of elements that Autocapture can track. You can remove all common HTML elements and restrict to elements with a specific class. Enable this through the _Data Settings > Autocapture > Element Interactions_ page. #### Turn off Autocapture events You can turn off Autocapture entirely and use precision tracking for data collection. Amplitude includes robust data management tools and workflows that support planning and implementing a custom taxonomy. [Turn off any or all Autocapture events](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#disable-autocapture) through your SDK configuration. ================================================================================ # Plan your taxonomy URL: https://amplitude.com/docs/data/data-planning-playbook Updated: 2026-09-09 ================================================================================ # Plan your taxonomy A taxonomy defines which events and properties you track, what you name them, and how they fit together. A solid taxonomy keeps analyses consistent, prevents data gaps, and avoids costly schema rework later. Build one in three steps: define your business objectives, break down key metrics, then optimize the resulting events and properties. Use this playbook when you're designing a tracking plan by hand or auditing an existing one. ## What is a taxonomy A taxonomy is a set of hierarchical classifications and naming conventions for your data. A taxonomy identifies and categorizes your event and user data so that Amplitude can generate relevant and valuable insights. The process of setting up a taxonomy in Amplitude differs from organization to organization, but the core steps are selecting the events you want to track, identifying event properties and user properties to track, and naming them. ## Users, events, and properties Amplitude's analyses use a combination of events and properties attached to your users. ### Users A user represents a unique individual taking an action or engaging in an activity related to your application. Amplitude uses multiple methods to identify and reconcile your users across various devices. To learn how Amplitude tracks unique users, including how to reconcile anonymous users before login, refer to [tracking unique users](https://amplitude.com/docs/data/sources/instrument-track-unique-users). ### Events An event is a distinct action or activity a user takes within your product. Events can be active when a user interacts with your app (for example, starting a game or adding to their cart), or inactive (the user receives a push notification). When naming events, Amplitude recommends establishing a consistent naming convention that uses: - **Consistent capitalization**: Amplitude captures `Song Played` and `song played` as two separate events. This naming convention helps prevent messy data, especially when multiple teams send the same event. - **A consistent syntax**: `Song Played` and `Played Song` are also separate events. For example, a standard of `[Noun]` + `[Past-Tense Verb]` ensures all your events stay consistent. - **A consistent actor**: Does `Message Sent` mean that the user sent a message, or that you sent a message to the user? If all your events use the user's perspective, the meaning is clear immediately. Default events use Title Case from the user's perspective, with `[Noun]` + `[Past Tense Verb]`. You can also establish your own convention as long as you stay consistent. ### Properties Properties are attributes that help define details around your events and users: - Event properties are attributes that describe details specific to a particular instance of an event. For example, if you have a `Purchase Completed` event, you can specify what the user purchased, the total value of the order, and the payment method used. - User properties are traits that describe the user and apply across all the user's future events until you change them. Amplitude's SDK captures several user properties by default, and you can also set up your own properties to track. Learn more about the differences between [events and user properties](https://amplitude.com/docs/data/user-properties-and-events). As with events, establish a naming convention with consistent casing. ## Step 1: Define your business objectives Starting with your goals and metrics helps ensure you've prioritized the most important ones for your implementation. For example: - What are you and your team working toward? - What metric are you trying to optimize? - What questions do you want to answer with data? Some typical goals Amplitude customers pursue include: - Improving acquisition ROI. - Finding the "aha" moment in the product. - Optimizing conversion. - Increasing user retention and LTV. After you identify your organization's overarching goals, it's easier to break them down into individual metrics and ensure your tracking plan measures the outcome you want. For example, suppose you have an e-commerce app and want to increase purchases. You can do this by: - Increasing the conversion rate of users through your purchase flow. - Increasing the number of users who make multiple purchases. - Increasing the number of users coming to your app. Each of these can be an input metric to achieve your goal. Prioritize these input metrics so you can answer the most important question first. Consider an iterative approach, where you plan and instrument your most important metrics, then iterate later to add more. ## Step 2: Break down your key metrics After you know your ultimate goal and have hypotheses about how to accomplish that goal, break down those input metrics further. What critical paths do your users take, and how do they involve each of those metrics? What actions are essential to each of those paths? Suppose you start with increasing the conversion rate of users through your purchase flow. What are users' critical interactions with your application through the purchase flow? They could be: - **Search completed**: The user searched for an item to purchase. - **Product details viewed**: The user viewed the details of an item. - **Product added**: The user added an item to their order to purchase. - **Order reviewed**: The user viewed the items in their order before purchase. - **Order completed**: The user made a purchase and completed their order. For each of these, think about the various factors involved in each step. For example: - When using search, what term did the user search for? - When the user viewed an item, what was the `Product ID` for the item purchased? One helpful technique is to think about the objects involved with each action and include attributes of those actions in each event. For example, an item in your system likely has an ID, a category, and a price, all properties you can add to events related to your items. ## Step 3: Optimize your events and properties It's time for final optimizations on your plan. Ask yourself these questions. ### Do you have multiple events for similar actions Suppose you have two user actions you can capture as two separate events, or as a single event with a property distinguishing the two distinct cases. For example, suppose you believe payment method is a critical factor. Should you instrument: - `Order Completed` as a single event with a `Payment Method` property that captures `Credit Card` or `Apple Pay`, or - Separate events for `Credit Card Order Completed` and `Apple Pay Order Completed`? Consider these factors: - Start with your key metrics. In this case, while the purchase method is important, the key metric is the purchase flow conversion. A single `Order Completed` event is easier to include in a funnel to view the overall purchase flow conversion. - Is the event scalable? In this example, what happens when you introduce PayPal as a new payment method? Any chart measuring overall conversion would need an update. You'd also be using three events for an interaction where one is enough. - Do you want to identify these separately in [Journeys](https://amplitude.com/docs/analytics/charts/journeys/journeys-understand-paths)? If so, a single `Order Completed` event is probably fine. If you made all your events `Page Clicked` instead, a series of these generic events is unlikely to help when looking at a user flow. ### Are your property definitions consistent across your events Even though event properties are specific to each event, define them consistently across your taxonomy. For example, instead of having a property called `Type` that could represent the type of an item in one event and a type of payment in another, consider separate properties: `Item Type` and `Payment Type`. ### Are your properties captured across all applicable events One typical use case for event properties is tracking values that must hold constant to count toward funnel conversion. For example, suppose you want to know how often users add to cart after viewing details: - Step 1: `Product Details Viewed` - Step 2: `Product Added` Here, users should count as having converted through the funnel only if they triggered the event on the same product. To ensure this, instrument the event property `Product ID` and require the funnel to hold this value constant. Every event in the funnel must have that property for the holding constant feature to work. - Step 1: `Product Details Viewed` - `Product ID` = `3345` - Step 2: `Product Added` - `Product ID` = `3345` - `quantity` = `1` In this example, you can understand how often a user adds to their cart after viewing an item. Without the `Product ID`, you'd be analyzing how often a user adds any item to their cart after viewing any item. ## Next steps Refer to the steps in this playbook as you add new features or iterate on your product analytics. Amplitude Data provides ways to create and iterate on your plan directly in the product, or by importing a CSV file. For more specific examples, go to the following industry-specific best practices guides for sample use cases, business questions, taxonomy recommendations, and complementary dashboards. Each guide addresses the specific needs of these sectors: - [E-commerce](https://analytics.amplitude.com/share/8f32b20708e743e597b75c99b7a766d5). - [Fintech](https://analytics.amplitude.com/share/cbb3827995aa4d03852a3cdf9a3c46b0). - [Publications](https://analytics.amplitude.com/share/5940753342e04394bd0379cdd952cc18). - [Streaming Media](https://analytics.amplitude.com/share/6f40a915c14144b8ac992a5a8d7cf7cb). - [B2B](https://analytics.amplitude.com/share/0f7a78fadfc145d0b99e365eb41d9262). - [Healthcare](https://app.amplitude.com/analytics/share/6e938acce69d459bbb81561b2f942079). ================================================================================ # Destination event streaming overview URL: https://amplitude.com/docs/data/destination-event-streaming-overview Updated: 2026-09-22 ================================================================================ # Destination event streaming overview Event streaming sends your Amplitude event data in real time to downstream marketing, sales, and infrastructure tools, with filtering to control what each destination receives and monitoring to track delivery. Use this behavioral data to enhance customer profiles in those tools. With event streaming, you get configuration-based tools that offer precise control over the data you send. Filter data by user, group, and event properties to send only relevant information to your downstream tools. You can also monitor key metrics like event volume, latency, and detailed delivery status to assess the performance and reliability of your streaming integration. ## Plan availability Real-Time Streaming is available on all plans. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details. | Plan | Allowance | How to access | | --- | --- | --- | | Free | 1M/month events & user property updates | Included in plan | | Plus | 1M/month events & user property updates | Included in plan | | Growth | 1M/month events & user property updates | Included in plan. Add-on for Custom. | | Enterprise | 1M/month events & user property updates | Included in plan. Add-on for Custom. | _Availability reflects the latest Amplitude plans. If your organization is on an older plan, your access may differ. Check your plan under [Plans & Billing in your organization settings](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._ ## Warehouse and batch event streaming Amplitude streams events from both real-time and warehouse or batch sources to your configured destinations. Events imported from your data warehouse or batch sources (such as warehouse imports, Cargo syncs, or file-based ingestion) are eligible for outbound event streaming. After Amplitude ingests these events, Amplitude streams them to your configured destinations alongside real-time events. For your destination, you can expect: - **Complete event coverage**: Your downstream systems receive events from all sources, not just real-time ingestion. - **No additional configuration**: Warehouse and batch events stream to your existing destinations automatically. - **Same delivery guarantees**: Warehouse and batch events follow the same retry and latency targets as real-time events. ## Debug event streaming with Live Log Live Log gives you a real-time, sampled view of events as Amplitude processes them for an Event Streaming sync. Use it to confirm the right events flow through a sync, inspect how Amplitude transforms payloads, and review destination responses. To open Live Log, follow these steps: 1. Navigate to _Data > Destinations_. 2. Select an Event Streaming sync. 3. Select the **Live Log** tab. For each event, Live Log shows three stages side by side: - **Input**: The raw Amplitude event. - **Dispatched**: The transformed payload Amplitude sends to the destination. - **Response**: The status code and body the destination returns. Use the stream controls to pause or resume the feed, clear loaded events, and filter by status (**All**, **Success**, **Destination errors**, or **Processing errors**). Search across loaded events, or filter the stream to events where a specific field in the **Input**, **Dispatched**, or **Response** stage matches a value. Live Log provides a sampled, real-time view for debugging. Amplitude doesn't store Live Log data, so you can't use it for historical analysis. For retry and delivery status monitoring, use the **Debugger** tab on the same sync. ## Automatic destination disabling Amplitude automatically disables an Event Streaming destination when its delivery rate drops to 5% or below over three consecutive UTC calendar days. A disabled destination stops sending events until you re-enable it. Amplitude computes the delivery rate as `eventsDelivered / (eventsDelivered + eventsNotDelivered)`: - **Delivered**: Events that succeed on the first attempt or after a retry. - **Not delivered**: Events that expire or that Amplitude discards, including events with a missing `gclid`, incompatible events, and other non-retryable failures. A delivery rate strictly above 5% keeps the destination enabled. A rate at or below 5% triggers the auto-disable. ### Check schedule Amplitude runs the auto-disable check once per day between 19:00 and 20:00 UTC. Each check scores the previous 3 full UTC calendar days separately. To trigger a disable, all three days must have streaming traffic and all three must show a delivery rate at or below 5%. If any of the three lookback days has zero streamed events, Amplitude skips the auto-disable for that check. ### Scope Auto-disable applies to all Event Streaming destinations on the broadcast and connector pipeline, including Google Ads, webhooks, and Braze. It doesn't apply to cohort syncs, which have a separate auto-disable mechanism. ### Notification When Amplitude disables a destination, it emails the users associated with the sync's created-by and last-updated-by fields. The subject line is `[Amplitude] Event Streaming Pipeline named '{name}' was disabled due to the repeated issues` and the email includes a View Destinations button. Amplitude doesn't show an in-app banner. ### Recovery You can re-enable the destination from the UI at any time. There's no cooldown and no required configuration change before re-enabling. Keep in mind: - If you re-enable during the 19:00–20:00 UTC check window and the previous 3 UTC calendar days still show a delivery rate at or below 5%, the auto-disable job can disable the destination again immediately. - If you re-enable after 20:00 UTC, the destination stays enabled until the next day's 19:00 UTC check. - Fixing your destination configuration today doesn't change yesterday's delivery rate. The destination can keep disabling until three consecutive UTC calendar days show a rate above 5%. ## Considerations - **Billing efficiency:** Amplitude tracks event volume based on distinct events sent. If you send the same event to multiple event streaming destinations, Amplitude counts it only once for billing. - **What counts toward Event Streaming Usage:** Only near real-time streaming destinations count toward your Event Streaming Usage. This includes destinations such as Amazon Kinesis Data Stream and Amazon Kinesis Firehose, even though Amplitude groups them under the **Warehouse Destination** section in the UI. Scheduled batch export destinations such as Amazon S3, Google Cloud Storage, Google BigQuery, Snowflake, and Amazon Redshift export data on a recurring schedule, so they don't count toward Event Streaming Usage. - **Identify events count toward limits:** When you enable the **Send Users** option in your event streaming destination, Amplitude triggers an `Identify` event each time a selected user property changes. Amplitude sends these `Identify` events to your event streaming destinations, and they count toward your event streaming volume limit. Monitor your `Identify` event volume to avoid exceeding your contracted limits, especially if you have frequently updated user properties. - **Latency target:** Amplitude aims for an end-to-end p95 latency of 60 seconds, monitored and supported by alerts. - **Retry mechanism:** Amplitude addresses intermittent errors using in-memory retries with exponential backoff for initial sends. The retry pipeline attempts up to 10 times within a 4-hour window. This mechanism applies to all event streaming destinations. - **Monitoring and management:** Use the **Live Log** tab on an Event Streaming sync to inspect events in real time as Amplitude processes them. The **Debugger** tab lets you monitor pending retries, progress, and expired payloads. Analyze failed payload samples to gain insight into error categories. ## Limitations - **Format for user properties:** Amplitude sends all forwarded user properties as strings except for [Braze streaming](https://amplitude.com/docs/data/destination-catalog/braze) and [Iterable streaming](https://amplitude.com/docs/data/destination-catalog/iterable) destinations. - **Reserved keywords:** You can't use specific keywords, including `_all` and `_identify`, as event names when streaming events from Amplitude. - **Historical data:** Amplitude streams events ingested after you configure a destination. Amplitude doesn't retroactively send events ingested before you set up the streaming destination. Warehouse and batch events ingested after configuration stream alongside real-time events. - **Unsupported Amplitude properties:** Ingestion and streaming pipelines handle some Amplitude properties differently. If so, streaming might not support them. Properties handled differently are `Version` and `Device Family`. ## FAQs ### What's the difference between cohort syncing and event streaming? - **Cohort syncing:** Cohort syncing automatically maintains lists of user IDs based on specific criteria or behaviors. This feature transfers a list of user IDs from Amplitude to third-party tools like SFMC or Braze. Cohort syncing lets you explore behavioral targeting and analyze the impact of your targeting strategies in downstream destinations. Cohort syncing simplifies the management and updating of these lists, supporting actions based on user behavior without manual effort. - **Event streaming:** Event streaming offers more than cohort syncing. Event streaming simplifies your data setup by letting you use a single Amplitude configuration to send data to various platforms, removing the need for constant technical adjustments. With event streaming, you have precise control, choosing which events, users, or properties to send to each platform so only important data reaches its destination. Event streaming also supports real-time conversion events, triggering actions in tools like Braze, Customer.io, or SFMC to optimize your targeting and improve the effectiveness of your initiatives. ### What are some examples of how customers use event streaming? 1. **Marco Polo:** Used event streaming to power a real-time 'Welcome' email campaign by streaming sign-up events from Amplitude to Braze. 2. **Invoice Simple:** Used event streaming for a robust engagement campaign, customizing messaging based on a series of events to improve engagement effectiveness. ### What happens if I don't see an event streaming destination on Amplitude Catalog? 1. **Webhook streaming:** You can use [Webhook Event streaming](https://amplitude.com/docs/data/destination-catalog/webhooks) integration to send your Amplitude events and user data to custom webhooks. This integration sends data to a URL of your choice for various use cases. 2. **Vendor switch:** Consider switching to a vendor already integrated with Amplitude, which offers similar functionalities. Find more information in the [Amplitude Catalog](https://amplitude.com/integrations). 3. **Self-build or vendor request:** You can build the integration yourself using the Amplitude Integration Portal, or request the vendor to create it through the integration portal. Learn more about the [Amplitude Integration Portal](https://amplitude.com/docs/partners/create-an-event-streaming-integration/). ### What happens when multiple events modify the same user property in rapid succession using Send Users? When multiple events that modify the same user property arrive for the same user in rapid succession, two things can happen: 1. **Amplitude coalesces intermediate state changes**: When using the **Send Users** option, if several property-changing events are processed close together, Amplitude forwards only the net result from persisted state to final state. It doesn't forward intermediate values individually. If the final value matches the already-stored value, Amplitude doesn't forward a change at all, even if the property changed in between. 2. **The destination may not retain the original event order**: Depending on how the destination processes near-concurrent updates, forwarded changes may arrive out of order, potentially leaving the destination with a stale value. To avoid unexpected behavior, space out writes to the same user property instead of updating it multiple times in rapid succession. ### What's the IP range of your service? Amplitude data centers use the following IP addresses, depending on their region: - Amplitude US IP addresses - 52.33.3.219 - 35.162.216.242 - 52.27.10.221 - Amplitude EU IP addresses - 3.124.22.25 - 18.157.59.125 - 18.192.47.195 ================================================================================ # Syncs URL: https://amplitude.com/docs/data/destinations/syncs Updated: 2026-09-22 ================================================================================ # Syncs Amplitude supports three types of syncs for cohorts, properties, computations, and predictions: on-demand syncs, automated syncs, and real-time syncs. On-demand syncs are useful for audience testing and one-off campaigns. Automated syncs run on a daily or hourly schedule. As cohort audience membership or user predicted probabilities change, Amplitude automatically adjusts cohort membership in connected destinations. Real-time syncs update each minute and work best for interactive use cases that require rapid updates. You don't need CSV downloads or manual syncs. When users take an action in your app, Amplitude automatically syncs them to the relevant ad, email, or testing platform. ## Plan availability Scheduled Syncs is available on the Growth and Enterprise plans. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details. | Plan | Allowance | How to access | | --- | --- | --- | | Free | Not included | [Upgrade your plan](https://amplitude.com/pricing) | | Plus | Not included | [Upgrade your plan](https://amplitude.com/pricing) | | Growth | Limited 2 syncs | Included in plan. Add-on for Unlimited. | | Enterprise | Limited 2 syncs | Included in plan. Add-on for Unlimited. | One-Time Syncs is available on all plans. _Availability reflects the latest Amplitude plans. If your organization is on an older plan, your access may differ. Check your plan under [Plans & Billing in your organization settings](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._ ## Feature availability - Users on Free, Plus, Growth, and Enterprise plans can use on-demand syncs. - Users on Growth, Enterprise, and Plus plans can use automated syncs. - Users on Growth and Enterprise plans can use real-time syncs. ## Real-time syncs With real-time syncs, Amplitude sends updates to a partner destination almost as soon as a user enters or exits a cohort. This unlocks additional uses for cohort sync, such as timely and contextual messaging to end users. When you create a real-time sync, Amplitude first sends the initial population to the destination. This can take several hours if the sync is large. After this initial sync, Amplitude sends updates every minute as users enter and exit the cohort. Most destinations and cohorts support real-time cohort syncs. When partners fail or reject API requests, or when network delays and errors occur, Amplitude sends any changes once the issue clears. Real-time sync doesn't support select destinations that aren't designed for frequent updates, such as ad destinations and S3, or destinations with strict integration limits that prevent frequent syncing. Real-time sync doesn't support some complex or very large cohorts because of high computation cost. Real-time sync can send cohort membership to destinations, but not computations, properties, or predictions. ## Create a new sync To create a new sync, follow these steps: 1. Click **+ New** and click the **Sync** tile. The _Create New Sync_ modal appears. 2. Select the sync type to create: cohort, recommendation, user property, or computation sync. Then click **Next**. 3. From the drop-down list, select the specific item you want to sync. Then click **Next**. 4. Choose the destination to sync to. If the destination doesn't appear, click **+ Add** or **Manage Destinations** and configure the destination there. Then click **Next**. 5. Choose whether to create an on-demand sync, recurring sync, or real-time sync. Recurring syncs run on an hourly or daily schedule, while real-time syncs update each minute. Depending on your choice in step 4, you may also need to specify a customer account or API target to sync to. 6. Click **Sync**. Your sync is active. ## Email notifications Amplitude automatically sends email alerts for cohort sync jobs: - **Success notifications**: Receive confirmation when your cohort sync completes successfully. - **Failure notifications**: Receive an alert when a sync job fails, so you can address issues quickly. These notifications help you monitor cohort sync status without manually checking the platform. ## View sync details After you create a sync, click the sync name in the _Syncs_ panel to view its details. The _Details_ tab provides basic information about the sync. The example above is a cohort sync, so the _Details_ tab provides a definition of the cohort, as well as a chart detailing its population over time. The _Syncs_ tab shows each destination that receives this sync. On the _Comparisons_ tab, you can view a head-to-head comparison between this synced cohort and another cohort of your choosing. You can break down the results of the User Composition chart by user property using the _Composition by_ drop-down. To view a list of your synced cohorts from within Amplitude Analytics, click **Cohorts** and open the **Synced Cohorts** tab. ## Understanding cohort sync discrepancies When syncing cohorts from Amplitude to a third-party destination, you may notice differences between the user numbers in Amplitude and on the partner's platform. Understanding why these differences occur and how to check which users transferred successfully can help you fix these issues. Amplitude lets you choose any user properties to sync. This aids in customization, but it also requires careful planning to minimize discrepancies during a cohort sync. Common reasons for differences in cohort syncs include: - **Unresolved mapping**: If a user property isn't set, or is `NULL`, Amplitude can't sync the user attached to the property. For example, if you're syncing a cohort of 100 users to a platform using email as the `User_ID`, but only 50 users provided an email, only those 50 users sync. Check and fix your data at the source, update it in Amplitude, and then run another sync. - **Invalid mapped properties**: Properties that don't conform to the expected format in third-party destinations can cause partial or failed syncs. For example, the downstream destination may not accept a particular identifier format, such as email or phone number. > **Note:** > > If a sync is partially successful, Amplitude still marks the entire cohort sync as successful, regardless of whether individual users are valid. ## Warning when updating cohort mapping Amplitude issues a warning if you attempt to modify the Amplitude user property mapping, because modifying the mapping can affect active cohort syncs. Click **View Syncs** to view the syncs that the change could affect. From there, decide if you want to turn off the sync. Even if you don't receive a warning, be careful when modifying mapping properties. Mapping changes can cause unexpected changes in the number of users tracked. For example, if you stop mapping by email addresses and switch to phone numbers, users previously synced with their emails don't receive updates. Your change only affects new users. Amplitude syncs new users based on phone numbers, while previously existing users still sync based on email addresses. Over time, this can lead to data discrepancies. If your cohort sync process has been in place for some time and you're considering changing the mapping, create a new sync destination first. Then proceed with the sync using this new target. ## View sync history The cohort sync history page provides a detailed breakdown of cohort syncs over the last 14 days. Each cohort sync provides a list of skipped, added, or removed users. To access the page, follow these steps: 1. Click the **Cohorts** tab. 2. Choose the specific cohort of interest. 3. Click the **Syncs** tab. 4. If the cohort sync includes multiple destinations, select the appropriate cohort destination. 5. Click the **History** tab. > **Note:** > > The detailed cohort sync history page supports all cohort sync destinations except for [Amazon S3](https://amplitude.com/docs/data/destination-catalog/amazon-s3) and [TradeDesk](https://amplitude.com/docs/data/destination-catalog/thetradedesk). These destinations continuously perform a full sync of users, not just an initial sync followed by incremental changes. This sync behavior makes CSV exports impractical. ## Inspect exported cohorts using CSV export To find out which users and how many users Amplitude exported from your cohort to your third-party destination, export a CSV containing all exported users. The CSV export includes the following columns: - **Amplitude\_id**: Displays the unique Amplitude ID associated with each user. - **Operation**: Indicates whether Amplitude added or removed a user from cohort membership. - **Mapped properties**: This column shows the mapped user identifier for the cohort sync. - **Skip\_detected**: Shows if Amplitude skipped a user during the cohort sync process. - **Skip\_reason**: High-level categorization of why Amplitude skipped a user. - **Unresolved mapping**: Amplitude skipped this user during the cohort sync because the mapped property used to identify the user is missing or has no value. - **Rejected by partner**: The third-party destination rejected this user because the mapped property doesn't adhere to the required format. For example, if data fields aren't in the correct numeric or email format, the destination excludes the user from the cohort sync. Some user properties may be incomplete or out of compliance with the target platform's criteria. A cohort sync success rate over 80% is often acceptable for advertising campaigns. For email campaigns or A/B testing, use a rate above 95%. If there are many skipped entries, there may be a data quality issue at the source. To resolve this issue, review the CSV file to pinpoint discrepancies. Then make appropriate corrections to the user data when you're importing it into Amplitude. After you make corrections, launch the cohort sync process again to confirm the accuracy and consistency of your data. ## Additional considerations - **Real-time cohort sync**: With Amplitude's Real-Time Sync (RTS) feature, the cohort sync history page doesn't allow you to export a CSV for users skipped during the sync. For detailed tracking of skipped users, use hourly or daily syncs instead of real-time syncs. - **Users are silently dropped upon reaching destination**: Some destinations may return a 2XX response to indicate a successful cohort sync from Amplitude, even though the destination silently dropped users who didn't meet its criteria. In these cases, confirm that Amplitude exported a specific user by checking the CSV file. > **Note:** > > Amplitude uses response codes to detect when third-party destinations don't include users. In some cases, Amplitude can't identify these users. If you have questions, post in the [Amplitude community](https://community.amplitude.com/) or contact the [Support team](https://help.amplitude.com/hc/en-us/requests/new) for assistance. ## Supported destinations Refer to the [Destination Catalog](https://amplitude.com/docs/data/destination-catalog). ================================================================================ # Troubleshooting URL: https://amplitude.com/docs/data/troubleshooting Updated: 2026-07-07 ================================================================================ # Troubleshooting When your Amplitude data looks incorrect or incomplete, start here. Pages in this section cover common diagnostic questions about ingestion, instrumentation, and source integrations. ### [Missing or unexpected data](https://amplitude.com/docs/data/troubleshooting/missing-data) Missing events, inflated user counts, and discrepancies with other platforms. ### [Instrumentation and governance](https://amplitude.com/docs/data/troubleshooting/instrumentation-issues) Hiding, blocking, and deleting events; filtering internal users; historical data changes; UI quirks. ### [Integrations and sources](https://amplitude.com/docs/data/troubleshooting/integrations-and-sources) Segment, iOS 14, mobile attribution, and third-party site builders. ## More in this section - [Missing or unexpected data](https://amplitude.com/docs/data/troubleshooting/missing-data). - [Instrumentation and governance](https://amplitude.com/docs/data/troubleshooting/instrumentation-issues). - [Integrations and sources](https://amplitude.com/docs/data/troubleshooting/integrations-and-sources). ================================================================================ # Autocapture Remote Configuration URL: https://amplitude.com/docs/data/autocapture-remote-configuration Updated: 2026-10-08 ================================================================================ # Autocapture Remote Configuration Remote configuration updates your [Autocapture](https://amplitude.com/docs/data/autocapture) settings from the Amplitude UI without a code change or SDK redeploy. It toggles which event types Autocapture tracks, adjusts allowlists and exclude lists for element interactions, and adds extra event properties such as page referrer or page URL across all events. Use Remote Configuration when you want non-engineers to adjust Autocapture without shipping code. If you need the settings hardcoded in the client or want to gate them behind a deploy, configure Autocapture directly in your Browser SDK initialization options instead. > **Note:** > > Autocapture Remote Configuration works with [Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) v2.10.0+ when you enable `fetchRemoteConfig`. Browser SDK v2.16.1 enables Remote Configuration by default. ## Set up remote configuration for Autocapture 1. Go to _Data > Settings > Autocapture_. 2. Specify which elements you want to capture. By default, Amplitude captures all elements. You can capture or not capture any of the following elements: - **File downloads**: Track when a user clicks an anchor or `<a>` tag linked to a file. - **Form Interactions**: Track a user's interaction with the form element. - **Sessions**: Track the period of time that a user has your website open. Amplitude tracks both Start Session and End Session events. - **Page Views**: Track when a user navigates to a page. - **Element Interactions**: Track when users click links, buttons, inputs, and so forth. 3. For Element Interactions, specify the following additional aspects: - **CSS Selector Allowlist**: CSS selectors that specify which elements on the page Amplitude always tracks. - **Action Click Allowlist**: Additional CSS selectors to track when clicked. - **Page URL Allowlist**: Defines one or more URLs or URL patterns on which Amplitude tracks element click and change events. - **Page URL Exclude List**: Defines one or more URLs or URL patterns to exclude from element click and change tracking. Note: Using RegEx or glob patterns requires your SDK version to be 2.23.7 or higher. - **Text Masking RegEx Patterns**: Defines the RegEx patterns to mask for event properties in Autocapture. Note: Using this masking feature requires your SDK version to be 2.23.7 or higher. - **Data Attribute Prefix**: Lets Amplitude capture data attributes as event properties. - **Shadow DOM**: Experimental. Enables element interaction tracking inside open shadow roots and sets the maximum shadow DOM depth. - **Frustration interactions**: Rage clicks or dead clicks that a user performs. Rage clicks are clicks that occur four or more times in a second. Dead clicks are clicks on an interactive element that result in no visible change within three seconds. 4. Click **Save Changes**. ================================================================================ # Visual Labeling URL: https://amplitude.com/docs/data/visual-labeling Updated: 2026-09-09 ================================================================================ # Visual Labeling Visual Labeling creates tracked events from elements you click directly on your site, so non-technical Amplitude users can define events without writing code or understanding the structure of the page. It requires [Autocapture](https://amplitude.com/docs/data/autocapture) on your site. Amplitude maintains labeled events separately from events you've created in other ways. If there are issues with data for labeled events, make adjustments from within the Labeled Events tab, instead of involving your engineering team. ## Prerequisites - [Amplitude Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) 2.10.0 or higher. - The SDK's `config.autocapture.elementInteractions` option set to `true`. For more information, go to the [Browser SDK Configuration](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#configure-the-sdk). > **Note:** > > Visual Labeling is available to Amplitude users with the role Member and above. > **Tip:** Retroactive analysis > > Events you create with visual labeling work retroactively against all Autocapture data. Amplitude applies your labeled event definitions to historical click and form interaction data captured since your instrumentation went live. You can analyze user behavior from the past without waiting for new data to accumulate. ## Create a labeled event with visual labeling To use Visual Labeling to create new labeled events, follow these steps: 1. Open Amplitude Data and click **Visual Labeling**. 2. Click the drop-down menu to select the URL you want or add a new URL. 3. Click **Start Labeling**. Amplitude opens your website or app in a new tab, with the visual labeling toolbar at the top of the page. 4. Click an element you want to label. The visual labeling overlay appears. 5. In the visual labeling overlay, enter a name, description, and category for your labeled event. Select if tracking should happen when a user clicks the element, or when it changes. Visual labeling uses the `clicked` event by default. Refine the definition and select filters as needed. 6. Click **Save**. If Amplitude detects an existing event with the same or a similar definition, a warning appears before the event saves. Refer to [Avoid event duplication](#avoid-event-duplication) for details. Amplitude saves the labeled event and displays a confirmation with an option to view the labeled event. 7. Repeat for each event you want to label. 8. You can select another element to continue labeling or click "Back to Amplitude" if you're done. 9. (Optional) Click **Navigate** to go to a different part of the site to label more elements on different pages. When you finish, return to Amplitude where you can manually update the tag, text, selector, and page URL of each labeled event. > **Note:** > > If you leave any fields blank, Amplitude interprets that as `[any value]`. For example, if you leave the URL field blank, the tracking for that event fires on any page. ### AI-generated CSS selector Amplitude uses AI to recommend precise CSS selectors for elements on your web page during the visual labeling process. When you click an element to label it, Amplitude automatically suggests a selector that may best capture the intended target. AI-generated CSS selectors appear on individual elements (such as a button) and on groups of elements (such as a list or product tiles). The AI pre-fills the **Name** and **Description** fields using contextual understanding of the selected element. You can modify the AI-generated input for these fields at any time. ### Avoid event duplication When you save a labeled event, Amplitude checks for two types of overlap with existing events and surfaces a warning before you finalize the event: - **Same definition**: Another labeled event already captures the exact same page element and interaction. Amplitude surfaces the `This labeled event already exists` warning. Click **View** to open the existing event and decide whether to use it instead of creating a new one. - **Similar page elements**: Another labeled event matches similar page elements, even if the definitions aren't identical. Amplitude surfaces the `Event has a similar definition` warning. Click **View** to compare your new event to the existing events. Amplitude highlights the elements on screen that define each event so you can tell them apart. Reviewing these warnings before saving helps you avoid duplicate coverage across your tracking plan and keeps your event taxonomy clean. If an existing event covers the same interaction, use it rather than creating a new one. > **Note:** > > Visual Labeling prevents saving events with duplicate names or identical definitions. You must resolve a `This labeled event already exists` warning before you can save. ## Edit a labeled event When your site's code changes, you need to update the definition of your labeled events to match. Because Autocapture consistently captures the raw click events, you can update the definition of your labeled events and fix any gaps in your data. To edit your labeled events, follow these steps: 1. Open Amplitude Data and click **Events**, then select the **Labeled Events** tab. 2. Select the labeled event you want to edit. In the flyout tab, click **Edit**. 3. If your event is no longer collecting data because of a site change, add another condition at the bottom by clicking **Select action...**. 4. Add a new condition based on your new site structure. ### Repair a labeled event Sometimes, changes to your site's DOM break Visual Labeling's reference to the specific element on your site. You also need to repair a labeled event when an element moves to a different location or its structure changes. Visual Labeling's repair flow preserves your event history by adding a new `OR` statement with a secondary definition, rather than replacing the original definition. All historical data remains intact while the event begins tracking the new element as well. To repair a labeled event: 1. Open Amplitude Data and click **Events** in the left rail, then in the main section, click the **Labeled Events** tab. 2. Select a labeled event. In the flyout tab, you can interact with: - A chart that depicts the number of times Amplitude saw the event over the last 30 days. - Charts for each definition you've added to the labeled event. 3. To repair an event that doesn't have event volume, click **Repair**. This opens the Visual Labeling flow with the context of the selected event. 4. Select a new element on the page to update the labeled event's definition. The repair process adds this as an additional OR condition to your existing definition, keeping all historical data. 5. Click **Save** to exit the Visual Labeler and apply the updated definition. ### Find misconfigured events Amplitude provides information to indicate if a labeled event isn't working as it should. Go to _Data > Events_, and open the Labeled Events tab. The _Recency_ column shows the last time Amplitude tracked each event. Events that weren't seen recently may show an issue with the event definition. ## Labeled events and event volume When you enable Autocapture, Amplitude begins tracking click and page change events on your site. These events count toward your total event volume. Labeled events act like a virtual layer on top of these events, and help define a specific type of click and use that click in an analysis. Labeled events don't impact event volume beyond Autocapture. For example, a well-instrumented site may record 10,000 events each day, and Autocapture may add as many as 2,000 events each day. The site could experience a 20% increase in daily events. A less-instrumented site may only record 1,000 instrumented events each day. The plugin adding another 2,000 events counts as a 200% increase. In both cases, the increase in daily events comes from tracking click and page change events. Labeled events don't impact the event count. ## Limitations - **Event streams**: Labeled events aren't available in live events, or in the event stream in user lookup and Session Replay. The raw `Element clicked` and `Element changed` events are visible instead. - **Google Chrome extension**: The Amplitude Event Explorer Chrome extension only displays raw events from the browser, so labeled events don't appear. - **Destination event streaming**: You can't send labeled events to destinations with [event streaming](https://amplitude.com/docs/data/destination-event-streaming-overview). You can use your labeled events to define cohorts and then use cohort syncing to integrate with [other destinations](https://amplitude.com/docs/data/destination-catalog). - **Content Security Policy (CSP)**: Amplitude requires cross-tab communication between your site and Amplitude. Visual Labeling requires `cross-origin-opener-policy` to be `unsafe-none` or unset. ## Troubleshooting ### I don't see the visual labeling experience on my site If the visual labeling tools don't appear on your site, check the following: - If you have pop-up or adblocking tools enabled, they can interfere with the Visual Labeling experience. Disable the adblocker and retry. - If the URL you entered redirects to another URL, the visual labeling experience may not load. For security reasons, the domain of the page you're labeling must match the domain you entered in Amplitude. Try using the final URL after any redirects complete. - Ensure `Cross-Origin-Opener-Policy` is set to `unsafe-none` or unset. ================================================================================ # Debug with the Amplitude Chrome extension URL: https://amplitude.com/docs/data/chrome-extension-debug Updated: 2026-09-09 ================================================================================ # Debug with the Amplitude Chrome extension The Amplitude Event Explorer Chrome extension captures every Amplitude event your browser JS SDK fires and displays each event's payload in a popup as you interact with your product. It also surfaces Guides and Surveys trigger state and Web Experiment exposure so you can debug why a guide, survey, or experiment doesn't behave as expected. Install it from the [Chrome Web Store](https://chrome.google.com/webstore/detail/amplitude-instrumentation/acehfjhnmhbmgkedjmjlobpgdicnhkbp). Use the extension when you need to inspect events at the moment they fire in the browser, with their raw event and user properties. To review events after they arrive in Amplitude and search across users and sessions, use [User Look-up](https://amplitude.com/docs/analytics/user-data-lookup) instead. > **Note:** > > The Event Explorer displays the `event_type`, even when it has a different display name. ## View triggered events In the Event Explorer, the _Events_ tab contains detailed insights into the parameters of each event you trigger on your website. These parameters include `user_id`, `device_id`, `event_properties`, and `user_properties`. To switch between the different Amplitude projects receiving your events, select the project from the **Project** dropdown. An abbreviated API key distinguishes each Amplitude project. To clear all the events from your popup, select **Clear Events**. To hide specific event types, select the **Invisible** icon. To copy your events' event and user property parameters, select the **Copy** icons. ## View configuration options To view the [configuration options](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#configure-the-sdk) you've set for each project's SDK, select the **API Options** tab. ## View hidden events To see a list of your hidden events or to display events on the webpage as they trigger, select the **Settings** tab. ## Guides & Surveys The extension includes tools to help you debug Guides & Surveys. Use these features to verify SDK setup, troubleshoot why guides or surveys don't show, and test event-based triggers. > **Tip:** > > The _Guides & Surveys_ tab doesn't update live. Wait for the page to finish loading before you review its information. ### SDK setup Verify the Guides & Surveys SDK runs correctly on the page before troubleshooting specific guides or surveys. The SDK setup section shows the status of four steps: - **Installed**: You've installed the SDK on the page. - **Initialized**: You've initialized the SDK with your configuration. - **Analytics Connected**: The SDK connects to at least one analytics SDK. - **Booted**: The SDK received user info and is ready to display guides and surveys based on triggers. If all checks pass but guides or surveys still don't work, verify these settings: - **Configuration**: Use **Show config** to verify the API key matches the project where you published your guide or survey. - **User identification**: Use **Show user info** to verify the `user_id` matches the expected user. - **SDK installation**: You might have installed the Guides & Surveys SDK on some pages but not others. Verify you've installed it on all pages where you plan to set up a guide or survey. - **Boot step**: The boot step might be conditional on certain environments or user types. Make sure your code always calls it regardless of environment or user type. ### Troubleshoot Guides & Surveys The troubleshooting section shows all published guides and surveys for the associated project's API key. Each guide or survey displays its trigger conditions and whether those conditions pass. Open a preview of any guide or survey to see the Preview toolbar and debug individual steps. The preview helps you test the guide's behavior and identify issues with specific steps. The expanded section also shows why a guide or survey may not show without opening a preview. Check the trigger conditions to see which requirements aren't met: - **Should show if triggered**: Whether the guide would show if all trigger conditions passed. - **Trigger conditions**: Built-in throttles, custom throttles, limits, page targeting, snooze settings, and user targeting. ### Forwarded events View all events that the Guides & Surveys SDK sees client-side. The SDK only sees client-side events and doesn't have access to server-side events. Use the Forwarded Events section to: - View events the SDK has received. - Simulate test events to trigger guides that depend on specific events. To test an event-based trigger, enter the event name in the input field and select **Test Event**. The event appears in the logged events list with its timestamp and full event payload. ## Web Experiments The extension shows granular targeting details for active [Web Experiments](https://amplitude.com/docs/web-experiment) so you can diagnose why an experiment isn't firing. When an experiment runs on the page, the extension displays a _Debugging Details_ panel with an overall exposure badge that shows _Exposed_ or _Not Exposed_ at a glance. > **Note:** > > Update to the latest version of the extension to see Web Experiment debugging details. ### Audience targeting The _Audience Targeting_ section shows which segment matched and which variant the experiment assigns to the current user. Use it to confirm the user falls into the segment you expect. ### Page targeting The _Page Targeting_ section shows the configured page view rule, whether the current URL matches that rule, and the trigger status. Check this section first when an experiment doesn't fire, since URL mismatches and trigger misconfiguration cause most issues. ### Preview a variant To QA a specific variant without changing the experiment configuration, use **Preview Variant** to override the variant the experiment assigns to the current user. The override applies only to your session, so it doesn't affect other users or the live experiment. ================================================================================ # Self-service data migrations URL: https://amplitude.com/docs/data/self-service-data-migrations Updated: 2026-09-08 ================================================================================ # Self-service data migrations The Migrations panel moves event data between Amplitude projects and organizations you control, or imports event data from Mixpanel or Posthog. Find it under _Data > Migrations_. All plan tiers can use it, including in the EU data center. Use data migrations to consolidate event data across projects, reorganize your Amplitude structure, or bring historical event data from another analytics platform. To remove unwanted data already in Amplitude, use [self-service data deletion](https://amplitude.com/docs/admin/account-management/self-service-data-deletion-in-amplitude) instead. ## Supported sources The Migrations panel supports three migration sources: - **Amplitude**: Move event data between projects or organizations you control. - **Mixpanel**: Import historical event data from a Mixpanel project into Amplitude. - **Posthog**: Import historical event data from a Posthog project into Amplitude. ## Run a data migration To run a data migration: 1. In Amplitude, navigate to _Data > Migrations_. 2. Click **New Migration**. 3. Select the migration source: Amplitude, Mixpanel, or Posthog. 4. Provide the credentials or authentication required for the source. 5. Configure the migration scope, including the time range and the events you want to import. 6. Review the migration summary and click **Start Migration**. Amplitude runs the migration in the background. Return to _Data > Migrations_ to track the status. Migrated events count toward your monthly event volume. ================================================================================ # Data backfill URL: https://amplitude.com/docs/data/data-backfill Updated: 2026-09-09 ================================================================================ # Data backfill A data backfill loads historical events into your project so past user activity appears alongside your current data. You can import historical data to Amplitude using the [Batch Event Upload API](https://amplitude.com/docs/apis/analytics/batch-event-upload). ## Considerations Review these considerations before backfilling data. - Consider keeping historical data in a separate Amplitude project instead of backfilling into a live production project. Keeping historical data separate makes the upload easier and keeps your live Amplitude data clean and focused on current and future data. You typically don't need to check historical data often, but you still want it available. Historical user property values overwrite current live values during a backfill. Amplitude syncs the out-of-date property values onto new live events. To skip user property sync, add the following to your event payload: `"$skip_user_properties_sync": true`. - To connect historical data with current data, combine the historical data and live data in the same project. To connect users from each dataset, the users need matching Amplitude user IDs in each set. - The new user count might change. Amplitude defines a new user based on the earliest event timestamp it sees for a given user. If Amplitude records a user as new on June 1 2021 and you backfill data for the user from February 1 2021, then Amplitude defines the user as new on February 1 2021. - Backfilling can compromise your app data. If a mismatch exists between the current user ID and the backfilled user ID, Amplitude interprets the two distinct User IDs as two distinct users. As a result, Amplitude double-counts users. Because Amplitude can't delete data after it's recorded, you might have to create a new project to prevent data issues. - Amplitude uses the Device ID and User ID fields to compute the Amplitude ID. For more information, refer to [Track unique users](https://amplitude.com/docs/data/sources/instrument-track-unique-users). - Events in the backfill count toward your monthly event volume. ## Limits Keep these limits in mind when backfilling data. - **Daily limit**: An ingestion daily limit of 500K events per device ID (and per user ID) applies to each project to protect Amplitude from event spam. This limit uses a 24-hour rolling window of 1-hour intervals. A user or device can send at most 500K events in the last 24 hours at any given time. If you hit this limit, you get `exceeded_daily_quota_users` or `exceeded_daily_quota_devices` in the response. For more information, refer to [Batch Event Upload](https://amplitude.com/docs/apis/analytics/batch-event-upload#daily-limit). - **Batch limit**: An upload limit applies of 100 batches per second and 1000 events per second. You can batch events into an upload, but Amplitude recommends sending no more than 10 events per batch. Amplitude throttles your upload if you send more than 10 events per second for a single device ID. For more information about throttling, refer to [Batch Event Upload](https://amplitude.com/docs/apis/analytics/batch-event-upload#code-429-explained). To avoid overloading your ingestion workers, Amplitude recommends limiting backfill event upload to 300 events per second per device ID. Backfills can exceed 300 events per second if you iterate through historical data and send data as fast as possible in parallel. ## Backfill best practices - Review the documentation for the [Batch API](https://amplitude.com/docs/apis/analytics/batch-event-upload). If you exported historical data using the Export API and want to use the data to backfill, note that the exported fields aren't in the same format as the fields needed for import. For example, the Export API uses `$insert_id`, while HTTP and Batch APIs use the format `insert_id` without the `$`. - Decide which fields to send and map your historical data to Amplitude fields. Amplitude strongly recommends that you use the `insert_id` field to deduplicate events. - Because no way exists to undo an import, create a test project in Amplitude to send sample data from your backfill. Run several tests with a few days' worth of data in an Amplitude test project before the final upload to the production project. Amplitude recommends this approach for backfilling large amounts of data: 1. Break up the set of events into mini non-overlapping sets (for example, partition by `device_id`). 2. Have one worker per set of events run these steps: 1. Read many events from your system. 2. Partition those events into requests based on `device_id` or `user_id`. 3. Send your requests concurrently or in parallel to Amplitude. To optimize further, add aggressive retry logic with high timeouts. Continue to retry until you receive a 200 response. If you send an `insert_id`, Amplitude deduplicates data that has the same `insert_id` sent within 7 days of each other. ### Skip user properties sync When Amplitude captures an event, it includes the current values for each user property, which can change over time. When Amplitude receives an event with user properties, it updates the existing user properties and adds any new user properties. To change this behavior, add `"$skip_user_properties_sync": true` to the event payload. When you include `"$skip_user_properties_sync": true`, Amplitude ignores the user properties table completely. The event has only the user properties sent with the event, doesn't update the user properties table, and doesn't display any preexisting user properties. > **Example:** > > For example, you send the following event to Amplitude. The user property table already has the user property `"city": "New York"`. > > ```json > { > "api_key": "API_KEY", > "events": [ > { > "user_id": "b4ee5d78-e1b6-11ec-8fea-0242ac120002", > "insert_id": "97b74bc6-a8c8-48f3-bbc7-de9f95aea636", > "device_id": "", > "event_type": "Button Clicked", > "user_properties":{ > "subscriptionStatus":"active" > } > } > ] > } > ``` > > The event appears in Amplitude as: > > ```json > "events": [ > { > "user_id": "b4ee5d78-e1b6-11ec-8fea-0242ac120002", > "insert_id": "97b74bc6-a8c8-48f3-bbc7-de9f95aea636", > "device_id": "", > "event_type": "Button Clicked", > "user_properties":{ > "city":"New York", > "subscriptionStatus":"active" > } > } > ] > ``` > > You include `"$skip_user_properties_sync": true` and send the same event. The event appears in Amplitude like this: > > ```json > "events": [ > { > "user_id": "b4ee5d78-e1b6-11ec-8fea-0242ac120002", > "insert_id": "97b74bc6-a8c8-48f3-bbc7-de9f95aea636", > "device_id": "", > "event_type": "Button Clicked", > "$skip_user_properties_sync": true, > "user_properties":{ > "subscriptionStatus":"active" > } > } > ] > ``` > > The event doesn't include the city property. > > Next, you include `"$skip_user_properties_sync": true` and send this event: > > ```json > { > "api_key": "API_KEY", > "events": [ > { > "user_id": "b4ee5d78-e1b6-11ec-8fea-0242ac120002", > "insert_id": "97b74bc6-a8c8-48f3-bbc7-de9f95aea636", > "device_id": "", > "event_type": "Button Clicked", > "$skip_user_properties_sync": true, > "user_properties":{ > "city":"San Francisco" > } > } > ] > } > ``` > > Amplitude doesn't update the user properties table, and the event appears in Amplitude like this: > > ```json > "events": [ > { > "user_id": "b4ee5d78-e1b6-11ec-8fea-0242ac120002", > "insert_id": "97b74bc6-a8c8-48f3-bbc7-de9f95aea636", > "device_id": "", > "event_type": "Button Clicked", > "user_properties":{ > "city":"San Francisco" > } > } > ] > ``` > > Any new event still has `"city":"New York"`, but this event displays `"city":"San Francisco"`. ### Timing If you send data with a timestamp 30 days or older, it can take up to 48 hours to appear in some parts of Amplitude. Use the [User Activity tab](https://amplitude.com/docs/analytics/user-data-lookup) to check the events you're sending, because that tab updates in real time regardless of the event time. ### Resources - Example scripts for data import: [https://gist.github.com/djih/2a7e7fb2c1d45c8277f7aef64b682ed6](https://gist.github.com/djih/2a7e7fb2c1d45c8277f7aef64b682ed6) - Example data: [https://d24n15hnbwhuhn.cloudfront.net/sample\_data.zip](https://d24n15hnbwhuhn.cloudfront.net/sample_data.zip) ## Data ingestion system In Amplitude's ingestion system, each user's current user properties are tracked and synced to a user's incoming events. ![Diagram of user properties synced to each incoming event in ingestion](https://amplitude.com/docs/images/data/data-user-property-sunc.svg) When sending data to Amplitude, you either send event data or send `identify` calls to update a user's user properties. These `identify` calls update a user's current user property values and affect the user properties attached to events received after the `identify` call. > **Example:** > > The Datamonster user has one user property, 'color', set to 'red'. Datamonster logs a 'View Page A' event and triggers an `identify` that sets 'color' to 'blue'. Afterward, Datamonster logs a 'View Page B' event: > > 1. `logEvent` -> 'View Page A' > 2. `identify` -> 'color':'blue' > 3. `logEvent` -> 'View Page B' > > If Amplitude receives events from Datamonster in that exact order, you'd expect 'View Page A' to have 'color' = 'red' and 'View Page B' to have 'color' = 'blue'. Amplitude maintains the value of user properties at the time of the event. For this reason, the order in which events are uploaded matters. If the `identify` arrives after 'View Page B', then 'View Page B' has 'color' = 'red' instead of 'blue'. Because Amplitude processes all of a user's events using the same ingestion worker, Amplitude guarantees that it processes events in the order it receives them. All Datamonster's events queue in order on a single ingestion worker. If two separate workers processed these events in parallel, ordering would be harder to guarantee. For example, one worker might run faster than another. Because a single ingestion worker processes a user's events, a user sending an abnormally high number of events in a short period can overload that worker. To avoid overloading your ingestion workers, Amplitude recommends limiting event upload to 300 events per second per device ID. Backfills can exceed 300 events per second if you iterate through historical data and send data as fast as possible in parallel. Amplitude tracks each device ID's event rate and rejects events with a 429 throttling HTTP response code if a device ID sends too many events. If you receive a 429 in response to an event upload, the process should sleep for a few seconds and then keep retrying the upload until it succeeds. This approach ensures that events aren't lost in the backfill process. If you don't retry after a 429 response code, Amplitude doesn't ingest that batch of events. ## Backfill preexisting users If you have preexisting users, backfill them to accurately mark when they became new users. Amplitude marks users new based on the timestamp of their earliest event. To backfill your preexisting users, use the [Batch API](https://amplitude.com/docs/apis/analytics/batch-event-upload). Send a placeholder event or a signup event where the event timestamp is the actual time the user was originally created. For example, if a user signed up on Aug 1st, 2022, the timestamp of the event you send should be Aug 1st, 2022. ================================================================================ # Privacy and consent implementation guide URL: https://amplitude.com/docs/data/privacy-and-consent-implementation Updated: 2026-10-13 ================================================================================ # Privacy and consent implementation guide You can set up Amplitude in a privacy-friendly way. The right setup depends on your policy, your region, and how much data you want to collect before consent. Before you choose a method, align with your legal and privacy teams on what's allowed in your case. A good way to think about this: first choose your consent model, then configure storage and access in Amplitude to match it. ## Plan availability CMP Integrations and Track Counts for Non Consent are available on all plans. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details. _Availability reflects the latest Amplitude plans. If your organization is on an older plan, your access may differ. Check your plan under [Plans & Billing in your organization settings](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._ ## Using this guide This guide helps you implement a privacy-conscious analytics setup in Amplitude. It doesn't replace legal advice. Your team decides which consent model, disclosures, and regional requirements apply to your business. This guide shows you practical ways to implement those choices in Amplitude. There's no single setup that fits every company. Some organizations need strict opt-in before analytics starts. Others may use a more limited measurement-only approach in some regions. The right choice depends on your product, your data, and the rules that apply where you operate. Use this guide as a decision and implementation framework: 1. Choose the consent method that fits your policy. 2. Configure Amplitude to match that method. 3. Add the governance, retention, and deletion controls you need. 4. Validate the setup before launch. The guide covers common implementation patterns and the controls most teams need first. For complex use cases, use it as a starting point and identify the decisions to make with your legal, privacy, and security teams. ## Before you start Before you configure anything, answer these three questions: 1. Do you need consent before analytics starts? 2. Do you want to collect no data, or limited anonymous measurement, before consent? 3. Which fields should reach Amplitude at all? You're responsible for obtaining any required consent, making the right disclosures, and deciding how to classify Amplitude cookies in your policy. A practical starting point is to write down: - which events you want to collect. - which identifiers you want to store. - which properties are sensitive. - what should happen when a user declines consent. - what should happen when a user grants consent after an initial decline. That one-page decision document makes the implementation much easier to review and test. > **Note:** How to classify Amplitude cookies in your CMP > > Most organizations classify Amplitude's analytics cookies as analytics or performance cookies, not marketing cookies. If your consent banner separates cookie categories, configure Amplitude under the analytics or performance category in your consent management platform. > > In limited circumstances, such as when Amplitude is used only for feature flagging or for Session Replay in a security or debugging context, the relevant cookies may qualify as "necessary." Your legal team should confirm the correct classification for your specific use case. ## Choose the setup that fits your policy ### Method 1: Ask for consent and collect data only from users who consent This is the clearest option if your policy requires consent before analytics begins. It's also the easiest model to explain to users and auditors because nothing starts until the user grants consent. #### How it works In Browser SDK 2, the SDK may create Amplitude cookies as soon as it initializes. If you need to avoid cookies before consent, don't initialize the SDK until the user has consented. #### How to set it up in Amplitude Only call `amplitude.init()` after consent is captured. Let your site load normally, and hold off on initializing until your consent tool confirms that analytics is allowed. ```javascript import * as amplitude from '@amplitude/analytics-browser'; // User hasn't consented yet. // Don't initialize the SDK here. function onConsentGranted() { amplitude.init('API_KEY'); } ``` If you need to anonymize a user after logout, call `amplitude.reset()`. This clears the `userId` and creates a new `deviceId`. The next activity appears as a new anonymous user until the user signs in again. #### What to do outside Amplitude Use your CMP to control whether initialization happens. Amplitude doesn't provide a default CMP integration, so your CMP needs to pass the consent outcome into your Amplitude implementation. #### Centralize SDK initialization Make `amplitude.init(...)` run from one place only. If several teams initialize the SDK in different parts of the site, proving that tracking is gated by consent becomes much harder. When you test this setup, open your browser developer tools and confirm that no Amplitude cookies are present before consent. ### Method 2: Ask for consent, but collect limited anonymous measurement from users who don't consent Some organizations want a middle ground: full analytics for users who consent, and very limited measurement for users who don't. This can be appropriate only when your legal team confirms that this kind of limited audience measurement is allowed in your jurisdictions. #### How it works Keep this method limited to anonymous or strongly minimized audience measurement, such as total traffic or page views. Don't let it turn into user-level behavioral analysis. Rules can vary across Europe, so treat local regulatory guidance as part of the implementation decision. France is one well-known example: the [Cookies and consent management guide](https://amplitude.com/docs/sdks/analytics/browser/cookies-and-consent-management) describes the CNIL exemption as a narrow case for anonymous statistical audience measurement without consent, not full analytics. It's a useful reference point, but don't treat it as the default rule for every European market. > **Warning:** CNIL self-certification requirement > > Qualifying for the CNIL exemption requires completing a formal self-certification process with CNIL. If you're pursuing this route, work with your legal team to confirm your setup meets the certification criteria before relying on this exemption. #### How to set it up in Amplitude For the limited anonymous flow, reduce or remove persistent identity: - Set `identityStorage` to `none` if you don't want persistent browser identity. - Set `identityStorage` to `session` if you want to track users within a single session but not across sessions. This is a useful middle ground for some implementations. - Avoid sending a stable `userId`. - Keep the event set small and focused on aggregate traffic measurement. ```javascript amplitude.init('API_KEY', { identityStorage: 'none', }); ``` You can also shorten cookie duration if your policy allows cookies but you want a more conservative setup. #### What to do outside Amplitude Decide exactly which events belong in the anonymous flow. Keep that list short. For most teams, that means page views, traffic totals, and other high-level measurement only. If you need stronger control, [send data through your own proxy before it reaches Amplitude](https://amplitude.com/docs/analytics/domain-proxy). A domain proxy can help you filter, block, or anonymize data before forwarding it. #### Keep the anonymous flow narrow If you choose this method, be disciplined. Don't quietly turn a "limited anonymous measurement" flow into full behavioral analytics over time. The more your anonymous flow starts to look like user analysis, the weaker your privacy position becomes. ## Keep consented and non-consented data in separate projects If you collect both consented analytics data and a limited non-consented measurement stream, always keep them in separate Amplitude projects. Mixing the two into a single project creates problems that are difficult to untangle later. Three reasons to be strict about this from the start: - **Reporting integrity**: non-consented data uses minimized or rotating identifiers, so user-level metrics like uniques, funnels, and cohorts behave very differently from your consented data. Keeping them separate makes it clear which numbers mean what. - **Risk of unintended user stitching**: Amplitude resolves identity at the organization level, not the project level. If the same user ID or device ID appears in both projects, Amplitude treats them as the same user. If your non-consented project wasn't designed with this in mind, you may inadvertently link anonymous data to identified users across projects. - **Access control**: the non-consented project should have tighter controls. Disable individual user-level event lookup so analysis stays at the aggregate level. This is much easier to enforce when the data is already in its own project. ### Configure the non-consented project more strictly [Separate projects](https://amplitude.com/docs/admin/account-management/manage-orgs-projects) let you configure the non-consented stream differently from the start. In practice, that usually means using the stricter setup in the non-consented project: no cookies, no persistent storage, no stable user ID, and a minimal event set. ### How to set it up A common setup looks like this: - one project for consented users, where full analytics begins after consent. - one project for non-consented users, where you only send the limited anonymous measurement events your policy allows. When a visitor hasn't consented, route the allowed events to the non-consented project. If the visitor later gives consent, initialize Amplitude with the consented project and begin normal tracking there. If you use this approach, make sure your identity strategy is intentional in both projects. Across projects in the same organization, Amplitude assumes that the same user ID or device ID refers to the same user. That's useful for legitimate cross-project analysis, but it also means you should be careful not to reuse identifiers across consent states unless that matches your legal and implementation model. ### Restrict user-level access where appropriate For some teams, separating projects isn't enough on its own. They also want the project that contains non-consented data to have tighter access to user-level views. In those cases, review whether features such as [User Lookup](https://amplitude.com/docs/analytics/user-data-lookup), user profiles, user streams, or similar user-level surfaces should remain available for that project. This is especially relevant if the project contains anonymous or non-consented data and your privacy posture is meant to avoid individual-level exploration. As a practical rule, many teams want a stricter setup for the non-consented project and a more standard setup for the consented one. If you need that kind of project-specific restriction, discuss it with your Amplitude team as part of the implementation design so they apply the right controls for your organization. #### Disabling User Lookup at the project level In addition to DAC and RBAC, Amplitude supports disabling the User Lookup feature at the project level. When your Amplitude team enables this setting, team members can't access individual user event streams from contextual menus in charts and dashboards (for example, the microscope icon that opens a user's event stream). This control is especially relevant when your privacy posture requires analysis to happen at the aggregate level only, and you want to prevent access to raw individual-level user events. For example, to comply with CNIL requirements in France, the exemption for analytics without consent applies only to aggregate statistical measurement. Your Amplitude team manages this setting at the project level. To apply it, contact your Amplitude team so they can enable it as part of your project configuration. You can also control broader user-level access using [RBAC](https://amplitude.com/docs/admin/account-management/user-roles-permissions), but the User Lookup control is separate and more targeted, specifically for disabling individual event stream access. ### Use Portfolios to combine top-line reporting If you want to analyze consented and non-consented projects together, use a Portfolio view. [Portfolio](https://amplitude.com/docs/admin/account-management/portfolio) lets you combine multiple projects into one cross-project view so you can build charts across them. This is useful when you want a broader picture of traffic or activity across consent states without collapsing the underlying implementations into one project. A good pattern is to: - keep the data collection separate. - use a Portfolio to report across both projects where that makes sense. - set expectations clearly about what can and can't be combined. For example, top-line event counts may be useful across both projects, while user-level metrics require more caution. If the non-consented project uses minimized identity, don't expect Portfolio reporting to recreate the same kind of user continuity you have in the consented project. #### Document the routing rules If you adopt the separate-projects pattern, document it clearly for both implementers and analysts. Teams should know: - which events go to which project. - when traffic moves from the non-consented project to the consented project. - which identifiers are allowed in each project. - which user-level features should be restricted in the non-consented project. - which charts should use the Portfolio view versus a single source project. This is one of the most practical ways to support privacy-sensitive measurement while keeping your analytics setup understandable and maintainable. > **Note:** When a non-consented user gives consent mid-session > > If a visitor initially arrives without consenting and later grants consent on the same visit, you need to handle the transition explicitly. The recommended approach is: > > 1. Stop sending to the non-consented project. After the user grants consent, stop routing events to the anonymous measurement project. > 2. Initialize Amplitude with the consented project key. Call `amplitude.init()` with your consented project's API key and, if the user is now identified, set their `userId` at this point. > 3. Don't attempt to retroactively link pre-consent activity to the now-identified user, unless your legal model explicitly allows it. The anonymous events from before consent should stay anonymous. > > This ensures a clean boundary: pre-consent activity stays in the anonymous project with no stable identity, and post-consent activity begins fresh in the consented project under the user's real identity. ### Method 3: Don't ask for consent, but reduce identifiers and data collection where your policy allows it In some regions or use cases, your legal team may decide that consent isn't required for your analytics setup. If so, you can still make that setup more privacy-friendly by limiting identifiers, shortening storage, and minimizing what you send. #### How to set it up in Amplitude Choose the storage mode that matches your policy: - `cookie` for standard browser persistence. - `localStorage` if you prefer browser storage without cookies. - `none` if you want no persistent identity. If you use `localStorage`, remember that it's limited by subdomain. A user on one subdomain won't automatically carry the same stored identity to another. If you use `identityStorage: "none"`, Amplitude generates a new `device_id` on every page load (or app start), because there's no stored identity to reuse between loads. > **Note:** > > Amplitude generates a new `device_id` on each page load or app start, not on each individual event. All events fired within the same page load share the same `device_id`. As soon as the user closes the tab or restarts the app, the next page load generates a completely new `device_id` with no link to the previous one. You can't reconstruct cross-session user journeys, which is the intended behavior for strict anonymization. #### What to do outside Amplitude Make sure your privacy notice matches what you're actually doing. If you're not asking for consent, your policy should still explain what you collect, why, and how users can opt out if that applies to your model. #### Minimize data by default Even when consent isn't required, data minimization is still a good default. Collect what you need, not what happens to be available. ## Use a proxy when you want tighter control A [domain proxy](https://amplitude.com/docs/analytics/domain-proxy) is useful when you want more control over what reaches Amplitude. It lets you send tracking requests through your own domain and can help with filtering, blocking, debugging, audit logging, and anonymization before forwarding data to Amplitude. This is especially helpful if you want to remove fields such as IP address, location, or `userId` before data leaves your environment. A proxy isn't the only way to do this. You can also exclude or suppress specific fields directly in the SDK at initialization time, which is easier when you only need to strip a small number of fields client-side. > **Note:** > > You can configure the Amplitude SDK at initialization time to suppress or exclude specific fields before any data leaves the client. For example, you can pass options in `amplitude.init(...)` to prevent IP address or user ID from being transmitted. The SDK config approach is simpler when you only need to strip a small number of fields client-side. A proxy is the better choice when you need centralized control, server-side enforcement, audit logging, or want the filtering to happen outside the client entirely, so that sensitive fields never leave your infrastructure at all. If you build a proxy, involve your developer operations and information security teams early. ## Keep noisy traffic out of your data Privacy settings work better when your data is also clean. ### Block bot traffic If you track public web traffic, bot traffic can distort your metrics. Amplitude lets you create a [block filter](https://amplitude.com/docs/data/block-bot-traffic) so this data is never ingested in the first place. To set it up: 1. Go to your project's `main` branch. 2. Open **Filters**. 3. Open the **Block Filters** tab. 4. Click **Create Block Filter**. 5. Select **Bot Traffic**. 6. Save the filter. Amplitude blocks bots based on the User-Agent, using the IAB/ABC International Spiders and Bots List. ### Block internal traffic If your team tests in production, [block internal IP addresses](https://amplitude.com/docs/data/troubleshooting/instrumentation-issues#block-and-filter-internal-users) so employee traffic doesn't inflate your metrics. In Amplitude Data, create a block filter for **Events** where **IP Address** equals the addresses you want to block. A good practice is to keep a separate development project for testing and only use production for final validation. ## Restrict who can see sensitive data Collecting data responsibly is only half the job. You should also control who can see it. Amplitude's [Data Access Control (DAC)](https://amplitude.com/docs/data/data-access-control) lets you classify properties as _PII_, _revenue_, or _sensitive_, then grant or deny access to those classifications by group. With DAC enabled: - restricted users can't view charts, cohorts, dashboards, notebooks, or user sessions that contain restricted data. - Amplitude hides classified properties from Event Stream and User or Account Lookup. - restricted values appear as `[DAC Restricted]`. To set it up: 1. Ask Amplitude Support to enable DAC for your organization. 2. In _Amplitude Data_, classify the properties you want to protect. 3. In _Settings > Organization settings > Groups_, open the group and configure access on the **Data Access** tab. If you want broader role control beyond sensitive properties, use [RBAC](https://amplitude.com/docs/admin/account-management/user-roles-permissions) to define what users can do in each project and assign those roles through groups. ## Set a retention period If you don't need to keep event data forever, set a retention period. Amplitude's [Time to Live (TTL)](https://amplitude.com/docs/data/time-to-live) lets you define event retention at the organization level and override it per project. To configure it: 1. Ask Amplitude to enable TTL controls for your organization if they aren't already enabled. 2. Go to _Organization Settings_. 3. Open the **Time to Live (TTL)** tab. 4. Choose a retention period and confirm. 5. Add project-level overrides if some projects need a different retention policy. Be careful here. TTL causes irreversible data loss, and existing charts zero out for periods outside the retention window. A good rule is to set a shorter TTL for higher-risk datasets and a longer one only where there's a clear business need. ## Prepare for deletion requests If a user asks you to delete their data, you need a process that covers both Amplitude and any upstream systems. Amplitude's [User Privacy API](https://amplitude.com/docs/apis/analytics/user-privacy) lets you programmatically submit deletion requests for known Amplitude IDs or User IDs. By default, deletions are project-based. If you want to delete the user across your organization, set `delete_from_org` to `true`. Two things matter in practice: - deleting a user doesn't block future tracking for that user. - if the same user data still exists in your warehouse or another ingestion source, Amplitude may ingest it again on the next sync. So your deletion workflow should be: 1. Receive the request. 2. Identify the correct user IDs. 3. Delete the user in Amplitude. 4. Delete the same user from the warehouse or any synced source. 5. Log completion for audit purposes. ## Validate your setup before launch After your setup is live, test it with real scenarios. At minimum, test: - a visitor who hasn't consented. - a visitor who grants consent. - a signed-in user. - a user who logs out. - a user whose data is deleted. In Amplitude, use [User Lookup](https://amplitude.com/docs/analytics/user-data-lookup) to inspect the event stream for a specific user and confirm what data was actually ingested. For each test case, check: - whether the SDK initialized. - whether Amplitude cookies or storage were created. - whether the expected events were sent. - whether the expected identifiers were present. - whether restricted data is visible only to the right users. This step is worth the time. Most privacy issues come from small implementation gaps, not from the policy itself. ## Recommended rollout order If you want a simple order of operations, use this: 1. Choose the consent method. 2. Decide what data is allowed. 3. Configure SDK initialization and storage. 4. Connect your CMP if needed. 5. Add filters for bots and internal traffic. 6. Classify and restrict sensitive properties. 7. Set data retention. 8. Document your deletion workflow. 9. Validate everything with end-to-end tests. That sequence keeps the work manageable and makes it much easier to explain your setup to internal stakeholders and external auditors. ## Additional considerations Depending on your implementation, you may need to configure more than cookies, storage, and access controls. The topics below are worth reviewing before you consider your setup complete. ### Session Replay If you use Session Replay, review it separately from your core analytics setup. Replay can capture a richer set of user interactions, so it often requires its own privacy review, masking rules, and consent treatment. In practice, this means you should: - decide whether Replay is covered by the same consent choice as analytics or needs separate treatment. - review masking and exclusion settings before rollout. - make sure your privacy notice accurately describes the use of replay technology. You can learn more in the [Session Replay documentation](https://amplitude.com/docs/session-replay). ### Access requests, not only deletion requests Many privacy programs focus first on deletion, but customers may also need to respond to requests for access to personal data. If you support privacy requests, plan for both. For deletion workflows, use the [User Privacy API](https://amplitude.com/docs/apis/analytics/user-privacy). If you also need to support data access requests, refer to the [DSAR API documentation](https://amplitude.com/docs/apis/analytics/ccpa-dsar). A good practice is to document one operational workflow that covers: - request intake. - identity verification. - access or deletion in Amplitude. - cleanup in upstream systems. - audit logging. ### Privacy notices and disclosures Your implementation and your privacy notice should stay aligned. If you collect analytics data, use Session Replay, or rely on a limited anonymous measurement flow, review your disclosures to make sure they still describe what you collect, why you collect it, and how users can exercise their choices. This is especially important when teams change implementation details over time. A privacy issue is often caused not by the tool itself, but by a gap between what the product does and what the notice says. ### Hosting region and data residency For some organizations, especially in Europe, hosting region is part of the privacy decision. Amplitude offers both US and EU data center options, and that choice may affect your internal review process. If data residency matters to your business, confirm your hosting setup early and make sure it matches your internal requirements. You can learn more about [data residency options](https://amplitude.com/docs/admin/account-management/manage-orgs-projects). ### Operational caveats after launch Some privacy controls work exactly as expected, but still have practical consequences that teams should plan for. A few important examples: - deleting a user doesn't prevent Amplitude from tracking that user again. - if deleted data still exists in a warehouse or synced source, Amplitude may reingest it. - retention settings can permanently remove historical data and affect old charts. - test privacy settings after every major instrumentation or tag-management change. A good rollout doesn't end at launch. Re-test your setup periodically, especially after SDK updates, consent banner changes, new event launches, or changes to upstream pipelines. ### When to ask for help If your setup includes regional legal complexity, multiple consent categories, sensitive personal data, or multiple downstream activation tools, involve your legal, privacy, and security teams early. It's much easier to design a privacy-conscious setup from the start than to retrofit one later. In general, the safest approach is to keep the implementation simple, collect only what you need, and add complexity only when there's a clear business and legal case for doing so. ### Server-side tracking as an alternative for known users For logged-in or identified users, server-side tracking offers an alternative that avoids some client-side consent constraints. If a user is authenticated, you can pass their user ID directly to Amplitude's HTTP API from your backend, bypassing the browser SDK entirely. In many jurisdictions, server-side tracking of authenticated users doesn't trigger ePrivacy Directive requirements. ePrivacy applies to accessing or storing information on the user's device (cookies, localStorage, and so on), and server-side calls don't touch the device. For logged-in users, server-side Amplitude tracking may therefore not require consent under ePrivacy rules in some regions. Important caveats: - This only applies to known, logged-in users. For anonymous visitors, you still need a client-side identifier to track behavior across pages, even if your server generates that identifier (as with cookieless tracking approaches). As soon as you store or access any persistent identifier on the user's device, ePrivacy rules apply. - Your legal team should confirm whether server-side tracking of identified users is sufficient for your jurisdiction and use case. - Confirm with your privacy team that processing authenticated user data server-side aligns with your data processing agreements and your GDPR lawful basis. ## Why Amplitude doesn't generate modeled data for non-consenting users Some analytics platforms fill in the gap left by non-consenting users by modeling estimated behavior, statistically inferring what those users might have done based on users who did consent. Amplitude doesn't take this approach. Here's why. - Modeled data is inconsistent and hard to interpret. Platforms that offer modeling typically generate estimates only when they have enough activity volume to do so. Below certain thresholds, the platform produces no model at all, and coverage is uneven across segments, time periods, and properties. You can't easily tell when you're looking at real data and when you're looking at an estimate, and applying consistent analysis rules across your dataset becomes nearly impossible. - Modeled data behaves differently depending on where you query it. If you export modeled event data to a warehouse and run the same analysis there, you often get different results than you do inside the analytics UI. Platforms typically apply this logic at query time in the UI, not at ingestion. This creates a split source of truth that is very difficult to reconcile, particularly for teams who rely on warehouse exports for reporting or compliance. Amplitude's approach focuses on clear consent boundaries and accurate first-party data. It's better to know precisely what you measured and for whom than to fill gaps with estimates that are hard to validate or explain to auditors. If your organization uses Google services alongside Amplitude, you can configure Google Consent Mode for those tools independently. It doesn't affect how Amplitude processes data. ## Privacy and Amplitude AI features > **Note:** > > If your Amplitude account includes AI-powered features, such as Ask Amplitude, AI-generated insights, or other AI-assisted workflows, you may have questions about how your user data interacts with those features. For example, you may want to know whether event data is processed by third-party large language models (LLMs), and what data handling agreements apply. > > Amplitude's [Trust Page](https://trust.amplitude.com) includes a dedicated AI FAQ that covers these topics, including questions about data sharing with AI providers. > > For more detailed technical information, the [Amplitude AI privacy and security documentation](https://amplitude.com/docs/amplitude-ai/privacy-and-security) covers third-party LLM usage and related data handling practices. > > Review these resources and align with your privacy team before enabling AI-powered features, particularly if you operate under GDPR or handle sensitive personal data. ## Final recommendation If you want the safest and simplest default, start with Method 1: initialize Amplitude only after consent, keep your event schema tight, and add access controls and retention rules from day one. If your policy allows more flexibility, you can still keep the setup privacy-friendly by reducing identifiers, using a proxy when needed, filtering bad traffic, and limiting access to sensitive data inside Amplitude. ================================================================================ # Planning and instrumentation workflow URL: https://amplitude.com/docs/data/data-planning-workflow Updated: 2026-09-01 ================================================================================ # Planning and instrumentation workflow Using Amplitude Data for planning helps ensure high-quality data from the start and reduces the need for clean-up later. This article describes the complete workflow in Amplitude Data. ## Plan your events For most companies, the lifecycle starts when launching a product or feature. Suppose the product team creates a new onboarding flow and wants to see how it performs. The first step is determining what to track in this onboarding flow. What metrics does your feature affect, and what does success look like? After you identify the events and properties you want to track, create them on the _Events_ page. With Premium plans, you can create a branch to capture all your related changes without impacting anyone else. The Git branch in your code and the branch in Amplitude Data co-exist throughout the process. Engineering can pull analytics code from the Amplitude Data branch into their Git branch throughout the feature's development. Branches are especially helpful when multiple teams work on the same project, or when teams work on various features simultaneously. ## Instrument events If you haven't already, invite the developers working on the feature to Amplitude Data and ask them to review your proposed plan. If you work in a branch, send them a link to the _Activity_ page of your branch, which shows all the changes you want to make. Next, engineers implement the updated tracking plan in their branch. They use the [Ampli CLI](https://amplitude.com/docs/sdks/ampli/ampli-cli) to generate a new tracking library that matches the changes in the Amplitude Data branch (`ampli pull -b {branch-name}`). Iterating on your tracking plan with your developers is normal. You might respond to issues or challenges they encounter. Update your plan as your understanding evolves based on their feedback. > **Tip:** Automate instrumentation planning with AI > > The Amplitude MCP plugin includes skills that automate event discovery and instrumentation planning directly in your editor. Use `amplitude:add-analytics-instrumentation` to analyze a PR or branch diff, generate a complete instrumentation plan, and add events and properties to your Amplitude tracking plan with rich metadata, including descriptions and categories, without leaving your editor. > > For setup and the full list of available skills, refer to [Plan your taxonomy](https://amplitude.com/docs/data/data-planning-playbook#ai-assisted-taxonomy-planning). ## Request reviews If you configured your project for team reviews, you might not have permission to merge directly. Instead, you first create a merge request. A merge request asks stakeholders outside your team to review your changes and give their explicit approval. After the feature team is happy with the changes (the plan is comprehensive, and engineering implemented it correctly), your branch is ready for review by other stakeholders. > **Tip:** > > Refresh your changes from main to get your branch up to date and resolve any potential conflicts. You might do this more than once as your developers refresh their branch (with `git merge` or `git rebase`). Analytics changes often affect the broader organization, so getting feedback is essential. Typical stakeholders include the security and legal team, the growth team, and the data team. Soliciting reviews starts with creating a merge request. When creating a merge request, describe the changes you're proposing and @mention any specific reviewers or approvers you want to include. An admin- or manager-level user can then approve changes. ## Merge After the tracking plan changes are ready and everyone needed to approve has done so, you're ready to merge into main. When the rest of the feature team is ready to merge in Git, merge your branch in Amplitude Data first. Merging creates a new official version of your tracking plan on main and assigns new versions to all new and changed events. If your Git branch is already up to date with the merged Amplitude Data branch, you can now merge your Git branch as-is. Run `ampli status --is-merged` to check that your Ampli code is up to date with the merged Data branch. If the command returns an error, run [ampli pull](https://amplitude.com/docs/sdks/ampli/ampli-cli#pull) to update the generated library to the latest version. After `ampli status --is-merged` succeeds, you can merge the Git branch. ================================================================================ # Create a tracking plan URL: https://amplitude.com/docs/data/create-tracking-plan Updated: 2026-09-22 ================================================================================ # Create a tracking plan A tracking plan defines every event and property you collect, why you collect each one, and which source emits it. Build one before you instrument code so analysts, PMs, and engineers work from one schema instead of arguing about field names after the data lands. In Amplitude Data, the plan lives next to your events and properties, so edits flow straight into instrumentation, governance, and the Ampli code generator. Build or update a plan directly in Amplitude Data's UI when your team wants a shared, reviewable workspace for designing events and properties together. Use the [Amplitude MCP Server](https://amplitude.com/docs/amplitude-ai/amplitude-mcp#tracking-plan-changes) instead when you want an AI coding client to create or edit the same tracking plan directly from code. For the strategy behind designing a plan before you build it, refer to the [data planning playbook](https://amplitude.com/docs/data/data-planning-workflow). ## Plan availability Data Catalog and Proactive Planning are available on all plans. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details. _Availability reflects the latest Amplitude plans. If your organization is on an older plan, your access may differ. Check your plan under [Plans & Billing in your organization settings](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._ ## Find your tracking plan Each project in Amplitude has its own tracking plan. To find your plan, select the **Data** tab in the top navigation. Then, in the left navigation, select the project from the dropdown at the top. The events and properties for your plan appear on the left. ## Update your tracking plan You can update your plan in two ways: - Proactively plan new events and properties before implementation, and use Amplitude Data to define details, work together with team members, and agree on what you want to track. (Recommended.) - Reactively plan events and properties after Amplitude ingests for the first time. By default, these events and properties appear in your plan as "Unexpected." You can add them to your plan, or delete them to stop ingestion and remove them from your data catalog. You can also manage events, properties, and branches through the [Amplitude MCP Server](https://amplitude.com/docs/amplitude-ai/amplitude-mcp#tracking-plan-changes) from an AI coding client, including deleting and restoring events and properties. MCP tools such as `manage_amp_events` and `manage_amp_properties` modify the same tracking plan you manage in Amplitude Data. ### Create a source [Sources](https://amplitude.com/docs/data/sources/connect-to-source) represent the originating source of the data sent to Amplitude (for example, your iOS, Android, Web, and Backend). When using the [Ampli Developer experience](https://amplitude.com/docs/sdks/ampli), you need to create a source to generate the correct tracking library. To create a source, follow these steps: 1. Navigate to _Data > Sources_ and select **Add Source**. 2. Select the SDK source you want to add. 3. Name your new source and select **Create**. ### Create an event An event is a distinct action that a user can take in your product. When you create an event, you can specify metadata about the event that helps with both implementation and discovery in Analytics after implementation. To create an event, follow these steps: 1. Navigate to _Data > Events_ and select **Create event**. 2. Give your event a name. Amplitude suggests any modifications to match your naming convention. 3. Add a source to specify where to instrument this event. 4. Add any relevant metadata, including: - A description to help define when to send the event or important details about the event. - A category to provide more context and group similar events. - The active or inactive status of the event. An active event is one the user triggers. Inactive events relate to the user, but a direct user action doesn't initiate them (for example, receiving a push notification). 5. Add any relevant event properties to the event. ### Create an event property Event properties describe the event and the context in which a user triggered it. For example, a `Song Played` event might contain a `Song Title` property. A name, description, examples, and rules define each property. Rules are specific to each data type. For example, property `Song Title` of type `String` can have the following rules: Min Length, Max Length, and Regex. To create a new event property, follow these steps: 1. In Amplitude Data, navigate to _Data > Properties_ and select the **Event Properties** tab. 2. Select **Create event property**. 3. Give your event property a name and add any relevant metadata to the property, including: - A description. Including example values can be helpful. - Whether this property is required on this event. If it is, and Amplitude receives an event that doesn't include it, Amplitude Data generates a warning. - The data type (such as string or number) and any additional rules. You can now add this property to your events. To add an existing property, or create a new property within an event, follow these steps: 1. In Amplitude Data, navigate to _Data > Events_ and select the event you want to add a property to. 2. In the event detail pane, select **Add property**. 3. Name your new property, or select an existing property to add to the event. > **Note:** > > If multiple events share similar properties, you can [create a property group](https://amplitude.com/docs/data/property-updates-property-groups). Property groups, which are distinct from group properties, make it easier to manage complex tracking plans because you don't have to keep adding the same properties repeatedly. When you update a property group, the update applies to all events associated with the group. ### Create a user property User properties capture traits about the user. After you set a user property, it automatically applies to any subsequent events the user triggers, until its value updates. To create a new user property, follow these steps: 1. In Amplitude Data, navigate to _Data > Properties_ and select the **User Properties** tab. 2. Select **Create user property**. Give your new user property a name. 3. Add any relevant metadata to the property, including: - A description. Including example values can be helpful. - The data type (such as string or number) and any additional rules. ### Create a group with group properties > **Note:** > > This feature requires the [Accounts](https://amplitude.com/docs/analytics/account-level-reporting-setup) add-on. Group properties make it easy to associate a user with a particular account (for example, name, industry, or employees) whenever the `group()` call runs. Group properties help when you want to track groups of users (for example, tracking events across an entire company, instead of specific users within that company). To create a group, follow these steps: 1. In Amplitude Data, navigate to _Data > Groups_ and select **Create group**. 2. Name your group and add any relevant metadata, including: - A description. Including example values can be helpful. - The data type (such as string or number) and any additional rules. 3. Add any group properties that apply to this group type. To create a group property, follow these steps: 1. In Amplitude Data, navigate to _Data > Properties_ and select the **Group Properties** tab. 2. Select **Create group property**. 3. Name your group and add any relevant metadata, including: - A description. Including example values can be helpful. - The data type (such as string or number) and any additional rules. ## Collaborate on your plan If you want feedback on any changes you've made, you can @mention your colleagues in the rich text editor of any event or property to send them an email notification or Slack message. This approach helps when you're working on a branch and finalizing the event and property names you plan to use. ## Send your plan to your developers Finally, send this plan to your developers. If you're using the Ampli Developer Tools, it consumes your tracking plan and presents it to developers as type-safe autogenerated code. Amplitude Data can generate a tracking library for all popular platforms and programming languages. The autogenerated library is a lightweight wrapper over your analytics provider's SDK that provides type-safety, supports linting, and enables additional features like input validation. The code exactly replicates the spec in the tracking plan and enforces all its rules and requirements. You can also send them a link to the branch or directly to Amplitude Data, where they can review the details you specified. ================================================================================ # Work with branches URL: https://amplitude.com/docs/data/work-with-branches Updated: 2026-09-22 ================================================================================ # Work with branches A branch in Amplitude Data is a point-in-time copy of your tracking plan that you and your team edit privately, without exposing the changes to anyone else until you merge them back into the main tracking plan. If you've used Git, the model works the same way: you isolate changes on a branch, then merge them when they're ready. When you first create your Amplitude Data account, Amplitude automatically creates a default branch called `main`. It includes a few sample events and properties to get you started. Think of the `main` branch as your production branch: it contains your latest official tracking plan and matches what's instrumented in your default branch in Git (typically `master` or `main`). `main` is suitable for getting started in Amplitude Data, and you may find that it's the only branch you need for some time. ## Plan availability Branches varies by plan. Some features need a higher plan or an add-on. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details. | Plan | Branches | | --- | --- | | Free | 1 branch | | Plus | 1 branch | | Growth | Included | | Enterprise | Included | Approval Workflow is available on the Growth and Enterprise plans. _Availability reflects the latest Amplitude plans. If your organization is on an older plan, your access may differ. Check your plan under [Plans & Billing in your organization settings](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._ ## Publish a version of your tracking plan A branch initially keeps the changes you make in its staging area, where they remain pending. Pending changes are work-in-progress changes: visible to you and your teammates, but hidden from your production systems and not yet available for instrumentation by your engineering team. When your pending changes are ready, publish them. Publishing your changes creates a new version of your tracking plan that includes those changes. Publishing also exposes that new version to your engineering team for instrumentation. If your new version is on the main branch, those changes also propagate to your production systems. Every new version has a version number and an optional description, so you can tell versions apart later. Version numbers start at 1 and increment by 1 each time you publish a new one. Every branch has its own tracking plan versions, which means it's possible to have two versions of the tracking plan with the same version number: one in `main`, and one in your own branch. When this happens, Amplitude Data always displays the name of the branch to avoid confusion. ## Create and delete branches As you and your team ramp up your use of Amplitude Data, you may outgrow the `main` branch and need a more robust workflow. This usually happens when: - Too many people are making changes to `main` at the same time, or - Feature teams want their own separate copy of the tracking plan to collaborate in, review their work, and get stakeholder approval. In Amplitude Data, all branches spawn from `main` and merge back into `main`. To create a new branch, follow these steps: 1. Click **main** in the page's header. 2. Type the name of the branch you want to create. 3. Click **+**. 4. In the _Create branch_ modal, confirm the name of your branch, add an optional description, and click **Create**. If you have pending changes on `main`, you can either take those changes with you into your new branch, or leave them behind on `main`. To delete a branch, follow these steps: 1. Click the **X** next to the branch name. 2. In the modal that appears, click **Delete** to confirm your choice. ## Work on a branch After your branch exists, working with it is like working with `main`. You and your team can create and publish new versions, instrument those versions in the product, and report back to the branch on the status of the instrumentation. This can all happen in parallel with other teams working in their own branches, without any impact on you. From time to time, refresh your branch with any changes made to `main` since you created your branch. If Amplitude Data detects that your branch is out of date with `main`, you see a **Refresh** button in the page's toolbar. Click it to get caught up. ## Merge your branch back into main When you're happy with the changes you've made on your branch, merge them back into `main`. This typically happens when your product team is also ready to merge their changes into the `main` branch in Git. There are a few prerequisites to address before you can successfully merge: - You must publish all pending changes on your branch. - Your branch must be up to date with `main`. - `main` must have all its pending changes published as well. To publish your changes to a new version on your branch, follow these steps: 1. In the left sidebar, click **Save changes**. 2. In the _Save changes_ modal, review the pending changes. If everything looks correct, click **Save**. To merge, follow these steps: 1. Go to _Activity_. You may have to click **Refresh**. 2. Click **Approve**. 3. Click **Merge**. If your project requires [team reviews](https://amplitude.com/docs/data/amplitude-data-settings), you may not have permission to merge directly. In this case, you must first create a merge request. A merge request is a way to ask stakeholders outside your team to review your changes and give their explicit approval. Only team members with Manager or Admin permissions can approve changes; do so by logging into Amplitude Data and clicking **Merge** in the page's toolbar. Anyone on your team can then merge an approved merge request. ## Copy branch changes to testing environments After you apply changes to a branch, you can copy those changes to other projects or environments for testing. To copy branch changes, follow these steps: 1. Go to _Activity > Branch Changes_ from the branch you want to copy. 2. Click **Copy Branch**. 3. In the modal that appears, select the testing projects to copy the branch to from the dropdown. Then click **Copy**. 4. After the copy completes, click the notification to review the copied branch. 5. Review changes to the testing project. If changes look as expected, click **Merge**. Managers and Admins can also restrict which projects can accept copies of branch changes. To restrict branch copying, follow these steps: 1. From the source project, go to _Settings > General_. 2. Select the checkbox next to **Restrict branch copying to specified testing projects**. 3. From the dropdown, select the checkbox next to the projects where other Amplitude users can save copies of branch changes. ================================================================================ # Ampli and developer tools URL: https://amplitude.com/docs/data/use-ampli Updated: 2026-09-22 ================================================================================ # Ampli and developer tools Ampli dynamically generates a lightweight wrapper for the Amplitude SDK based on your analytics tracking plan in Amplitude Data, making event tracking easier and less error-prone. The Ampli Wrapper provides types and methods that prevent human error by strictly enforcing event names and property values. The wrapper code enables autocompletion for all events and properties in your tracking plan, plus static type checks at development and compile time. To learn more about using Ampli, go to the [Amplitude Developer Center](https://amplitude.com/docs/sdks/ampli). ## Plan availability Development Tools (Ampli) is available on all plans. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details. _Availability reflects the latest Amplitude plans. If your organization is on an older plan, your access may differ. Check your plan under [Plans & Billing in your organization settings](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._ ================================================================================ # Monitor your data with observe URL: https://amplitude.com/docs/data/validate-events Updated: 2026-09-22 ================================================================================ # Monitor your data with observe Observe continuously inspects, analyzes, and monitors your event stream against your tracking plan, surfacing invalid, missing, and out-of-date events as they occur. It needs no code changes and runs automatically in the background, keeping your tracking code in sync with your tracking plan. Observe assigns every event one of four statuses: unexpected, valid, invalid, or out of date. Observe listens to your existing event stream and turns your tracking code into a living document, so you get a holistic view of your data collection across platforms. You and your teams get immediate insight into anything broken or that needs attention. With an intuitive, collaborative workflow, your teams can work together to instrument fixes and keep your tracking plan in shape. ## Plan availability Observability is available on the Plus, Growth, and Enterprise plans. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details. | Plan | Allowance | How to access | | --- | --- | --- | | Free | Not included | [Upgrade your plan](https://amplitude.com/pricing) | | Plus | Included | Included in plan | | Growth | Included | Included in plan | | Enterprise | Included | Included in plan | _Availability reflects the latest Amplitude plans. If your organization is on an older plan, your access may differ. Check your plan under [Plans & Billing in your organization settings](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._ ## View and update your event statuses To access your event stream, go to _Data > Events_. This displays all your events. The first time you view your tracking plan, Amplitude displays all events and properties received and processed. By default, Amplitude categorizes all events and properties as _Unexpected_. To add them to your tracking plan, check the box next to the event name and click **Add to plan**. Do this anytime you want to add an unexpected event to your tracking plan. Click **Publish** to complete the process. From this point on, Observe alerts you about any changes to this event or any properties associated with it. Your events always have one of four statuses: - **Unexpected**: Any event or property not yet added to your tracking plan. - **Valid** (and **Current**): Any event or property that matches (in name and schema) the latest version of an existing event. If Observe doesn't know the version of the event, it only ensures that the event shape matches your current tracking plan. - **Invalid**: Any event or property that doesn't match your current tracking plan. - **Out of Date**: Any event or property that matches a previous version of an existing event or property (only applicable when using Amplitude SDKs). Observe only surfaces data as it occurs. If you have legacy tracking or events that fire infrequently, they may not appear in your tracking plan. If you know of events that Observe doesn't surface, you can add them manually to your plan, or trigger the events yourself. > **Note:** > > If you're blocking, filtering, or transforming your data upstream of Amplitude, Observe can't access this data. For this reason, ensure that you send all your data to Amplitude. ### Observe and the Ampli CLI If you've instrumented all your event tracking using Amplitude's SDKs, you already benefit from type-safe analytics libraries, client-side validation, and continuous integration with [CI](https://amplitude.com/docs/sdks/ampli/validate-in-ci) for clean, accurate data you can trust. Observe still adds value by surfacing and alerting you to runtime validation errors in the web app. This is specifically relevant for JavaScript, because it isn't a type-safe language, and checks only happen at runtime. Refer to the Amplitude Data developer documentation for more details. ## Overlay your tracking plan with observed events and issues You can overlay your tracking plan with your event stream. If you're using the Amplitude SDK, you also have the option to overlay your tracking plan with your event stream from an environment, but only data sent to the specific branch you're on. This is useful for debugging when multiple teams send data to the environment. You can also set a specific time range to use for overlaying your event stream with your tracking plan. You can choose from: - Five minutes. - One hour. - 12 hours. - Seven days. - 14 days. Note that changing this range can determine whether Observe considers an event valid or invalid. For example, if you had a bug seven days ago, choosing **Last 7 days** causes the event to show up as invalid. If you fixed it at any point between seven days ago and 12 hours ago, and then choose **Last 12 hours**, Observe considers it valid. ## Act on your Observe insights Observe surfaces missing and invalid properties on an event. The property rows show this information in a few ways: - **Status tooltip**: Indicates if an event was invalid at the point Amplitude received it (if Observe receives the version, it compares the event to the version; otherwise, it compares the event to your current tracking plan). - **% Seen indicator**: Red if the property is required (published or unpublished) and Amplitude received the event without the property within the selected timeframe. The indicator can be red while the status is green if you have unpublished changes, or if you recently modified the event. - **Type indicator**: Red if Amplitude received the property with a type other than what's selected (published or unpublished) within the selected timeframe. The indicator can be red while the status is green if you have unpublished changes, or if you recently modified the event. Observe automatically detects the source of each event (based on the library) and displays those sources in the event detail pane. This is especially helpful when you have multiple sources managed by different teams, because you can identify which source is sending invalid data. The sparkline to the right of the source name shows both total and invalid event volume to quantify the amount of data with errors. You can also create and assign multiple SDK sources with the same library. For example, if you have a marketing site and a web app that use the Browser SDK, you can create two different sources and assign the correct source to each event. Using Ampli also lets you see each source's volume and validation data separately. If you're not using Ampli, you see the volume for both sources rolled up into a single row with the library name (in this case, "Browser SDK".) ## Scope and limitations Observe works by default if you're sending data to Amplitude. Observe is limited by how you're sending data to Amplitude. If you're using Amplitude's SDKs (current source support: JavaScript, Node.js, Android, and iOS), Observe can attribute your event stream to its respective source (web, iOS, backend, and so on). > **Note:** > > If Observe can determine the version of your event, it validates against that version's schema. When Observe doesn't know the version, it validates against the schema of the latest version in your tracking plan. ================================================================================ # Protect your schema from unexpected data URL: https://amplitude.com/docs/data/configure-schema Updated: 2026-10-07 ================================================================================ # Protect your schema from unexpected data Schema settings control how Amplitude handles data that violates your schema. A schema violation happens when Amplitude receives data that your schema doesn't account for, such as an event you didn't plan or a property value with an unexpected type. You configure a response to three types of schema violation: unplanned event types, unplanned event or user properties, and unplanned property values. For each type, Amplitude either marks the data as unexpected and ingests it, or rejects it. Use schema settings when you want Amplitude to mark or reject data that violates your schema at ingestion. To monitor your event stream for invalid, missing, or out-of-date events without changing how Amplitude ingests data, use [Observe](https://amplitude.com/docs/data/validate-events) instead. Find your schema settings by going to Amplitude Data and navigating to _Settings > Schema Settings_. ## Plan availability Protected Schema is available on the Growth and Enterprise plans. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details. | Plan | Allowance | How to access | | --- | --- | --- | | Free | Not included | [Upgrade your plan](https://amplitude.com/pricing) | | Plus | Not included | [Upgrade your plan](https://amplitude.com/pricing) | | Growth | Included | Included in plan | | Enterprise | Included | Included in plan | _Availability reflects the latest Amplitude plans. If your organization is on an older plan, your access may differ. Check your plan under [Plans & Billing in your organization settings](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._ ## Unplanned event types Sometimes, Amplitude may receive an event that isn't part of your schema, or that you didn't plan earlier. This is an unplanned event type. You can configure Amplitude to respond in these ways: - **Mark As Unexpected**: Amplitude ingests the event, triggers a warning, and sends a notification to the designated subscribers. - **Reject**: Amplitude rejects the event and sends a notification to the designated subscribers. Amplitude doesn't store the event or its properties. ## Unplanned event or user properties When Amplitude encounters an event or user property that isn't part of your schema, or that you didn't plan earlier, it considers the property to be an unplanned event or user property. You can configure Amplitude to respond in the following ways: - **Mark As Unexpected**: Amplitude ingests the property, triggers a warning, and sends a notification to the designated subscribers. - **Reject**: Amplitude rejects the property and sends a notification to the designated subscribers. Amplitude stores the event, but not the properties. ## Unplanned event or user property values When Amplitude receives an event property value that isn't part of your schema, or that you didn't plan earlier, it considers the value an unplanned property value. For example, an event property value arrives as a string, but your schema expected a number. You can configure Amplitude to respond to an unplanned property value in the following ways: - **Mark As Unexpected**: Amplitude ingests the property, triggers a warning, and sends a notification to the designated subscribers. - **Reject**: Amplitude rejects the property, triggers a warning, and sends a notification to the designated subscribers. Amplitude stores the event, but not the properties. If Amplitude rejects your event data and you want to ingest it, add the events or properties to your schema by planning a new event or property. ## View validation errors After you initialize your schema and define your expected events and event properties, your schema can validate live data coming into Amplitude. If you configured your schema to trigger a warning for unexpected events or properties, Amplitude logs an error in the validation errors panel. View validation errors by going to Amplitude Data and navigating to _Settings > Schema Settings > Validation Errors_. Any errors triggered in the last 24 hours appear on this page, whether or not you've since approved or rejected the event or property. If no errors appear on the validation page, there haven't been any violations in the past 24 hours. This doesn't mean you've fixed every violation; it only means Amplitude hasn't encountered them in that time. Select **Subscribe** to set up email alerts for validation errors. ## Manage subscribers You can designate specific users to receive email notifications of any schema violations. Select **Manage Subscribers** at the top right of your schema options. ================================================================================ # .CSV import and export URL: https://amplitude.com/docs/data/csv-import-export Updated: 2026-09-22 ================================================================================ # .CSV import and export Import and export your tracking plan as a .CSV to make bulk schema changes in Amplitude Data. The .CSV round-trip covers events, event properties, and user properties, and supports planning new events, editing categories and descriptions, and applying changes in one upload instead of editing entities one at a time. Use .CSV import when you need to make bulk schema edits across many events or properties at once. For programmatic, automated, or scripted schema changes, use the [Taxonomy API](https://amplitude.com/docs/apis/analytics/taxonomy) instead. ## Plan availability CSV Import/Export is available on all plans. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details. _Availability reflects the latest Amplitude plans. If your organization is on an older plan, your access may differ. Check your plan under [Plans & Billing in your organization settings](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._ ## Events and event properties Follow these steps to import or export events and event properties: 1. Navigate to Data, and select **Events** under your tracking plan in the left side pane. 2. To import, select the import icon to open the import modal. 3. If your import file is ready to upload and follows the [expected schema for events and event properties](#events-and-event-properties-file-schema), you can drop your .CSV file or select **Upload** and choose the file from your location. If not, select **template** to download a template .CSV to update for importing. The imported events and event properties appear in a branch named _import_. 4. After you confirm the imported tracking plan updates are correct, you can [merge the changes back into the main branch](https://amplitude.com/docs/data/data-planning-workflow). 5. To export events and event properties from your tracking plan, select the export icon instead. 6. In the export modal that appears, choose whether to download your tracking plan's schema or a .CSV file template. Then, select **Download**. Downloaded .CSV files of your tracking plan contain additional fields not required for import. The next section defines the events and event properties .CSV import file structure and the [additional columns seen in the exported file](#events-and-event-properties-file-schema). > **Note:** > > The import and export features don't support custom events, transformations, or default Amplitude entities. ## Events and event properties file schema The events and event properties .CSV file requires a specific schema for a successful import. The table below highlights the required schema by entity type. Note that: - The file's header must contain all listed fields. - The fields can be in any order, but their names and values must match exactly in spelling and capitalization for a successful import. - Some fields require a value depending on entity type, as indicated in the following list. ### Action - Definition: Action to perform on a particular entity. - Values: - `Ignore`: No changes made to the entity or its subproperties. - `Remove`: You can remove event and property groups from the tracking plan. The remove value doesn't affect individual properties. Removing an event or property group disassociates related properties, and changes a live property's status to unexpected. The remove value doesn't delete an entity or stop ingestion. - `<blank>`: Creates or updates an entity and its associated sub-entities. - For events, event properties, property groups, and property group properties. ### Array min items - Definition: Minimum number of items for a property with an array property value type - For event properties and property group properties ### Array max items - Definition: Maximum number of items for a property with an array property value type - For event properties and property group properties ### Array unique items - Definition: Denotes if an array property value type has unique items - Values: - `TRUE`: Array has unique items - `<any>`: Assumes array doesn't have unique items - For event properties and property group properties ### Const value - Definition: Const value for properties with a const property value type - For event properties and property group properties ### Enum values - Definition: Enum values for properties with an enum property value type - Format: Separate each enum value with a comma - For event properties and property group properties ### Event activity - Definition: Description of an event's activity. - Values: - `Active`. - `Inactive`. Marking an event as inactive applies retroactively and immediately, and excludes the event from the `Any Active Event` metric. - For events. ### Event hidden from dropdowns - Definition: Set event visibility in dropdowns - Values: - `True`: Event is hidden in event dropdowns - `False`: Event is visible in event dropdowns - `<blank>`: Retains the current value - For events ### Event hidden from persona results - Definition: Set event visibility in persona results - Values: - `True`: Event is hidden from persona results - `False`: Event is visible in persona results - `<blank>`: Retains the current value - For events ### Event hidden from pathfinder - Definition: Set event visibility in pathfinder - Values: - `True`: Event is hidden from pathfinder - `False`: Event is visible in pathfinder - `<blank>`: Retains the current value - For events ### Event hidden from timeline - Definition: Set event visibility in timeline - Values: - `True`: Event is hidden from timelines - `False`: Event is visible in timelines - `<blank>`: Retains the current value - For events ### Event category - Definition: Category of an event - For events ### Event display name - Definition: Only applicable to optional display names of events - For events ### Event property name - Definition: Name of the property - Required for event properties and property group properties ### Event source - Definition: Sources associated with the event - For events ### Number property value min - Definition: Minimum value of a property with number property value type - For event properties and property group properties ### Number property value max - Definition: Maximum value of a property with number property value type - For event properties and property group properties ### Number is integer - Definition: Denotes if a property with number property value type is an integer - Values: - `True`: Property is an integer - `False` or `<blank>`: Property isn't an integer - For event properties and property group properties ### Object type - Definition: Entity type - Values: - `Event` - `Property Group` - Required for events and property groups ### Object name - Definition: Name of the event or property group - Required for events and property groups ### Object owner - Definition: Owner of the event or property group - Leaving this as `<blank>` removes the owner if one exists on the event or property group ### Object description - Definition: Description of the entity - For events and property groups ### Property type - Definition: Type of property associated with the event - Values: - `Event Property` - `Event Property Group` - Required for events ### Property group names - Definition: Property group that's associated with the event - For events ### Property description - Definition: Description of the property - For event properties and property group properties ### Property value type - Definition: The value type of an event property or property group property - Values: - `string` - `number` - `boolean` - `any` - `enum` - `const` - For event properties and property group properties ### Property required - Definition: Denotes the required status of the property - Values: - `True`: Property is required - `False` or `<blank>`: Property is optional - For event properties and property group properties ### Property visibility - Definition: Set property visibility in charts - Values: - `VISIBLE`: Property is visible in charts - `HIDDEN`: Property is hidden in charts - `<blank>`: Retains the current value - For event properties only ### Property is array - Definition: Denotes if the property is an array - Values: - `True`: Property is an array - `False` or `<blank>`: Property isn't an array - For event properties and property group properties ### Property regex - Definition: Regular expression (Regex) values for properties with a string property value type - For event properties and property group properties ### String property value min length - Definition: Minimum length of a property with string property value type - For event properties and property group properties ### String property value max length - Definition: Maximum length of a property with string property value type - For event properties and property group properties ### Tags - Definition: Tags associated with an event - Format: separate each tag with a comma - For events ### Additional fields .CSV export of events and event properties The following list includes additional fields found in the .CSV export of your tracking plan’s events and event properties. #### Action - Definition: The default action to perform on a particular entity. This field exists in the import template, but the downloaded file includes default values. - Values: - `Ignore`: The user property is unexpected, blocked or deleted. - `<blank>`: The user property is planned or live. - For events, event properties, property groups property group properties #### Event first seen - Definition: The date on which the event was first seen. - Format: `mm/dd/yyyy` - For events #### Event last seen - Definition: The date on which the event was last seen. - Format: `mm/dd/yyyy` - For events #### Property first seen - Definition: The date on which the property was first seen. - Format: `mm/dd/yyyy` - For property groups #### Property last seen - Definition: The date on which the property was last seen. - Format: `mm/dd/yyyy` - For property groups ## User properties Follow these steps to import or export user properties: 1. Navigate to Data, and select **Properties** under _Tracking Plan_ in the left side pane. Then select **User Properties**. 2. Select the import icon to open the import modal. 3. If your import file is ready to upload and follows the [expected user properties schema](#user-properties-file-schema), you can drop your .CSV file or select Upload and choose the file from your location. If not, select **template** to download a template .CSV to update for importing. The imported events and event properties appear in a branch named _import_. 4. After you confirm the imported tracking plan updates are correct, you can [merge the changes back into the main branch](https://amplitude.com/docs/data/data-planning-workflow). 5. To export user properties from your tracking plan, select the export icon instead. 6. In the export modal that appears, choose whether to download your tracking plan's schema or a .CSV file template. Then, select Download. The next section defines the user properties .CSV import file structure and the [additional columns seen in the user properties export](#user-properties-file-schema). ## User properties file schema The list below highlights the required schema for the user properties .CSV file import. Note that: - The file's header must contain all listed fields. - The fields can be in any order, but their names and values must match exactly in spelling and capitalization for a successful import. - Some fields require a value as indicated in the following list. ### Action - Definition: Action to perform on a particular user property. - Values: - `Ignore`: Amplitude makes no changes to the user property. - `Remove`: Amplitude removes the user property from the tracking plan. The removed value doesn't delete a user property or stop its ingestion. - `<blank>`: Creates the user property if it didn't already exist, or updates the user property if it did exist. ### Array min items - Definition: Minimum number of items for a property with an array property value type ### Array max items - Definition: Maximum number of items for a property with an array property value type ### Array unique items - Definition: Denotes if an array property value type has unique items - Values: - `TRUE`: Array has unique items - `<any>`: Assumes array doesn't have unique items ### Const value - Definition: Const value for properties with a const property value type ### Enum values - Definition: Enum values for properties with an enum property value type - Format: Separate each enum value with a comma ### Number property value min - Definition: Minimum value of a property with number property value type ### Number property value max - Definition: Maximum value of a property with number property value type ### Number is integer - Definition: Denotes if a property with number property value type is an integer - Values: - `True`: Property is an integer - `False` or `<blank>`: Property isn't an integer ### Property type - Definition: User property type - Values: User property (required) ### Property name - Definition: Name of the user property - This value is required ### Property description - Definition: Description of the user property ### Property visibility - Definition: Set property visibility in charts - Values: - `VISIBLE`: Property is visible in charts - `HIDDEN`: Property is hidden in charts - `<blank>`: Retains the current value ### Property value type - Definition: The value type of a user property - Values: - `string` - `number` - `boolean` - `any` - `enum` - `const` ### Property is array - Definition: Denotes if the property is an array - Values: - `True`: Property is an array - `False` or `<blank>`: Property isn't an array ### Property regex - Definition: Regular expression (Regex) values for properties with a string property value type ### String property value min length - Definition: Minimum length of a property with string property value type ### String property value max length - Definition: Maximum length of a property with string property value type ### Additional fields in .CSV export of user properties The following list includes additional fields found in the .CSV export of your tracking plan’s user properties. #### Action - Definition: The default action to perform on a particular entity. This field exists in the import template, but the downloaded file automatically includes default values. - Values: - `Ignore`: The user property is unexpected, blocked, or deleted. - `<blank>`: The user property is planned or live. #### Property first seen - Definition: The date on which the property was first seen. - Format: `mm/dd/yyyy`. #### Property last seen - Definition: The date on which the property was last seen. - Format: `mm/dd/yyyy`. ## Common questions ### Export options for raw chart or event data These questions all have the same answer: - How do I export raw data for a chart or event? - Can I export the raw event data for the events included in this chart instead of the chart results? - How do I export a .CSV of all occurrences of a specific event? - How do I see the data that was pulled into this chart? - Can I see event and user property values for every instance of this event in the last 30 days? There's no way to export selected raw data for a chart or all data for selected events. Amplitude is built to perform large-scale, complex analyses inside the application, so isolating and exporting event data in a SQL-like manner isn't supported. A few alternatives: - **Export API**: to export all values of an event and its event properties, use Amplitude's [Export API](https://amplitude.com/docs/apis/analytics/export). It exports all events across a specified time range and returns them in JSON format. From there, you can extract the specific events you want. If your data exceeds the Export API size limit, use Amazon S3 Export instead. - **Amazon S3 Export**: integrate Amplitude with Amazon S3 to export your event data to an S3 bucket. This integration is available on all accounts, including the free plan. Refer to [Amazon S3 Export](https://amplitude.com/docs/data/destination-catalog/amazon-s3). ### How does Amplitude determine the structure of the .CSV file when exporting from an Event Segmentation chart? Amplitude uses the breakdown data table as a guide when creating the .CSV. Amplitude mirrors the format and structure of the table in the .CSV. ### Why isn't the .CSV file showing all the possible values of the user or event property? There are limits on the number of values that appear in a .CSV. The limits differ from chart to chart. Refer to [Limits and quotas](https://amplitude.com/docs/faq/limits-and-quotas#csv-download-limits). ### Why is the value of a user property different between the chart and the .CSV export? When you download users from the chart through Microscope, the .CSV contains the most recent property values for the user. The chart returns the property value at the time of the event. The same applies when the .CSV has property values listed as "none" in the chart: the .CSV shows the most recent value, while the chart shows the value at the time of the event. ### Why are there leading spaces (tabs) in my exported .CSV file? By default, leading empty spaces can appear in the cells of an exported .CSV. To change the default: 1. Go to _Personal settings_. 2. Go to _Profile_. 3. Enable **Always Remove Leading Spaces from Export** under _Site Settings_. Refer to [Manage your settings](https://amplitude.com/docs/admin/account-management/account-settings) for more. ================================================================================ # Integrate Jira with Amplitude Data URL: https://amplitude.com/docs/data/integrate-jira Updated: 2026-09-09 ================================================================================ # Integrate Jira with Amplitude Data Amplitude Data lets you integrate with Jira to quickly create new Jira issues whenever you make changes to a feature branch. You can only create issues from within the feature branch, and you can only associate changes with a Jira ticket. ## Set up the integration To set up and use the integration, follow these steps: 1. In Amplitude Data, navigate to _Settings > Integrations_ and find the Atlassian Jira panel. Click **Add**, and in the modal that appears, click **Authenticate** to start the authentication flow. 2. Another modal appears asking you to authorize Jira access for your site. From the drop-down in the modal, select the site you want to authorize. Then click **Accept**. ## Create a Jira issue in Amplitude Data To create a new Jira ticket from within Amplitude Data, follow these steps: 1. Create a feature branch and make your changes there. You can only use this integration from within a feature branch. 2. Your changes appear grouped by sources under the Home page. If you successfully integrate with Jira, you can create a Jira Issue for each source inside Amplitude Data. Click **+Jira** to create a new issue or link an existing issue to current changes. 3. To unlink an issue from your feature branch, hover over the issue tag and click **Unlink Jira**. In the modal that appears, click **Unlink** to confirm the unlink action. After you link an issue to a source, any subsequent published changes automatically leave a comment on the Jira issue. ================================================================================ # Manage access to sensitive data with Data Access Control URL: https://amplitude.com/docs/data/data-access-control Updated: 2026-09-22 ================================================================================ # Manage access to sensitive data with Data Access Control Data Access Control (DAC) restricts which users can access sensitive categories of event and property data, such as revenue data or personally identifiable information (PII), so unauthorized users can't view them. Enterprise organizations use DAC to classify this data and prevent inadvertent data leaks. > **Note:** Enable this feature > > Contact [Amplitude Support](https://gethelp.amplitude.com) to enable Data Access Controls for your organization. ## Plan availability Data Classification and Permissions (DAC) vary by plan. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details. | Plan | Data Classification | Permissions (DAC) | | --- | --- | --- | | Free | Not included | Not included | | Plus | Not included | Not included | | Growth | Not included | Not included | | Enterprise | PII, Revenue, Sensitive | Group | _Availability reflects the latest Amplitude plans. If your organization is on an older plan, your access may differ. Check your plan under [Plans & Billing in your organization settings](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._ ## How Data Access Control works DAC works within Amplitude's Groups framework. Admins grant or restrict access to PII, revenue data, and sensitive information for all members of a group. From there, admins can [add or remove users from these groups](https://amplitude.com/docs/admin/account-management/manage-permission-groups#edit-a-group) as access requirements change, either at the individual or organizational level. For example, when an unauthorized user tries to view a chart that includes restricted information, Amplitude blocks the chart from loading. Those users also can't create new charts that might include restricted data. This applies to charts, cohorts, dashboards, notebooks, and user sessions. > **Note:** > > Organization admins always have access to all data classifications, regardless of any DAC restrictions. When a user encounters a chart they can't view because of restricted data, Amplitude specifies the properties or cohorts that DAC blocked. The user can then exclude the restricted data and view the chart (or cohort, dashboard, notebook, or user session) without it. With DAC enabled, Amplitude hides classified properties from the Event Stream and User or Account lookup pages. When your project's users encounter classified data, Amplitude displays the value as `[DAC Restricted]`. The same restrictions apply to Ask Amplitude. ## Set access for specific categories of sensitive data Setting access levels is a two-stage process. First, classify your data. After that's complete, set up permissions. > **Note:** > > DAC applies only to properties. It doesn't apply to definitions or metadata. ### Classify properties 1. In Amplitude Data, go to _Properties_ and select the tab that contains the properties you want to classify. DAC lets you classify User, Event, and Group properties in your tracking plan, except for Amplitude ID, Version, Platform, Group ID, and Group name. > **Note:** Properties not eligible for classification > > Amplitude doesn't support classifying transformed properties or unexpected properties. > > Transformed properties inherit classification from their component properties. > > To classify an unexpected property, add it to your tracking plan. 2. Select the name of the property you want to classify. You can manage event, user, and group properties directly. Derived properties inherit all the classifications of their parent properties. 3. In the details panel that opens, select the **Classification** drop-down and choose all relevant classifications for this property. Then select **Send**. 4. Repeat steps 2 and 3 for each property you want to classify. > **Warning:** Classifying the User ID property > > If you classify `user_id`, users without access to that classification can't use [Event Explorer](https://amplitude.com/docs/analytics/charts/event-explorer). ### Set up permissions 1. Go to _Settings > Organization settings > Groups_ and select the name of the group you want to edit. You can also [create a new group](https://amplitude.com/docs/admin/account-management/manage-permission-groups#create-a-group). 2. Open the group's **Data Access** tab. Three controllable classifications appear here: PII, revenue, and sensitive. 3. For each classification, select **Yes** to allow members of the group to view this data, or **No** to deny access. 4. When you're done, select **Save**. ## Data Access Controls overview page > **Note:** > > This page is available to users with the Administrator role. Go to _Organization Settings > Data Access Controls_ to view the Data Access Controls overview page. There, find information about the following: - The number of groups with access to data classified as `PII`, `Sensitive`, or `Revenue`. - The number of users with access to data classified as `PII`, `Sensitive`, or `Revenue`. - All event, user, and group properties classified as `PII`, `Sensitive`, or `Revenue`. Drill into any cell in the table for a detailed view of the specific users or groups with access to each classification, or for more detailed information about the properties in each classification. Update user and group access from the Overview page, or go to _Data_ to update any property classification. Use the project switcher to view classifications for each project, and select **Classify Data** to open that project's tracking plan, where you can manually classify properties. To customize the error message that your internal users see when they try to access a restricted chart or cohort, select **Customize Restricted Access Message**. On the resulting modal, edit the error message and include any links to internal documentation that might help. > **Note:** > > When you customize the restricted message, the message applies to your organization, not just the project. ## Access request notifications Users who go to a restricted chart or cohort can contact an administrator in their organization to request access. Amplitude sends this request to all organization administrators. > **Note:** Turn off access request notifications > > Administrators can deselect the `Someone requests access to a property classified by Data Access Controls` notification in _Personal Settings > Notifications_ to opt out. ## Exports and subscriptions DAC enforcement applies to all exports and subscriptions in Amplitude: - If a user selects **Download Users** from the [microscope](https://amplitude.com/docs/analytics/microscope) in a chart, the CSV export excludes properties with classifications they can't access. - If a user tries to export a CSV from a dashboard, the export excludes charts they can't access. - If a user tries to export a PDF or PNG from a dashboard, the export obfuscates charts and cohorts they can't access. - If a user tries to subscribe to a chart they can't access, Amplitude cancels the subscription and the user doesn't get a notification or email. - If a user tries to subscribe to or create alerts for a dashboard, the email obfuscates the charts and cohorts they can't access. ## Manage classifications with the Taxonomy API The [Taxonomy API](https://amplitude.com/docs/apis/analytics/taxonomy) lets you manage classifications for all your properties at scale. ================================================================================ # Event and property descriptions URL: https://amplitude.com/docs/data/event-property-descriptions Updated: 2026-09-09 ================================================================================ # Event and property descriptions You can add or edit the description for an event or property to help other members of your organization understand what an event or property represents. > **Note:** > > This only applies to active events and properties included in your tracking plan. It also doesn't apply to custom events. ## Add a description to an event To add a description to an event, follow these steps: 1. Go to _Events_ and click the name of the event you want to add a description to. 2. In the flyout that appears, click **Add a description** (under _Details_). 3. Type a description of the event and click **Apply**. ## Add a description to an event property You can change the description for an event property in two ways. Because the same event property can apply to multiple event types, you can add a description for the global event property and for the specific event-to-event property pair. If the event property description specific to an event doesn't exist, the description defaults to the global event property description. - To change the description for an event property specific to an event, navigate to _Events_ and click the event name to open the _Details_ panel. Type a description where it says _Add a description_, and click **Apply** to save. - To change the global description for an event property, navigate to _Properties > Event Properties_ and click the event property name to open the _Details_ panel. Type a description where it says _Add a description_, and click **Apply** to save. ## Add a description to a user or group property You can change the description for a user property or a group property by navigating to _Properties > User Properties_ or _Properties > Group Properties_. Click the property name to open the _Details_ panel. Type a description where it says _Add a description_, and click **Apply** to save. ## AI-generated descriptions On paid plans, Amplitude generates suggested descriptions for events, event properties, and user properties. Suggestions appear in the description area of the details panel. Amplitude doesn't save the suggestion to the description automatically, and any existing description stays visible until you take action on the suggestion. ### Where descriptions come from Amplitude draws from two sources: - **Uploaded files**: Files you upload to a project under _Settings > AI Controls_, such as a data dictionary or a product spec. Amplitude treats these as the most authoritative source and prefers them over everything else. Refer to [file uploads](https://amplitude.com/docs/amplitude-ai/ai-controls#file-uploads) for details. - **Project data**: The project's own Amplitude data, including the event or property name, any existing description, how it's used across the project, and the values it takes. Amplitude only suggests a description it can trace back to one of these sources. An event or property with thin usage and no matching file gets no suggestion, because an empty description is more useful than a vague one. Only files scoped to a project describe that project's events and properties. Organization-level files support other Amplitude AI features but don't feed event or property descriptions. After you upload a file to a project, descriptions for that project refresh within a few minutes. #### Upload a data dictionary For the best results, upload a data dictionary to your project. A data dictionary is a document that lays out the project's taxonomy: its events, the properties on those events, and what each means. Amplitude relies on it more heavily than on anything it can infer from usage data alone, so projects with a data dictionary get noticeably better suggestions than ones without. Amplitude matches files to events and properties by name. A data dictionary row for `Order Placed` describes that event. For properties, type also matters. A row documenting a user property doesn't apply to an event property with the same name. ### Where suggestions appear Suggestions appear in two places: - **In Data**: Go to _Events_ or _Properties_ and select an event or property. The suggestion appears in the _Description_ field in the details panel. Suggestions never appear in the _Events_ or _Properties_ tables, only in the details panel. - **In chart dropdowns**: When you pick an event or property for a chart, the suggestion appears in the details panel next to the list. Some dropdowns are read-only. In those cases, accept or decline the suggestion from Data. ### Identify a suggestion A suggestion looks different from a manually written description: - Suggestions have a dotted underline. A description someone wrote doesn't. - Hovering over the underlined text opens a tooltip naming the source: the uploaded file it came from (all files, if more than one contributed), or "Amplitude charts, dashboards, and product metadata" when it came from the project's Amplitude data alone. - The appearance depends on what's already in the description field. With no existing description, the suggested text appears on its own. When the existing description is incomplete, Amplitude suggests text that fills the gap and keeps the original, adding the new part as a second paragraph. When Amplitude suggests a full replacement, it strikes through the current text and shows the replacement after it. ### Act on a suggestion To review a suggestion: 1. Select the suggestion to open an editor holding the suggested text. 2. Do one of the following: - Select **Apply** to accept the text as-is. - Edit the text, then select **Apply** to accept a modified version. - Select **Revert** to decline the suggestion and keep the original description. - Select **Cancel** to leave everything as-is for now. Once you accept or decline a suggestion, it doesn't come back. Amplitude already uses the suggested text for search and other AI features before anyone reviews it, so accepting confirms it rather than turns it on. Amplitude doesn't generate suggestions for events and properties it defines itself, for custom events, or for transformations. If an event property has an override on a specific event, Amplitude only suggests a description when that override has no description yet. Accepting writes the override, not the shared property description. ================================================================================ # Event and property display names URL: https://amplitude.com/docs/data/display-names-in-amplitude-data Updated: 2026-09-09 ================================================================================ # Event and property display names By default, an event's display name in Amplitude data matches the ingested name. These names can be difficult to read, understand, and incorporate directly into your analyses. To address this, you can give your events and user properties new display names that offer an easy-to-read description of their purpose and content. > **Note:** > > This only applies to active events and user properties added to your tracking plan, and doesn't apply to custom events. It changes the display name of the event or property within the Amplitude UI and doesn't change the raw data. ## Change the display name for an event You can update an event type's display name directly from the _Events_ screen. To do so, follow these steps: 1. Click **Events** in Amplitude Data’s left-hand rail. 2. Click the event name. 3. Type the new display name for the event. ## Change the display name for a user property You can update a user property's display name from the _User Properties_ tab on the _Properties_ screen. To do so, follow these steps: 1. Click **Properties** in Amplitude Data’s left-hand rail and open the **User Properties** tab. 2. Click the property name to open the details panel. 3. Click the property name in the panel and enter a display name. ## Update an event's visibility Hide events from appearing in areas of Amplitude where you don't want them. For example, you can hide noisy events from your user stream to make the data that appears more useful. Support for updating an event's visibility depends on the event type. | Event type | Editable? | Where to edit | | --- | --- | --- | | Default events | Must be in the tracking plan, and have `Modify` enabled. | Table menu, table row, side panel. | | Transformed events | Yes. Hiding from event streams isn't supported. | Side panel | | Live events | Yes | Table menu, table row, side panel. | | Planned events | No | | | Unexpected events | No | | | Blocked events | Yes | Table menu, table row, side panel. | | Deleted events | No | | To update an event's visibility: 1. Navigate to _Data > Events_. 2. Select the events you want to update. 3. In the menu that appears at the top of the table, click **Edit visibility** and select the areas where you don't want the selected events to appear. ================================================================================ # Event categorization URL: https://amplitude.com/docs/data/change-event-category Updated: 2026-09-09 ================================================================================ # Event categorization You can update an event type's category directly from the _Events_, _Custom Events_, or _Labeled Events_ tab. To do so, follow these steps: 1. Go to the _Events_ page and select the **Events**, **Custom Events**, or **Labeled Events** tab. 2. Click the checkbox next to the event name. 3. From the **Categorize** drop-down, select the category to which this event belongs. > **Note:** > > For events within _Events_, this only applies to active events included in your tracking plan. You can also change the event's category from the _Category_ column in the _Events_, _Custom Events_, or _Labeled Events_ tables, or from inside its right-hand fly-out panel. From a table, change the status from the _Category_ column's drop-down menu. Click the event name to open its _Details_ panel, then navigate to _Category_ and select the new category from the drop-down menu. ================================================================================ # Set an event's activity status URL: https://amplitude.com/docs/data/change-event-activity-status Updated: 2026-09-09 ================================================================================ # Set an event's activity status Setting an event's activity status to active or inactive tells Amplitude whether to count that event in metrics that track active users and active events. An active event is one the user actively engaged with, like clicking the Add to Cart button. An inactive event is one that happened to the user without any specific action on their part. Good examples include events like `Push Notification Sent` or `Message Received`. Setting an event as inactive removes that event from any dashboard metrics counting active users and active events. Users who only trigger inactive events don't count as active users for that day, though they do count towards Amplitude's new user definitions. > **Note:** > > When you change an event's activity status from active to inactive, Amplitude applies that change immediately and retroactively, so expect to see changes in your historical data. Inactive events still count against your event volume. To change the activity status, follow these steps: 1. Click the checkbox next to the event name. You can select more than one event to change the status of multiple events at once. 2. Click the **Edit Activity** drop-down menu. 3. Select the new event status. > **Note:** > > This only applies to active events and event properties included in your tracking plan. It also doesn't apply to custom events. You can also update the Activity status from the _Activity_ column in the _Events_ table, or the _Details_ flyout of a specific event. From the _Events_ table, change the status from the _Activity_ column's drop-down menu. Click an event's name to access the _Details_ flyout, and change the _Activity_ status from the drop-down menu. ================================================================================ # Property types URL: https://amplitude.com/docs/data/update-property-data-type Updated: 2026-09-01 ================================================================================ # Property types To change an event or user property's data type, for example from a string to a Boolean, open the property's details panel and select a new type from the _Type_ drop-down. Amplitude type-checks property values against the specified type and detects when event data doesn't match it, so update the type as your data and analysis needs change over time. To edit the data type of a user property, follow these steps: 1. Click the property's name to open the details panel. 2. Select the property's new data type from the _Type_ drop-down. Options include: - `String`: A string value. - `Number`: Numerical values (like 12345). - `Boolean`: Values representing Boolean states ("true" / "false", "yes" / "no", "0" / "1"). - `Array`: A collection of values stored in a single property (for example, \["apple", "banana", "strawberry"\] or \[1, 2, 3\]). - `Enum`: One of a set of possible values (for example, property fruit is one of \[apple, banana, strawberry\]). - `Const`: A constant value. - `Any`: Any value. ================================================================================ # Override a property definition URL: https://amplitude.com/docs/data/override-property Updated: 2026-09-09 ================================================================================ # Override a property definition Overriding property details is helpful when you want to customize the property for a specific event or property group, without updating the original version or creating an entirely new event property. Each property in the properties table represents the original version, which can be shared across multiple events and property groups. Amplitude Data applies changes to the details of any property to all events and property groups that share the original details. When you override a property on an event or property group, any changes to that property apply only to that event or property group. ## Override a property To override a property on a specific event, follow these steps: 1. Navigate to the _Events_ table and click an event's name. 2. In the event details panel that opens, navigate to _Details > Properties_. Then click the property you want to override. 3. In the event property details panel that opens, click **Override**. A message confirms that any changes to the property apply only to that event. To override a property on a property group, follow these steps: 1. From within _Properties_, open the **Event Properties** tab to view the event properties table. 2. Click **Property Groups** to switch to the property groups table view. Then click a property group name. 3. In the property details panel that opens, navigate to _Details > Properties_, and click the property you want to override. 4. In the event property details panel that opens, click **Override**. > **Note:** > > Any changes to a property that's overridden on a property group apply to all events that use that property group. You can always [revert an overridden property](https://amplitude.com/docs/data/override-property) when you no longer need the override. ================================================================================ # Revert an overridden property definition URL: https://amplitude.com/docs/data/revert-overridden-property Updated: 2026-09-09 ================================================================================ # Revert an overridden property definition Reverting an [overridden property](https://amplitude.com/docs/data/override-property) to its original version is a quick way to retroactively clean up your tracking plan and maintain consistency across your event properties. Doing so tells Amplitude Data to update the property to match the latest state of the original version listed in the event properties table. After reverting, any changes to the property also apply to any events or property groups that use the original version of that property. ## Revert an overridden property To revert an overridden property on a specific event, follow these steps: 1. Navigate to the _Events_ table and click an event's name. 2. In the event details fly-out, navigate to _Details > Properties_ and click the event property you want to revert. 3. In the event property details panel that opens, click **Manage Override**. 4. From the dropdown menu that opens, select **Revert To Original**. > **Note:** > > Event rows that include "via property group…" appear in the list because those events use a property group that includes this event property. Reverting the property on any one of those events reverts the property on all of them. To revert an event property on a property group, follow these steps: 1. From within _Properties_, open the **Event Properties** tab to open the event properties table. 2. Click **Property Groups** to switch to the property groups table. Then click a property group name. 3. In the property group details panel, navigate to _Details > Properties_ and click the property you want to revert. 4. In the event property details panel, click **Manage Override**. 5. From the dropdown menu that opens, select **Revert To Original**. > **Note:** > > To see how the details change after a revert before starting the process, click **Compare To Original**. The original values appear under any overridden values. Turn off this view by clicking _Manage Override > Hide Comparison_. To review and revert any overrides for a specific property, follow these steps: 1. From within _Properties_, open the **Event Properties** tab to open the event properties table, and then click a property name. 2. In the event property details panel, open the **Used By** tab. Any events or property groups labeled as overridden use an overridden version of that event property. 3. Hover over the overridden event or property group row you're interested in and click the three-dot icon on the right. 4. From the dropdown, select **Revert To Original**. You can bulk revert all overrides from the _Used By_ tab. Click **Manage**, and a modal opens that lets you review and bulk revert your overrides. ================================================================================ # Using property groups URL: https://amplitude.com/docs/data/property-updates-property-groups Updated: 2026-09-01 ================================================================================ # Using property groups A property group bundles a set of event properties into one reusable unit, so you can add all of them to an event in a single step instead of adding each property individually. When you update the group, Amplitude Data applies the change to every event that uses it, which keeps complex tracking plans consistent without manual edits to each event. Use property groups when you want to add the same set of properties to many events without repeating the setup on each one. To track properties about a business entity, like an account, rather than an event, use group properties instead, a distinct feature under _Data > Groups_. For example, a music app's tracking manager might need a way to streamline creation of events relating to songs. Each of these events includes the following properties: - `albumName` - `artistName` - `genre` - `recordLabel` - `releaseDate` - `songDuration` - `songTitle` Instead of individually adding properties to every one of these events, the tracking plan manager can add these properties to their own property group. Whenever they create a new song-related event that includes these properties, they only have to add the entire group to the event. Another benefit is that whenever they edit or update a property (but not a property value), that edit carries over to all events that include the group to which the property belongs. For example, imagine the tracking manager wants to change the `recordLabel` property from a text string to a numeric code to align with a standardized database of record labels. As soon as they make the change in Amplitude Data, that property updates for every event that uses the `Songs` property group. Using property groups also makes sure you use the same iteration of a property with your events. In Amplitude Data, you can have multiple iterations of a property, which can sometimes be confusing when adding properties to events. ## Create a property group To create a property group, follow these steps: 1. Navigate to _Properties > Event Properties_ and click **Property Groups**. 2. Click **+ Create property group**. 3. In the flyout window, enter a name for the group. Then add a description and any tags, if needed. 4. Click **+ Add property** to begin adding properties to this property group. 5. Select an event property from the dropdown menu. You can either scroll until you find it, or you can begin typing its name in the search box until it appears. 6. Repeat the previous step until you've added all the properties you want to include in the property group. Amplitude saves your progress automatically. ## Add a property group to an event To add a property group to an event, follow these steps: 1. In _Events_, click the name of the event you want from the list. The event's flyout window opens. 2. In the _Details_ tab, find the _Properties_ section and click **+ Add property**. 3. In the dropdown list that appears, any existing property groups appear first. Find the one you want and click it. If any property in the group already exists as a direct property on the event, Amplitude Data shows a confirmation dialog listing the affected properties and events. Confirm to remove the direct mappings and serve those properties through the group instead. The properties stay live on all affected events. This is a reorganization, not a deletion. To modify the properties for a property group, follow these steps: 1. Navigate to _Properties_ and click **Property Groups**. 2. Scroll until you find the group you want to modify and click it. Its flyout window appears. 3. Make your changes. The changes apply across all events or sources. If you add a property to the group that already exists as a direct property on an event that uses this group, Amplitude Data shows a confirmation dialog listing the affected events. Confirm to remove the direct mapping and serve the property through the group instead. > **Note:** > > This only applies to active events and event properties included in your tracking plan. It also doesn't apply to custom events. ================================================================================ # Cross-project analysis with Portfolios URL: https://amplitude.com/docs/data/cross-project-analysis Updated: 2026-09-09 ================================================================================ # Cross-project analysis with Portfolios Amplitude Data's portfolio feature lets you create cross-product analyses by combining multiple source projects into a single view. With this feature, you can create portfolios in Analytics and build charts using data aggregated across all the source projects in your portfolio. To learn more, refer to [Portfolio: Conduct cross-project analysis in Amplitude](https://amplitude.com/docs/admin/account-management/portfolio). Portfolios managed in Amplitude Data behave differently from legacy portfolios managed in the Govern section of Amplitude Analytics. Legacy portfolios didn't let users rank source projects, or show event or property metadata from the source projects in the portfolio by default. This article covers portfolios editable only from within Amplitude Data. Portfolios you manage in Analytics or Data return the same aggregated data when queried through charts. > **Note:** Portfolio project limits > > Portfolios support up to five projects. If your use case requires more, contact your account team to unlock up to 10 projects in a portfolio. ## Create a portfolio To create a portfolio in Amplitude Data, follow these steps: 1. From the project selector in Amplitude Data, select **+Create new Portfolio**. 2. In the modal that appears, name your portfolio and select the projects to include. When you're done, select **Next**. 3. Next, rank the schemas of the source projects you included. Ranking handles instances where Amplitude Data encounters conflicts or differences in the schemas. The order in which you rank them determines which schemas Amplitude Data regards as the source of truth. If an event or property name exists in multiple source projects, Amplitude Data uses and displays the metadata from the prioritized project in this portfolio. To rank the schemas, drag the project names into your preferred prioritization order. > **Note:** > > The metadata for an event or property from the source project (description, category, display name, activity, visibility) is in the Data-managed portfolio by default. 4. Select **Create Portfolio** to finish the creation process. Customize events and property metadata in the portfolio. You can customize event and property metadata in your portfolio by using an [override](https://amplitude.com/docs/data/override-property). ## Import existing portfolios into Amplitude Data You can import existing Analytics-managed portfolios into Amplitude Data. To do so, select the project selector and find the portfolio you want to import, either by searching for it or locating it under "Projects (managed in Analytics)". After Amplitude imports your portfolio, you can view the existing aggregated list of events and properties. > **Note:** > > Amplitude Data creates overrides in the imported portfolio for all events and properties. This approach maintains the existing schema for users of the Analytics-managed portfolio. ================================================================================ # Data Assistant Overview URL: https://amplitude.com/docs/data/use-ai-data-assistant Updated: 2026-09-22 ================================================================================ # Data Assistant Overview A clean, organized tracking plan helps you get the most value from Amplitude Data. When you have hundreds or thousands of events and properties, maintaining the plan can be difficult, especially when identifying what to fix in messy data. Amplitude's AI Data Assistant helps you maintain your tracking plan by showing a short list of suggested modifications whenever you visit the Data home page. Amplitude's internal AI generates these suggestions automatically. Any changes you apply through Data Assistant post directly to your tracking plan, with no other action required. ## Plan availability Data Copilot, AI-powered suggestions, and Automation vary by plan. Some features need a higher plan or an add-on. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details. | Plan | Data Copilot | AI-powered suggestions | Automation | | --- | --- | --- | --- | | Free | Basic recommendations + limited AI | Limited | Not included | | Plus | Adds limited automation + Observability | Limited | Limited Use Cases | | Growth | Unlimited AI recommendations | Included | Limited Use Cases | | Enterprise | Full Automation Workflows | Included | Included | Automated tasks is available on the Enterprise plan. DC: Guidance is available on all plans. _Availability reflects the latest Amplitude plans. If your organization is on an older plan, your access may differ. Check your plan under [Plans & Billing in your organization settings](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._ ## Update your tracking plan with Data Assistant To update your tracking plan using Data Assistant, follow these steps: 1. Open Amplitude Data. Data Assistant appears at the top of the home page, displaying a list of top suggestions. Data Assistant prioritizes suggestions based on their expected impact on your overall data health, surfacing the most critical issues first. For example: - If your project is close to the limit on the number of event types, a suggestion to clean up events surfaces as a critical issue, since exceeding the limit can make new event types unqueryable. - If high-volume events get heavy query traffic but have unclear names or meanings, Data Assistant may propose descriptions that help users and AI understand those events better. 2. Click a suggestion to expand it. The suggestion expands directly below, where you can see the proposed changes in detail. The action label describes the suggestion type, such as _Review deletions_ or _Review descriptions_. 3. In the expanded suggestion, you can: - Modify the proposed action before applying it, such as editing the proposed description or category. - Click **Approve** to accept the suggestion and apply the change to your tracking plan. - Click **X** to dismiss the suggestion. Dismissals apply for 90 days to everyone in the organization. 4. To take action on multiple items at once, use the bulk action controls at the bottom of the expanded suggestion. For more detail on why Data Assistant made a specific suggestion, hover over the Info icon. ## Detect semantically similar events Data Assistant detects events that are semantically similar, such as `Order Placed` and `Completed Purchase`, which people and AI find hard to tell apart. When it finds these events, it suggests one of two fixes: merge the events with a transformation, or draft descriptions that clarify how each event differs from the other. For Amplitude's AI-generated descriptions feature, which suggests descriptions for individual events and properties in the details panel, refer to [AI-generated descriptions](https://amplitude.com/docs/data/event-property-descriptions#ai-generated-descriptions). ## Use Data Assistant interactively Beyond the suggestions panel on the Data home page, you can work with Data Assistant interactively through Global Chat or by creating an Agent in the _Agents_ section. In a single conversation, you can ask your own questions, run custom audits, and act on the results. You can apply bulk actions to as many as 1,000 items at once, and you can dismiss any suggestions you don't want to act on. ## Automated tasks in Data Assistant Data Assistant provides automated tasks to help you clean up your data. Automated tasks let data governors define conditions and actions that the system performs automatically. Automated tasks automate repetitive clean-up workflows by turning Data Assistant recommendations into automatic actions. For more information, go to [Automated Tasks](https://amplitude.com/docs/data/automated-tasks-in-data-assistant). > **Note:** > > Data Assistant is one of several AI tools in Amplitude. For analytics insights, chart creation, and natural-language data exploration, refer to [Global Agent](https://amplitude.com/docs/amplitude-ai/global-agent-overview). For automated dashboard analysis and session replay insights, refer to [AI Agents](https://amplitude.com/docs/amplitude-ai/setup-and-onboarding). ================================================================================ # Automated Tasks URL: https://amplitude.com/docs/data/automated-tasks-in-data-assistant Updated: 2026-09-22 ================================================================================ # Automated Tasks Automated Tasks are part of Amplitude's [Data Assistant](https://amplitude.com/docs/data/use-ai-data-assistant) feature. Automated tasks let data governors define conditions and actions that Amplitude then performs automatically. Automated tasks turn Data Assistant recommendations into automatic actions and streamline repetitive clean-up workflows. For example, an automated task can delete events that have gone unused for 90 days. After you create an automated task, it runs daily. > **Note:** > > Automated tasks are only available to users with manager or admin permissions. Contact your administrator if you can't access Automated tasks as an option for Data Assistant. Access your automated tasks from the Data Assistant by going to _Data > Assistant > Automated Tasks_. If you have active automations, Amplitude displays them with a current count of the affected events. If you don't have any active automations, you can create one. By default, automated tasks operate across all projects within a workspace. You can specify for the automation to only search through a single project. ## Plan availability Automation varies by plan. Some features need a higher plan or an add-on. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details. | Plan | Automation | | --- | --- | | Free | Not included | | Plus | Limited Use Cases | | Growth | Limited Use Cases | | Enterprise | Included | Automated tasks is available on the Enterprise plan. _Availability reflects the latest Amplitude plans. If your organization is on an older plan, your access may differ. Check your plan under [Plans & Billing in your organization settings](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._ ## Types of automated tasks You can select any of the following types of tasks to automate: - Clean up stale events. - Clean up single-day events. - Clean up unused events. Cleanup extends beyond events. Data Assistant also cleans up broken or no-longer-useful event, user, and group properties, so you can keep your entire tracking plan tidy, not just its events. When Data Assistant identifies cleanup candidates, you choose how to act on them. You can schedule them for deletion, which starts the 30-day notice period that the following sections describe, or you can delete them immediately. ### Clean up stale events This task removes events that haven't had any recent volume. Low volume indicates that Amplitude isn't ingesting the events and they're no longer of value. The task inspects your organization for events that have a `last seen` date within a configurable number of days. For example, events that haven't been ingested in 90 days. When the automated task finds events that match those criteria, it schedules them for deletion. Amplitude notifies all people using those events through email or Slack about the impending deletion. Anywhere the events appear (for example, in a chart), a banner notifies users about the upcoming deletion. If anyone wants to keep the event, they can do so through the email or banner notification. If no one elects to keep the event within 30 days, Amplitude deletes the event. The 30-day timeframe to delete events isn't configurable. Deleted events no longer appear in the event drop-down menu, and Amplitude blocks them from future ingestion. Historical charts and data aren't affected. ### Clean up single-day events This task removes accidental or one-time test events that can negatively affect or clutter your taxonomy. The task inspects your organization for events that: - Have the same first seen and last seen dates. - Have that date more than a configurable number of days before the inspection date. For example, 90 days before the inspection date. When the automated task finds events that match those criteria, it schedules those events for deletion. Amplitude notifies all people using those events through email or Slack about the impending deletion. Anywhere the events appear (for example, in a chart), a banner notifies users about the upcoming deletion. If anyone wants to keep the event, they can do so through the email or banner notification. If no one elects to keep the event within 30 days, Amplitude deletes the event. The 30-day timeframe to delete events isn't configurable. Deleted events no longer appear in the event drop-down menu, and Amplitude blocks them from future ingestion. Historical charts and data aren't affected. ### Clean up unused events > **Tip:** Manually enabled > > The Clean up unused events automated task can affect events that you want to keep. The task must be manually enabled for each account. Reach out to your Amplitude representative or [Amplitude Support](https://gethelp.amplitude.com/hc/en-us/requests/new) for more information or to get this task enabled. This task optimizes your event volume by making sure that all your ingested events are actively used. The task inspects your organization for events that haven't been queried in 90 days. When it finds those events, it can notify you about them, schedule those events for deletion within 30 days, and notify you when Amplitude deletes them. Your users can save events through the notification from the automated task or through the Data Assistant. Amplitude doesn't delete saved events, even if no one queries them during the time window. If the task deletes an event, the deletion also blocks future ingestion of that event. Any data that Amplitude doesn't collect because of an event's deleted status isn't recoverable. Historical charts and data aren't affected. The deleted event still appears in them. You can manually recover a deleted event at any time. ## Set up an automated task You can manually set up an automated task. Alternately, the [Data Assistant](https://amplitude.com/docs/data/use-ai-data-assistant) can proactively identify tasks for you. ##### To manually set up an automated task 1. Go to _Data > Assistant > Automated Tasks tab_. 2. Click **Get Started**. 3. Complete the set up prompts. This includes: - Setting the threshold (in days). By default, the threshold is 30 days for single-day events and 90 days for stale events. - Specifying any event tags that the automation rule should ignore. For example, if you never want to remove creation events, add a `create` tag to the ignore field. Review your events to make sure you specify the exact tag applied to your event. 4. Click **Set Up Automation**. ##### To set up an automated task through the Data Assistant If Amplitude detects events that meet a task's criteria, those suggested tasks appear in the Suggestions view under _Data > Assistant_. If automation is available for that task, a banner appears above the suggestion. Click the banner to turn on automation for future matching events. Amplitude takes you to the window to complete the task set up. ## Remove an automation You can remove any current automation. When removing an automation, you can specify whether you want to affect any pending changes or to only affect future changes. ##### To remove an automated task 1. Go to _Data > Assistant > Automated Tasks_. 2. Click **View Automation**. 3. In the automated task window, click the **three-dot** option menu. 4. Click **Remove Automation**. 5. Confirm whether you want to also remove any pending changes from the task, then click **Remove**. ## Recover deleted events You can recover any deleted event at any time. ##### To recover a deleted event 1. Go to _Data > Events_. 2. Click **Deleted Events**. 3. Select the event you want and click **Restore**. ================================================================================ # Remove invalid or incorrect data URL: https://amplitude.com/docs/data/remove-invalid-data Updated: 2026-09-22 ================================================================================ # Remove invalid or incorrect data To remove invalid or incorrect data from your Amplitude analyses, use one of four Amplitude Data methods: create a drop filter, create a block filter, block events and properties, or delete events and properties. Drop filters hide events from queries and stay reversible. Block filters and blocking stop Amplitude from ingesting matching data going forward. Deleting removes an event or property from your plan but keeps historical data. Data is immutable after ingestion, so none of these methods change data that Amplitude already stored. To permanently delete data, use [Amplitude's self-service data deletion feature](https://amplitude.com/docs/admin/account-management/self-service-data-deletion-in-amplitude). ## Plan availability Drop, Block, and Delete is available on all plans. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details. _Availability reflects the latest Amplitude plans. If your organization is on an older plan, your access may differ. Check your plan under [Plans & Billing in your organization settings](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._ ## Create a drop filter You may find you've loaded incorrect data and want to filter it out from queries. Amplitude Data's drop filters feature lets you remove specific event data from your charts at query time. Amplitude doesn't delete these events, and you can restore them to your charts by editing or deleting the drop filter. Drop filters don't apply to data exports. > **Note:** > > As query-side filters that aren't applied during data ingestion, drop filters don't affect your event volume limit. To create a drop filter, follow these steps: 1. Make sure you're on `main`, as filters aren't accessible from any other branch. 2. In the left-hand sidebar, click **Filters**, then select the **Drop Filters** tab. 3. Click **+ Create Drop Filter** to open the Filter Configuration fly-out panel. 4. Click **Select event ...** to choose the event you want to filter on. 5. Optionally, click **+ where** to include any relevant properties that refine your filter. For example, perhaps you want to filter out all purchase events that come from a specific geographical location. Select that location from the list of properties and set the evaluation to `is not equal`. 6. Specify the time range for the events you want Amplitude Data to drop-filter out. 7. When you're ready, click **Drop Data** to initiate the drop filter. To edit or delete a drop filter, click its name in the drop filter list. In the fly-out panel that appears on the right, make your edits and click **Update Drop Filter**. > **Note:** Drop filter details > > Note the following about drop filters: > > - Drop filters don't affect event streams. > - You must use the same operator across all selected properties. > - You can mix and match event and user properties. > - You can have a maximum of three properties. > - You can't use any property more than once. ## Create a block filter Block filters let you stop data ingestion for events and properties that you specify based on criteria you define. Blocking Amplitude from ingesting data can help when you need to act quickly before you update your code. Block filters let you: - Block events based on an event property or Amplitude property. For example, events from a specific data source. - Block events from a specific IP address or set of IP addresses. Use this to block traffic from a test server or bad actor. - Block events from a specific version of your application to help find and fix instrumentation issues. - Block event or user properties that start with a particular string, or properties with numeric names to help uncover instrumentation issues. - Block bot traffic from websites. When you add or remove a block filter, allow up to 10 minutes for the change to take effect. As soon as the filter is active, it blocks Amplitude from ingesting matching data. > **Warning:** > > Amplitude doesn't collect data for blocked events or properties. As a result, you can't recover information about blocked data at a later time, because Amplitude never ingests it. If you think you may need data at some point in the future, consider hiding the event or property instead. To create a block filter: 1. Make sure you're on your project's `main` branch in Data. 2. Click **Filters** in the side navigation. 3. Click **+ Create Block Filter**. 4. Specify the project and data type (Events, Event properties, User properties, or Bot traffic). If applicable, use the available filtering parameters. 5. Click **Block Data** to initiate the block filter. ### Block events based on property values Block events based on the value of up to three event properties. When you block events based on property values, Amplitude compares your filter against the raw stringified values sent to Amplitude. Knowing the data type is important in the following scenarios: - Boolean values: If you send a property as `true` or `false`, Amplitude displays the value as "True" or "False". To use this in a Block filter, specify the exact value sent as a string. In this case, `true` or `false`. - Array values: Amplitude splits arrays into separate values for querying. Block filters compare against the stringified raw value. To find raw property values, use the [Event Explorer](https://amplitude.com/docs/analytics/charts/event-explorer) to view an example of the event you want to block. ### Block events and properties from your plan Create Block filters from your Events or Properties list. 1. Make sure you're on your project's `main` branch. 2. In Data, navigate to the Events or Properties tab. 3. Select the Events or Properties you want to block. 4. After selecting, click **Block** to create the filter, and confirm the block. 5. To unblock a blocked event, repeat the previous steps and click **Unblock**. > **Note:** > > Custom events are a virtual grouping of your ingested events and aren't blockable. Instead, block the individual events that make up the custom event. ## Block events and properties You can prevent Amplitude Data from ingesting data on a specific event, event property, or user property by blocking it. Amplitude Data immediately stops processing data for that event or property until you decide to unblock it. > **Warning:** > > Because Amplitude Data doesn't ingest any data for blocked events or properties, you can't recover any information about them at any future date. If you don't want to display a specific event or property but think you may someday need this data, consider hiding the event or property instead. To block an event or property, follow these steps: 1. Make sure you're in the `main` branch. You can only block events and properties from there. 2. Navigate to _Events_ or _Properties_, depending on which one you want to block. 3. Find the event or property you want to block and click the checkbox next to its name. 4. If blocking an event, click the **Block** dropdown menu, and choose either **Block now** or **Schedule for blocking**. If blocking a property, click **Block**. 5. A confirmation modal appears. If you still want to block the event or property, click **Block**. 6. To unblock a blocked event, follow steps 1-5 and click **Unblock** instead of **Block**. > **Note:** > > You can't block custom events. ## Delete events and properties in Amplitude Data If you ingest events or properties that you no longer need, you can delete them from your plan. When you delete an event or property, Amplitude blocks it from future ingestion and removes it from chart dropdowns to prevent future querying. The event or property doesn't count toward your monthly event volume or instrumentation limit. Deleting an event or property doesn't remove historical data. Charts that reference a deleted event load with data from before you deleted the event and indicate the event is deleted. Deleted user properties still appear on events that are already ingested, and you can still see them in historical user stream data. To delete an event or property: 1. Navigate to the Events or Properties section of Amplitude Data. 2. Find the events or event properties you want to delete and click the checkboxes next to their names. 3. Click **Delete**. 4. Complete the verification modal. You can undelete a deleted event or property. 1. From the status filter dropdown, select **Deleted** to find your deleted events or properties. 2. Find the items you want to restore and click the checkboxes next to their names. 3. Click **Restore**. ## Delete an entire user To delete a user entirely, use the [User Privacy API](https://amplitude.com/docs/apis/analytics/user-privacy). This API lets you delete a user, their events, and any associated data, and helps you keep compliant with data laws and regulations. ================================================================================ # Block bot web traffic URL: https://amplitude.com/docs/data/block-bot-traffic Updated: 2026-09-18 ================================================================================ # Block bot web traffic To block bot traffic in Amplitude, create a block filter for bot traffic. Amplitude then stops ingesting events from crawlers, scrapers, and similar tools, which matters if you track events on public, unauthenticated websites where bot traffic can skew your metrics. ## How bot blocking works Amplitude blocks bot traffic based on User-Agent, as identified by the [IAB/ABC International Spiders and Bots List](https://www.iab.com/guidelines/iab-abc-international-spiders-bots-list/). Blocking applies by default to data sent through the [legacy JavaScript SDK](https://github.com/amplitude/Amplitude-JavaScript) or the [TypeScript Browser SDK](https://github.com/amplitude/Amplitude-TypeScript/tree/main/packages/analytics-browser) (version 1.10.0 and later). You can also provide the `user_agent` field directly on events sent through the HTTP API or Batch API. `user_agent` must be a top-level field in the payload. The bot filter doesn't evaluate an event property or user property named `user_agent`. Be careful when doing this, because the value must represent a valid browser or Amplitude drops the event. You can't recover data that a block filter removes, because Amplitude never ingests it. ## Create a block filter for bot web traffic To create a block filter for bot web traffic, follow these steps: 1. Make sure you're on `main`. Filters aren't accessible from any other branch. 2. In the left-hand sidebar, click **Filters**, then select the **Block Filters** tab. 3. Click **+ Create Block Filter** to open the Filter Configuration fly-out panel. 4. Select **Bot Traffic** from the **Block** drop-down. 5. When you're ready, click **Block Data** to start the block filter. ================================================================================ # Change the description of an event or property URL: https://amplitude.com/docs/data/change-event-description Updated: 2026-09-09 ================================================================================ # Change the description of an event or property You can change the description for an event to help other members of your organization understand what an event represents. To do so, follow these steps: 1. Click the event name to open the fly-out panel on the right side. 2. Click the **Description** field. 3. Type in a description of the event. You can change the description for an event property in two different ways. Because the same event property can apply to multiple event types, you can either add a description for the original event property, or for an event property overridden for a specific event or property group. If no override exists, the description defaults to the global event property. > **Note:** > > Event properties that aren't overridden share the same original event property details. To change the description for an overridden event property specific to an event, follow these steps: 1. Navigate to the _Events_ table and click the event name. 2. In the event details panel that opens, navigate to _Details > Properties_, then click the property you want to update. 3. Make sure the event property is overridden. If it is, _Manage Override_ appears in the blue box within the details panel, and you can skip to step 4. Otherwise, click **Override** to apply the change only to a specific event or property group. 4. Click the field directly below the property name and type in a description of the property. To change the original description for an event property, follow these steps: 1. Navigate to _Event Properties_ and click the property you want to update. 2. In the event property details panel that opens, click the field and type in a description of the property. On paid plans, Amplitude can also suggest descriptions automatically. Refer to [AI-generated descriptions](https://amplitude.com/docs/data/event-property-descriptions#ai-generated-descriptions) for details. ================================================================================ # Fix your data with transformations URL: https://amplitude.com/docs/data/transformations Updated: 2026-09-22 ================================================================================ # Fix your data with transformations Transformations rewrite event data at query time to correct instrumentation mistakes without touching your code. They apply retroactively across all historical data, so a single rule fixes affected events both before and after you create it. Common fixes include merging duplicate events, consolidating property names, renaming property values, and hiding values from the UI. Use a transformation when you need to fix data retroactively across historical and future events without redeploying instrumentation. Use a custom event instead when you want to group existing events into a new analytical event while keeping the originals queryable. You can only create transformations on a project's `main` branch with the **Show transformations** toggle set to `ON`, and you can't transform Amplitude's default user properties. > **Note:** > > Transformations occur at query time when a chart or cohort generates results. This doesn't affect the raw data. Transformations don't affect raw data on Snowflake or Redshift. ## Plan availability Transformations is available on all plans. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details. _Availability reflects the latest Amplitude plans. If your organization is on an older plan, your access may differ. Check your plan under [Plans & Billing in your organization settings](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._ ## Merge events, event properties, and user properties Many Amplitude users need to merge superfluous or duplicate events, event properties, or user properties. Transformations make this process easy. ### Merge events This transformation lets you merge events together. Use it if you're tracking two or more events that you want to track as one single event instead. For example, you can merge the events `comment_reply_like` and `comment_share` into a single event, `comment`. When merging events, you can also add a property that helps distinguish between the two original events after you merge them. This transformation can help if you're logging data into two events with similar syntax when you could log this information as one event with different property values instead. For example, you could transform the events `comment_reply_like` and `comment_share` into one event, `comment`. The event `comment` then has a new event property `comment type` with values `reply like` and `share`. To merge events, follow these steps: 1. In Amplitude Data, navigate to _Events_. 2. Find the events you want to merge together and click the checkbox next to their names. 3. After you've selected the events, the _Transform_ option appears in the menu bar above the events list. Click **Transform**. 4. Choose whether you want to merge the events you selected into a single event, or into a single event with an extra distinguishing property. Then click **Next**. 5. Use the dropdown in the _Transform & Merge Events_ modal to tell Amplitude Data whether you want to merge the selected events into a new event, or whether you want to merge them into a different, already existing event. If you're merging into a new event, name it here. Then click **Preview**. 6. In step 5, if you aren't adding the extra distinguishing property to your merged event, skip to step 9. Otherwise, select the event property you want to use as a differentiator from the _Select Property_ dropdown. Then click **Next**. 7. Next, map the events you selected with new values for the property you selected. Enter the new value in the _Property Value…_ field and click **Preview**. 8. Review your changes and click **Merge** to complete the transformation. ### Merge event properties or user properties This transformation lets you merge properties, either for events or for users. Use it if you have two properties that track the same information but use different naming syntax. For example, imagine you call an event property `title` in some cases, and `TITLE` in others, even though they represent the same thing on all events. You can clean things up by transforming `title` and `TITLE` into `Title`, combining the data. Similarly, you might call a user property `name` in some cases and `NAME` in others, even though they represent the same thing for all users. Transforming `name` and `NAME` into `Name` resolves any potential confusion. You can merge event properties only with other event properties, and user properties only with other user properties. To merge event properties or user properties, follow these steps: 1. In Amplitude Data, navigate to _Properties_, then click either the **Event** or **User** tab, depending on which type of properties you want to merge. 2. Find the properties you want to merge together and click the checkbox next to their names. After you've selected the event properties, the _Transform_ option appears in the menu. 3. From the _Transform_ dropdown, select **Merge Property**. 4. The _Merge Properties_ modal appears. Type a new event property name or type the name of the event property you want to merge the selected event properties into. Click **Next**. 5. Review your changes and click **Merge** to complete the transformation. ## Rename property values This transformation lets you reassign event and user property values. Use this transformation if a property has misspellings or nonsensical values in dropdowns. It lets you hide them from the UI or turn them into another value. For example, you can reassign the values of `true` and `TRUE` to `True`. To rename a property value, follow these steps: 1. Navigate to _Properties_ and open either the **Event** or **User** tab, depending on the type of property you want to rename. 2. Find the property with the property value you want to rename and click the checkbox next to its name. 3. From the _Transform_ dropdown, select **Rename Value**. 4. The _Edit Renamed Values_ modal appears. Under _Current Property Value_, click **Select value(s)...**. 5. From the list, select the value you want to rename and click **Apply**. 6. Under _Derived Value_, click **Select value...** to set a new value. 7. Click **New Value** and enter the new value in the field that appears. 8. Repeat steps 4 through 7 for every value you want to rename. Then click **Next**. 9. A confirmation modal appears. Click **Rename**. ## Hide property values Setting a property value's visibility status to hidden is helpful for values you want to track but don't want to appear on the dashboard in any charts. Hiding a property value doesn't delete its raw data, and the value is still visible in the user's individual event stream. To hide a property value, follow these steps: 1. Find the event or user property with the value you want to hide. Check the box next to its name. 2. From the _Transform_ dropdown, select **Hide Values**. 3. Select the value or values you want to hide from Amplitude and click **Next**. 4. A confirmation modal appears. Click **Hide**. ## Edit and delete transformations Transformations aren't permanent. You can reverse them, and you can edit or delete them at any time. To edit your transformation, follow these steps: 1. Find the transformed event, event property, or user property you're interested in. 2. Click the transformation's name to open the details panel. Click **Transformed Values** to see the transformations tab. 3. Click **Edit** next to the transformation you want to edit, make the necessary changes, and save. To delete your transformation, follow these steps: 1. Find the transformed event, event property, or user property you're interested in. 2. Click the checkbox next to the transformation you want to delete. 3. Click **Undo Transformation**. 4. A confirmation modal appears. Click **Undo Transformation**. Deleting a transformation doesn't delete the original events. ## Use transformed properties for targeting Amplitude makes transformed user properties available as targeting criteria in Experiment, Feature Flags, and Guides & Surveys. At evaluation time, Amplitude applies your project's transformation configuration before evaluating targeting rules, so the same merge and rename rules that clean up your Analytics data also govern targeting and exposure. You don't need to reimplement transformation logic in your SDK or backend. Define the rules once in Amplitude Data and they apply consistently across Analytics, Experiment, Feature Flags, and Guides & Surveys. For more details, refer to [Remote evaluation](https://amplitude.com/docs/feature-experiment/remote-evaluation#transformed-properties) and [Setup and targeting](https://amplitude.com/docs/guides-and-surveys/setup-and-target#targeting). ## Transformed events and custom events | Topic | Custom Events | Transformed Events and Properties | | --- | --- | --- | | Analysis of individual components | Can perform analysis on the individual events used in the custom event. | Can only perform analysis on the transformed event. | | Use case | Augment and group existing events into new events you can analyze. | Clean up events and fix instrumentation issues. | | Drop and block filters | Not available to block and drop filters. | Transformed entities aren't available to block and drop filters. | | Chart UI limitations | Limited availability in Funnels, but can't group by event name. | Available to most charts. | | User lookup | Shows raw event data only. | Shows raw event data only. | | Event type limit | Don't count toward the event limit. | Don't count toward the event limit. | ## Common questions ### I merged event A and event B together to create event C. What happens to saved charts that were querying on event A? Any saved chart querying on event A continues to do so after the merge. The chart doesn't automatically switch from event A to event C. For charts created after the merge, neither event A nor event B appears in the chart dropdown; only event C appears. ### I merged event A and event B together to create event C. How do I bulk update the existing saved charts to now use event C? You can't bulk update charts in Amplitude. Try adding all charts that still use the old events (in this example, events A and B) to a dashboard. Use **Find & Replace** to swap those events for event C, then click _Save onto Charts > Update existing charts_. ### I merged event property A and event property B together to create event property C. What happens to saved charts that were querying on event property A and event property B? Saved charts don't automatically switch to a different event property after a transformation. Each chart keeps querying the property you saved with it until you edit the chart. After the transformation, chart dropdowns only show the merged or target property. You can't create new charts that still query the old, untransformed property names. How you update existing charts depends on how you merged properties: - **You merged into a new event property C.** Update every saved chart that still queries event property A or B. For example, edit each chart and select event property C in the chart controls. You can also add those charts to a dashboard, use **Find & Replace** to swap the old properties for property C, then click _Save onto Charts > Update existing charts_. - **You merged into an existing event property** (for example, you map both A and B into property A instead of creating a new name). Update any saved chart that still queries a source property you dropped. Charts that already query the target property don't need changes, because they already use the merged property. ### I want to unmerge event C. What happens to the charts that use this merged event? The result depends on how you created event C in the first place. - If you merged event A and event B into event C: after refresh, the chart's user/event totals drop to zero. - If you merged event A and event C into event C: after refresh, the chart queries the source event C. ### Can I create a new transformation from an existing transformation? Amplitude doesn't support transformations on transformations. To request this capability, submit a feature request. ### Event C is a merged event composed of source events A and B. Can I view event A and event B separately, then event C starting at the date of the transformation? Transformations apply retroactively, so that isn't possible. ### Which value takes priority in a property merge? Use this example: for one instance of event A, you send the event property `event prop` = `true`; for another instance of event A, you send the event property `event_property` = `false`. You then merge both event properties into `EVENT_PROPERTY`. When you query on event A and group by `EVENT_PROPERTY`, this user appears twice. You see one data point for the `true` value and one for `false`. ================================================================================ # Custom events URL: https://amplitude.com/docs/data/custom-events Updated: 2026-09-22 ================================================================================ # Custom events A custom event is a saved, reusable event that combines two or more existing events with an `OR` clause, so any of those events counts as the same step in an analysis. For example, a custom event can show users who, after receiving a push notification, either played a song or searched for one as their next step. You can also [combine multiple events in-line](https://amplitude.com/docs/analytics/charts/event-segmentation/event-segmentation-in-line-events) through the Events Module, but an in-line event applies only to the chart where you create it. Save it as a custom event when you want to reuse the same combination across other charts. You create a custom event in the _Events_ panel from one or more pre-existing events. Doing so tells Amplitude to combine those pre-existing events and count any user activity for them as activity for the new custom event. This approach helps when you want an easy way to track activity on related or similar events, like whether a visitor has fired either the `view_landing_page_1` or `view_landing_page_2` events. For example, `Play or Search Song` is a custom event consisting of the `Play Song` event, the `Search Song` event, and an `OR` clause to connect the two. Any user who triggers either the `Play Song` event or the `Search Song` event has converted that second step. Another method is conditioning an added event with an [event property or user property](https://amplitude.com/docs/data/user-properties-and-events). This is the primary method for analyzing whether a user performed one of many events. ## Plan availability Custom Events is available on the Plus, Growth, and Enterprise plans. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details. | Plan | Allowance | How to access | | --- | --- | --- | | Free | Not included | [Upgrade your plan](https://amplitude.com/pricing) | | Plus | Included | Included in plan | | Growth | Included | Included in plan | | Enterprise | Included | Included in plan | _Availability reflects the latest Amplitude plans. If your organization is on an older plan, your access may differ. Check your plan under [Plans & Billing in your organization settings](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._ ## Before you begin - Only admins, managers, and members can create custom events. - You can use custom events in Event Segmentation, Funnel Analysis, Retention Analysis, Lifecycle, Stickiness, Impact Analysis, Journeys, Pathfinder, Conversion Driver, Experiment Results, and Compass charts. - You can't query on custom events in Redshift. - All custom events have the prefix `[Custom]` before the event name in your charts. - Editing or renaming custom events used in other charts breaks those charts. Amplitude continues to query the named value until you manually change it on any charts that use it. Amplitude displays a warning when you make any edits to custom events. - Querying event properties on custom events is possible only if the property applies to all events. If you try to create a custom event with five different events and want to see the location values from all those events, you need to instrument the location event property to all the individual events making up the custom event. ## Group two existing events into a single custom event To group two events, follow these steps: 1. In Amplitude Data's left-hand rail, select **Events**. Then select **Create Custom Event**. 2. In the modal that appears, select the events you want to analyze as a single event. You can set different filters on these events, in case the analysis requires a more granular view of the selected events. At this point, you can use this event for further analyses in Amplitude. Select the new event in the _Custom_ category in the appropriate chart drop-down menus. ## Custom events and transformed events | Topic | Custom Events | Transformed Events and Properties | | --- | --- | --- | | Analysis of individual components | Can perform analysis on the individual events used in the custom event. | Can only perform analysis on the transformed event. | | Use case | Augment and group existing events into new events which you can analyze. | Clean up events and fix instrumentation issues. | | Drop and block filters | Not available to block and drop filters. | Transformed entities aren't available to block and drop filters. | | Chart UI limitations | Limited availability in Funnels, but can't group by event name. | Available to most charts. | | User lookup | Shows raw event data only. | Shows raw event data only. | | Event type limit | Don't count toward the event limit. | Don't count toward the event limit. | ================================================================================ # Currency Conversion URL: https://amplitude.com/docs/data/currency-conversion Updated: 2026-09-22 ================================================================================ # Currency Conversion Currency conversion lets you analyze multi-currency revenue data in Amplitude. With currency conversion, you can: - Send Amplitude transaction data with local currency codes. - Use revenue data for insight generation or decision making without manually pre-converting data into a single currency. - Run queries based on a series of lookup tables connected to daily exchange rates to convert transaction amounts based on transaction dates and daily exchange rates. You can use the primary currency set at the project level (for example, convert all global currencies to USD). > **Note:** > > Amplitude performs currency conversion using the exchange rates from the preceding day for consistency in reporting. Amplitude sources exchange rates daily from [ExchangeRate API](https://www.exchangerate-api.com/). You can control where you view currency-converted data throughout Amplitude. You can configure target currencies at the project level through project settings, which means you can use both converted and non-converted values for `$revenue` and `$price` fields. You can also: - Send standard `$revenue` and `$price` fields or map your own custom fields (or cart properties) into the conversion logic. - View original, non-converted values in user timelines. This view aligns with the original data and avoids confusion when comparing information against chart data. ## Plan availability Currency Conversion is available on the Growth and Enterprise plans. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details. | Plan | Allowance | How to access | | --- | --- | --- | | Free | Not included | [Upgrade your plan](https://amplitude.com/pricing) | | Plus | Not included | [Upgrade your plan](https://amplitude.com/pricing) | | Growth | Included | Included in plan | | Enterprise | Included | Included in plan | _Availability reflects the latest Amplitude plans. If your organization is on an older plan, your access may differ. Check your plan under [Plans & Billing in your organization settings](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._ ## Enabling conversion To enable currency conversion, send the `$currency` property as a 3-character [ISO 4217](https://www.iban.com/currency-codes) code such as USD or EUR alongside your revenue-related data. ## OOTB derived properties Amplitude provides two OOTB derived properties that let you view currency-converted data. These OOTB derived properties are: - Currency Converted Revenue. - Currency Converted Price. These derived properties apply only to events containing both `$currency` and either `$revenue` or `$price` fields. You can find these properties by going to _Data > Properties > Derived_. They appear as read-only fields, and you can use them for filtering, grouping, and aggregations. ### Currency Converted Revenue Converts the `$revenue` field into the project's target currency using the `$currency` field as the original currency code for the received `$revenue`. ```typescript CURRENCY_CONVERT(PROPERTY("$currency", "event"), PROPERTY("$revenue", "event")) ``` ### Currency Converted Price Converts the `$price` field into the project's target currency using the `$currency` field as the original currency code for the received `$price`. ```typescript CURRENCY_CONVERT(PROPERTY('$currency', 'event'), PROPERTY('$price', 'event')) ``` ## Custom derived properties If you use `$Cart Properties`, or if you don't use `$revenue`, `$price`, or `$currency` fields, you can create custom derived properties to apply currency conversion. Custom derived properties require project-level currency configuration. For example, add a derived property to currency convert the custom `$revenue` or `$currency` field: ```typescript CURRENCY_CONVERT(PROPERTY("_currency_", "event"), PROPERTY("_revenue_", "event")) ``` Then add the derived property to currency convert cart properties: ```typescript CURRENCY_CONVERT(PROPERTY("_currency_", "event"),PROPERTY("products.revenue", "event")) ``` ## Project settings You can configure the target currency for derived property revenue fields in the project settings. ##### To configure currencies 1. Open your project and go to _Organization Setting > Projects > General_. 2. Select the currency you want from the **Which currency should your values be converted to?** dropdown menu. All options are in standard [ISO 4217](https://www.iban.com/currency-codes) 3-digit format. ## Property selectors You can select both OOTB and custom derived properties when [building charts](https://amplitude.com/docs/get-started/create-a-chart). ##### To select currency conversion properties in a chart 1. Go to an existing chart or go to _Create > Chart_ to create a new one. 2. In the Events modal, select **Any Active Event**, then select **Select property**. 3. In the search field, find **Derived Properties**. 4. Select the properties you want. You can select any of: - Currency Converted Revenue. - Currency Converted Price. - Custom derived properties. ## Currency converted revenue in charts When viewing the chart, both the original revenue value and the currency-converted value are available. ================================================================================ # Derived properties URL: https://amplitude.com/docs/data/derived-properties Updated: 2026-09-22 ================================================================================ # Derived properties Derived properties create new event and user properties retroactively from existing ones, using functions and operators. Amplitude computes them dynamically at query time and doesn't change your raw data. Use them to run analyses on values you didn't send in the original event payload. Use a derived property when you need a value computed from existing properties and don't want to re-instrument or re-ingest data. If you need a value sent at event time from the client, use a regular event property instead. If you need a curated, named event built from multiple raw events, use a custom event instead. For example, create a derived property whose value is a boolean based on whether a cart item's price exceeds a threshold. ## Plan availability Derived Properties is available on the Growth and Enterprise plans. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details. | Plan | Allowance | How to access | | --- | --- | --- | | Free | Not included | [Upgrade your plan](https://amplitude.com/pricing) | | Plus | Not included | [Upgrade your plan](https://amplitude.com/pricing) | | Growth | Included | Included in plan | | Enterprise | Included | Included in plan | _Availability reflects the latest Amplitude plans. If your organization is on an older plan, your access may differ. Check your plan under [Plans & Billing in your organization settings](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._ ## Create a derived property You need to be on your project's `main` branch to create a derived property. To create a derived property, follow these steps: 1. In Amplitude Data, go to _Tracking Plan > Properties_ and select the **Derived Properties** tab. 2. Select **Add Derived Property**. 3. Give your derived property a name. 4. Add any relevant metadata to your property, including a description (optional, unless you want to use the Suggest feature) and the visibility of the property in charts within this project. 5. Enter your formula. Review the list of valid functions and operators below. 6. Select **Save**. ## Preview your results As long as the formula you entered is valid, you can test the results in the space below the formula editor. Test by selecting existing values for properties used in the formula, or by entering free-form values. You can test from either the _Create/Edit_ modal or from the side panel for a saved derived property. ## Derived property use cases Using the referrer URL example, you can write a formula using string operators such as: `SPLIT(PROPERTY('referrer_url','event'), "/", 2)` This formula converts a value like "https://www.google.com/search?q=amplitude" into the value "www.google.com." To strip this down further to "google", wrap the result of a SPLIT function inside another SPLIT function. The resulting formula looks like this: `SPLIT(SPLIT(PROPERTY('referrer_url','event'), "/", 2), ".", 1)` Amplitude also supports math operators. For example, if you have events that contain subtotal and tip properties and want to run analyses based on the total amount, use this formula: `SUM(PROPERTY('subtotal','event'), PROPERTY('tip','event'))` To determine whether a particular order receives a discount when the total order size exceeds $50, use this formula: `IF(SUM(PROPERTY('subtotal','event'), PROPERTY('tip','event')) >= 50, 'true')` > **Note:** > > Queries using derived properties might experience longer query times depending on the complexity of the formulas. A limit of up to 10 property references per derived property also applies. ## Functions and operators ### String functions - **`REGEXEXTRACT (text_property, regular_expression)`** - **Description**: Extracts substrings matching the regular expression. - **Example**: `REGEXEXTRACT("shirt-150", "[0-9]+")` - **Result**: `150` - **`REGEXREPLACE (text_property, regular_expression, replacement_text)`** - **Description**: Replaces the property's values with text matching the regular expression with replacement text. - **Example**: `REGEXREPLACE("en-US", "-.*", "")` - **Result**: `en` - **`CONCAT(property1, property2)`** - **Description**: Concatenates a property with another property or text value. - **Example**: `CONCAT("firstName", "lastName")` - **Result**: `firstName lastName` - **`LOWERCASE (text_property)`** - **Description**: Lower cases all characters in property's values. - **Example**: `LOWERCASE("John")` - **Result**: `john` - **`UPPERCASE (text_property)`** - **Description**: Upper cases all characters in property's values. - **Example**: `UPPERCASE("John")` - **Result**: `JOHN` - **`SPLIT (property, separator, [index])`** - **Description**: Split a property based on a delimiter and return an array of split elements. Takes an optional index that returns the element at that index. - **Example**: - `SPLIT("a_b_c", "_")` - `SPLIT("john@example.com", "@", 0)` - **Result**: - `["a", "b", "c"]` - `"john"` - **`REMOVE (property, text)`** - **Description**: Remove all occurrence of text in property. - **Example**: `REMOVE("en-US", "en-")` - **Result**: `US` - **`EXTRACT_FROM_DICT (property, text)`** - **Description**: Extract a value from a dictionary string based on a specific key. - **Example**: `EXTRACT_FROM_DICT("{'id': 1, 'name': 'John', 'country': 'US'}", "name")` - **Result**: `John` ### Math functions | Function | Description | Example | Result | | --- | --- | --- | --- | | `SUM(num_property1, num_property2)` | Adds a property with other properties or with numbers. Equivalent to the `+` operator. Use `ADD` as an alias. | `SUM(subtotal, tip) >>>  SUM(10, 2)` | 12 | | `MINUS(num_property1, num_property2)` | Subtracts a property with other properties or with numbers. Equivalent to the `-` operator. Use `SUBTRACT` as an alias. | `MINUS(total, tip) >>> MINUS(12, 2)` | 10 | | `MULTIPLY (num_property1, num_property2)` | Multiplies a property with other properties and/or with numbers. Equivalent to the `*` operator. | `MULTIPLY(price, quantity) >>> MULTIPLY(2.50, 4)` | 10 | | `DIVIDE(numerator, denominator)` | Divides a property by another property or number. Equivalent to the `/` operator. | `DIVIDE(calorie_intake, calorie_goal) >>> DIVID(1000, 2000)` | 0.5 | | `POWER(num_property, exponent)` | Takes the property's values to the exponent power. | `POWER(property, 3) >>> POWER(2, 3)` | 8 | | `MIN(num_property1, num_property_2)` | Returns the minimum value between two numbers. | `MIN(5, 10)` | 5 | | `MAX(num_property1, num_property_2)` | Returns the maximum value between two numbers. | `MAX(5, 10)` | 10 | | `CEIL(num_property)` | Rounds up to the nearest integer. | `CEIL(3.8)` | 4.0 | | `FLOOR(num_property)` | Rounds down to the nearest integer. | `FLOOR(3.8)` | 3.0 | ### Object functions | Function | Description | Example | Result | | --- | --- | --- | --- | | `EXTRACT_FROM_DICT (property, text)` | Extract a value from a dictionary string based on a specific key. | `EXTRACT_FROM_DICT("{'id': 1, 'name': 'John', 'country': 'US'}", "name")` | `John` | ### Date/ time functions Amplitude requires all Unix timestamps to be in milliseconds. | Function | Description | Example | Result | | --- | --- | --- | --- | | `DATE_TO_LONG (date_property)` | Convert date into Unix timestamp | `DATE_TO_LONG("2020-12-01")` | 1606780800000 | | `TIME_TO_LONG (time_property)` | Convert date time (YYYY-MM-dd\[T\]HH:mm:ss) into Unix timestamp | `TIME_TO_LONG("2020-12-01 12:00:00")` | 1606780800000 | | `LONG_TO_TIME (number_property)` | Convert Unix timestamp into date-time (local to user's timezone) | `LONG_TO_TIME (1606780800000)` | 2020-12-01 12:00:00 | | `LONG_TO_DATE (number_property)` | Convert Unix timestamp into date (local to user's timezone) | `LONG_TO_DATE (1606780800000)` | 2020-12-01 | | `DATE_TIME_FORMATTER (datetime_property, old_format, new_format)` | Convert format of a datetime property to a new format. Refer to [Java SimpleDateFormat](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html) for more details. | `DATE_TIME_FORMATTER ("05.01.2021 12:00:00:000", "MM.dd.yyyy hh:mm:ss:SSS", "yyyy/MM/dd")` | 2021/05/01 | | `TODAY()` | Current day represented as a long in epoch time in UTC. | `TODAY() - start_date_in_ms >>> 1609459200000 - 1577836800000` | 31622400000 | | `EVENT_HOUR_OF_DAY()` | Get hour of day (0-23) from the event's timestamp. | `EVENT_HOUR_OF_DAY()` | 10 | | `EVENT_DAY_OF_WEEK()` | Get day of week from the event's timestamp as string. For example, Monday. | `EVENT_DAY_OF_WEEK()` | Monday | ### Array functions When performing computations on derived properties created from array properties, Amplitude assumes that only the first child is an array property. Amplitude only considers the first value of the other children, even when those other children are also array properties. Here are some illustrative examples: ```plaintext Example 1 propA = [1,2,3], propB = [a,b,c] CONCAT(propA, propB) = [1a, 2a, 3a] Example 2 propA = [1, 2, 3], propB = [a] CONCAT(propA, propB) = [1a, 2a, 3a] Example 3 propA = [1], propB = [a, b, c] CONCAT(propA, propB) = [1a] ``` | Function | Description | Example | Result | | --- | --- | --- | --- | | `ITEM_COUNT (property)` | Length of array property; defaults to 1 for non-arrayed properties. | `ITEM_COUNT(products)` | 3 | | `GREATEST(property)` | Get max value of the array. | `GREATEST(prices)` | 10 | | `LEAST(property)` | Get min value of the array. | `LEAST(prices)` | 2 | | `COALESCE(property)` | Get the first non-null value of the array | `COALESCE(locations)` | 'California' | ### Property functions When you select a property from the _Insert Property_ dropdown, Amplitude inserts a property function referencing that property directly into the editor. You can also manually insert this function wherever you want to reference a different Amplitude property. These functions are available inside other functions. | Function | Description | Example | Result | | --- | --- | --- | --- | | `PROPERTY(property_name, property_type)` | Reference to property within Amplitude. Possible property types: "user", "event", "derived", "lookup", "group" | `PROPERTY("first name","user")` | A reference to the user property "first name" in your project. This is how derived properties communicate with Amplitude’s query service. | | `PROPERTY(property_name, "group", group_type)` | Reference to group property within Amplitude. Group type is required for group properties. | `PROPERTY("name","group", "business")` | A reference to the group property "name" in the group type "business" within your project. This is how derived properties communicate with Amplitude’s query service. | #### Reference Event Time To use an event's timestamp in a derived property formula, select **Event Time** from the _Insert Property_ dropdown in the derived property builder. Inside a derived property formula, `Event Time` is a long value in epoch milliseconds. To display it as a readable date, wrap it in `LONG_TO_TIME` or `LONG_TO_DATE`. Don't wrap `Event Time` in `TIME_TO_LONG` or `DATE_TO_LONG`, because the value is already a long and the conversion returns `none`. To compare `Event Time` against a date or datetime property, convert the other property to a long with `TIME_TO_LONG` or `DATE_TO_LONG` instead. ### Conditional operators | Operator | Description | Example | | --- | --- | --- | | `IF(logical_expression, value_if_true, value_if_false)` | Returns `value_if_true` if `logical_expression` is true, otherwise returns `value_if_false`. | `IF(property == "(none)", "Property wasn't set", "Property was set")` | | `AND(logical_expression_1, logical_expression_2)` | Returns True if both logical expressions are true, false otherwise. | `AND(is_subscribed == "true", has_valid_promo == "true")` | | `OR(logical_expression_1, logical_expression_2)` | Returns True if any logical expression is true, false otherwise. | `OR(has_email == "true", has_phone == "true")` | | `SWITCH(expression, case_1, value_1, [case_2, value_2 ...], [default])` | Evaluates an expression and returns values based on defined cases. Returns a default value if no cases are met if defined, otherwise null. | `SWITCH(tier, "gold", 2, "silver", 2, "bronze", 1, 0)` | ### String/numerical operators | Operator | Example | | --- | --- | | `==` | `action == "purchase" ` | | `!=` | `item_count != 0 ` | | `contains` | `email contains "@gmail.com"` | | `does not contain` | `title does not contain "officer" ` | | `<`, `<=`, `>`, `>=` | `duration >= 60` | | `glob match` | `url glob match "https://www.google.*/*"` | | `glob does not match` | `query glob does not match "*/query=*"` | | `has prefix` | `title has prefix "sir" ` | | `does not have prefix` | `title does not have prefix "sir"` | ### Set operators Set literals ("apple", "orange") must appear on the right hand side of the operator. - **`==`** - **Example**: - `IF(product == ("apple","orange"), "true", "false")` - product = "apple", Returns "true" - **`!=`** - **Example**: - `IF(product != ("apple","orange"), "true", "false")` - product = "banana", Returns "true" ### Parallel operators Perform operations on arrays of data to help perform cart analysis. | Operator | Description | | --- | --- | | `PARALLEL_SUM` | Adds corresponding values from two arrays at each position. | | `PARALLEL_PRODUCT` | Multiplies corresponding values from two arrays at each position. Use this operator to calculate revenue for each item in a cart. For example, `PARALLEL_PRODUCT(PROPERTY('Products.price', 'event'), PROPERTY('Products.quantity','event'))` | | `PARALLEL_MAX` | Returns the larger of the corresponding values from two arrays at each position. | | `PARALLEL_MIN` | Returns the smaller of the corresponding values from two arrays at each position. | | `SUM_ARRAY` | Sums all numeric elements in a single array property. Use this operator to calculate total cart value for filtering or grouping. For example, `SUM_ARRAY([1, 2, 4])` returns `7`. | Parallel operators require at least one property to be a child cart property, and both properties must be under the same parent property. For example, `products.price` and `products.quantity` are compatible. `products.price` and `shoppinglist.quantity` aren't compatible because they have different parent properties. When you use a parallel operator with two arrays, it adds, multiplies, or compares corresponding values at each position. For example, `PARALLEL_SUM([1, 3, 5], [2, 4, 6])` returns `[3, 7, 11]`. When one input is an array and the other is a scalar (single number), the scalar broadcasts to match the array's length. For example, `PARALLEL_SUM([1, 3, 5], 1)` returns `[2, 4, 6]`, and `PARALLEL_PRODUCT(2, [4, 5, 6])` returns `[8, 10, 12]`. The derived property that a parallel operator creates becomes a child property of the parent cart property used in the formula. For example, creating a `revenue` derived property with `PARALLEL_PRODUCT(PROPERTY('products.price', 'event'), PROPERTY('products.quantity', 'event'))` makes `revenue` a child property of `products`. > **Note:** > > To use a derived property created with a parallel operator in a chart, first select the parent cart property (marked with `{:}`). The derived property then appears in the child property selection list. #### Parallel operator example You have a purchase event with the following cart property: ```json "Products": [{ "brand": "Apple","categories": "Digital Content","department": "Electronics", "price": 24.99,"quantity": 1 }, { "brand": "Adidas","categories": "Newsletter","department": "Electronics", "price": 24.99,"quantity": 1 }, { "brand": "Fossil","categories": "Digital Content","department": "Women's Clothing", "price": 24.99,"quantity": 2 }] ``` | Brand | Price | Quantity | | --- | --- | --- | | Apple | 24.99 | 1 | | Adidas | 24.99 | 1 | | Fossil | 24.99 | 2 | Use `PARALLEL_PRODUCT` to create a `Revenue` derived property: ```plaintext PARALLEL_PRODUCT( PROPERTY('Products.price', 'event'), PROPERTY('Products.quantity','event') ) ``` If you add this property to a chart, group by `Brand` to view revenue by brand. You can also use `SUM_ARRAY` on the `Revenue` derived property to calculate total cart value: ```plaintext SUM_ARRAY(PROPERTY('Revenue', 'derived')) ``` This returns the sum of all revenue values across items in the cart, which is useful for filtering or grouping by total cart value. ## Common derived properties formulas ### Calculate the age of a customer ```plaintext CEIL( DIVIDE( MINUS( PROPERTY('server_upload_time', 'amplitude_user'), TIME_TO_LONG(PROPERTY('Created At', 'user')) ), 86400000 ) ) ``` Use this formula when you track a user property with a date-time data type and want to calculate the age of that user (how long that user has existed in your system) since the event that set this user property. ### Calculate days since registration Use `Event Time` with a date or datetime property to calculate how many days passed between an event and a fixed date, such as a user's registration date. In the derived property builder, select `Event Time` from the _Insert Property_ dropdown, then build a formula like this: ```plaintext DIVIDE( MINUS( PROPERTY('Event Time', 'event'), TIME_TO_LONG(PROPERTY('registration_date', 'user')) ), 86400000 ) ``` This example assumes `registration_date` is a datetime string (for example, `"2023-08-18 17:37:39"`). Inside a formula, `Event Time` acts as a long in epoch milliseconds. The formula converts the registration date to a long with `TIME_TO_LONG`, subtracts it from `Event Time`, and divides by 86400000, the number of milliseconds in one day. ### Get the difference between two dates ```plaintext DIVIDE( MINUS( DATE_TO_LONG( PROPERTY( 'start_date', 'user' ) ), DATE_TO_LONG( PROPERTY( 'end_date', 'user' ) ) ), 86400000 ) ``` Sample output. In the derived property above, Amplitude converts the properties `end_date` and `start_date` into UNIX timestamps to calculate the difference between them. Amplitude then divides that result by 86400000, the number of milliseconds in one day. > **Note:** > > This output is a double type (for example, 2.0). ### Output a standardized date format ```plaintext IF( DATE_TIME_FORMATTER( PROPERTY( 'publishDate', 'event' ), "yyyy-MM-dd'T'HH:mm:ssX", 'yyyy-MM-dd' ) contains '-', DATE_TIME_FORMATTER( PROPERTY( 'publishDate', 'event' ), "yyyy-MM-dd'T'HH:mm:ssX", 'yyyy-MM-dd' ), IF( DATE_TIME_FORMATTER( PROPERTY( 'publishDate', 'event' ), "yyyy-MM-dd HH:mm:ss", 'yyyy-MM-dd' ) contains '-', DATE_TIME_FORMATTER( PROPERTY( 'publishDate', 'event' ), "yyyy-MM-dd HH:mm:ss", 'yyyy-MM-dd' ), DATE_TIME_FORMATTER( PROPERTY( 'publishDate', 'event' ), "yyyy-MM-dd", 'yyyy-MM-dd' ) ) ) ``` Sample output. One way to format dates to Standard Date Format is to use a series of IF statements. Make sure the higher specificity conditional comes first. Replace the `$<number>` here with the actual properties. ### Get the month and year a customer signed up ```plaintext CONCAT( REGEXEXTRACT( PROPERTY( 'start_date', 'user' ), 'dddd-dd' ), "-01" ) ``` In this example, the derived property pulls the sign-up month and year from a property that contains a more detailed value, then appends "-01" to set it to the beginning of the month. Use `REGEXEXTRACT()` to pull the year and month from the value, and use `CONCAT()` to append "-01". Replace the `$<number>` here with the actual properties. ### Replace existing property values ```plaintext IF( OR( REGEXEXTRACT( PROPERTY( "package", "event" ), 'Casual' ) =='Casual', REGEXEXTRACT( PROPERTY( "package", "event" ), '1 Job Posting' )=='1 Job Posting', REGEXEXTRACT( PROPERTY( "package", "event" ), '1 Basic' )=='1 Basic' ), 'Casual', 'False' ) ``` Sample output. To replace multiple property values, use `REGEXEXTRACT()` to pull the string from the property, and use OR statements inside an IF statement to check whether the value pulled from the properties contains any of the values you want to replace. In this example, if the property value matches any of the specified values, the formula replaces the value with `Casual`. Otherwise, the formula replaces the property with `False`. Replace the `$<number>` here with the actual properties. ### Count length of an array that was accidentally ingested as a string Convert the string to an array format by using SPLIT: ```plaintext SPLIT( PROPERTY('color', 'event'), ',' ) ``` Sample output: ![Screenshot 2023-09-28 at 14.39.54.png](https://amplitude.com/docs/images/data/screenshot-2023-09-28-at-14-39-54-png.png) Amplitude ingested the property color as the string "Red, Green, Blue". After using SPLIT, the resulting value is `[Red, Green, Blue]`. Use the above derived property within a new derived property that uses `ITEM_COUNT`. ```plaintext ITEM_COUNT( PROPERTY("Transform into Array", "derived") ) ``` Sample output: ![Screenshot 2023-09-28 at 14.42.30.png](https://amplitude.com/docs/images/data/screenshot-2023-09-28-at-14-42-30-png.png) Now the underlying data is an array. `ITEM_COUNT` counts the number of items that make up the array. ================================================================================ # Lookup Tables URL: https://amplitude.com/docs/data/lookup-tables Updated: 2026-09-22 ================================================================================ # Lookup Tables With Amplitude's Lookup Table feature, you can import your own data and map it to ingested properties to create an enhanced set of event and user properties. > **Note:** Plan availability > > Lookup Tables are available on Growth and Enterprise plans with the Govern add-on. To learn more or upgrade, contact [Sales](https://amplitude.com/sales-contact). ## Plan availability Lookup Properties is available on the Growth and Enterprise plans. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details. | Plan | Allowance | How to access | | --- | --- | --- | | Free | Not included | [Upgrade your plan](https://amplitude.com/pricing) | | Plus | Not included | [Upgrade your plan](https://amplitude.com/pricing) | | Growth | Included | Included in plan | | Enterprise | Included | Included in plan | _Availability reflects the latest Amplitude plans. If your organization is on an older plan, your access may differ. Check your plan under [Plans & Billing in your organization settings](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._ ## Lookup table benefits - **Enrich data using ingested property values**: Say you've captured an event called `Purchased` with an event property named `SKU`. The `SKU` value itself doesn't inherently hold a lot of meaning. With your list of all the SKUs and their corresponding product names, you can use this feature to create a new property called `Product Name` that populates automatically based on that list. - **Bulk change or fix property values**: Imagine you've captured a user property called `Language Code` and passed in language codes (`en_US`, `fr_FR`, `de_DE`, and so forth). These codes are difficult to read, so you want a `Language` property that maps to friendlier values like `English`, `French`, and `German`. Use this feature to create a new property called `Language` that maps the language codes to the language names. - **Bulk filter long lists**: To analyze user behavior for a specific region when you have a list of all customers and their regions, use this feature to map each customer to a region, creating a new `Region` property. You can then filter to each region in a chart. > **Note:** > > Lookup Tables can't exceed 100MB or 1 million rows. Contact your Amplitude CSM if you have data that exceeds this limit. ## Find lookup properties in charts After you create a lookup property, it appears in chart dropdowns alongside the source property you mapped it from. > **Note:** Lookup properties based on child (cart) properties > > If you create a lookup property that maps from a child (cart) property (a property nested inside an object array), the lookup property doesn't appear in the main property list in charts. Instead, it appears under its parent cart property. To find it, first select the parent cart property (marked with `{:}`) in the property dropdown, then look for the lookup property as a nested option in the second-level dropdown. For more on cart properties, refer to [Cart analysis](https://amplitude.com/docs/analytics/charts/cart-analysis). ## Create a Lookup Table Before you can start using Lookup Tables, you need: - An event property or user property to create a mapping from. - A .CSV that has the data you want to map to. The first column data must correspond to the mapping property value and must contain unique values. > **Note:** > > Lookup Tables look for exact matches, and are case-sensitive. To create a new Lookup Table in Amplitude Data, follow these steps: 1. Navigate to _Sources_ in the project you want to import the .CSV data to. 2. Click **+ Add Source**. Search for **CSV**, then click it. 3. Navigate to your .CSV file and upload it. Then click **Next**. 4. Map your event property by selecting it from the dropdown. When you're done, click **Finish**. > **Note:** > > You must be an Admin or Manager of the project to add or manage a source. ## Update a Lookup Table To create a new lookup property or fix an incorrectly mapped property, update the lookup table by following these steps: 1. In Amplitude, navigate to _Sources_, find the Lookup Table in the _Sources List_. Click it to open its **General** tab. 2. Open the **Edit Lookup Table Configuration** tab. 3. Make your changes. You can change the mapping, or replace the .CSV by uploading a new file. 4. When you're finished, click **Update your lookup table configuration**. ## Delete a Lookup Table and its properties To delete a Lookup Table you no longer need, follow these steps: 1. In Amplitude, navigate to _Sources_, then find the Lookup Table in the _Sources List_. 2. Open the **Edit Lookup Table Configuration** tab. 3. Click the trash can and follow the on-screen instructions. ================================================================================ # Verify persisted properties URL: https://amplitude.com/docs/data/persisted-properties/verify-persisted-properties Updated: 2026-09-09 ================================================================================ # Verify persisted properties Persisted Properties carry a property value forward from an earlier source event to a later target event at query time. After you set up a persisted property, it starts enriching your target event immediately. This guide shows you how to confirm they are working, using your own live data. The pattern this guide covers: An event that fires your property → an event you want to analyze For example, "Item Viewed" fires `brand` and you want to see that brand carried forward to "Purchase Completed". Or "Search Performed" fires `search_term` and you want it on "Signup". Substitute your own events and properties throughout. The verification process consists of: 1. Confirm the property is firing on the event that should carry it. 2. Confirm the right users are in scope. 3. Validate persistence in a Data Table. ## Before you start Before running any checks, make sure you have [created the persisted property](https://amplitude.com/docs/data/persisted-properties) in _Data > Properties_ and noted down: - The event that fires the property you want to carry forward. - The property name as it appears on that event. - The event you want to analyze. This is the one you want enriched with the persisted value. Also note the allocation method you chose, either Original (first touch) or Most Recent (last touch). The allocation determines which value gets carried when a user fires the source event more than a single time before reaching the target. ## Step 1: Confirm the property is firing on the event that should carry it Before checking whether values are being persisted, confirm the property actually arrives on the source event in the first place. A high `(none)` rate on your target event is often traced back here. ### Check User Profiles 1. Go to _Users & Groups > [User Profiles](https://amplitude.com/docs/analytics/user-data-lookup)_. 2. Use the search bar to filter by name, email, or user ID if you have a specific user in mind. 3. Click **Add Filter** and choose **Performed event**. Select your source event. This narrows the list to users who have fired it at least once. 4. Click into any user in the results. In their event timeline, find an instance of the source event and expand it. You should see the property you're persisting listed alongside its value. > **Note:** What to look for > > The property appears with a non-null value on the source event for the majority of users. Occasional nulls are normal. Some sessions may not hit that code path. A null rate above 30% suggests an instrumentation gap that needs fixing before persisted properties can work. ### Narrow to users who have the source but not yet the target A useful diagnostic is to isolate users who fired the source event but haven't fired the target event in the same period. These users let you inspect the source property in isolation, without the complexity of a full journey. 1. Add a filter: `Performed event = your source event`. 2. Add a second filter: `Did not perform = your target event`. 3. Browse these users' timelines. Every source event should carry the property with a non-null value. This group is your cleanest signal that the upstream data is healthy. After you're satisfied the source property is arriving reliably, proceed with the verification process. ## Step 2: Confirm the right users are in scope Review the users who have fired both events. These are the users who carry the persisted value from the source to the target, and they're the population that appears in the [Data Table](#step-3-validate-persistence-in-a-data-table). 1. In User Profiles, add a filter: `Performed event = your source event`. 2. Add a second filter: `Performed event = your target event`. 3. Note the user count. This is the population you expect to see in the Data Table you'll build next. 4. Click into a few users. In each timeline, find a source event followed by the target event. Confirm the source event carries the property, and verify the event ordering matches what you'd expect for your allocation method. > **Note:** Allocation method affects directionality > > Original (first touch) locks in the first value Amplitude ever recorded for the user. It can attribute that value even if the source event fired after the target event within the expiration window. > > Most Recent works in a strictly forward direction, using the latest value recorded before query time. When reviewing timelines, keep your method in place: for Original, find the chronologically earliest source event. For Most Recent, find the one closest to the target. ## Step 3: Validate persistence in a Data Table The [Data Table](https://amplitude.com/docs/analytics/charts/data-tables/data-tables-attribute-credit) chart is the most powerful verification tool because it shows you the distribution of persisted values at scale, and lets you drill into the users behind any cell to close the loop. ### Build the table 1. Go to _Create > Data Table_. 2. Set the metric event to your target event (for example, "Purchase Completed"). Use **Event Totals** as the metric. 3. In the **Group-by** field, add your persisted property. It appears alongside standard event properties in the dropdown. Find the name you gave it in _Data > Properties_. 4. Set the date range to the last 7 days, or any window where you know both events have fired. ### Read the results After the table loads, find the rows for each distinct value of the persisted property. The values are carried forward from the source event to the target. A healthy setup shows most of your target event volume attributed to a named value, with a small `(none)` row. | What you see | What it means | What to do | | --- | --- | --- | | Named values appear with volume; `(none)` is a small fraction | Persistence is working. The property is being carried forward successfully. | Setup is correct. Tune your allocation method or expiration if needed. | | `(none)` dominates the table | Many target events lack a persisted value. The source event may not be firing the property reliably, or the event ordering doesn't match your allocation method. | Return to the [Step 1](#step-1-confirm-the-property-is-firing-on-the-event-that-should-carry-it) step and audit source event instrumentation. Confirm both events fall within the expiration window. For Most Recent, the source should precede the target; for Original, the first-ever occurrence is used regardless of ordering. | | Persisted property doesn't appear in Group-by | The property definition may not yet be saved, or it targets a different event. | Go to _Data > Properties_, open the persisted property, and confirm the source event and property name are correct. | ### Drill into users from the table Clicking any cell in the Data Table opens a list of users behind that number. This is the most direct way to close the loop between your aggregate picture and real individual journeys. 1. Click on the count in a cell. For example, the number of target events associated with a specific persisted value. 2. In the panel that opens, click to create a cohort. Cross-reference these users against the users you identified in the [Confirm the right users are in scope](#step-2-confirm-the-right-users-are-in-scope) step. They should largely overlap. 3. Click into one of those users and open their event timeline. Find the target event and confirm it shows the persisted property with the expected value. Then trace back to the source event and confirm the value matches. 4. (optional) Compare allocation methods side by side. If you set up two persisted properties with different allocation methods (Original and Most Recent), add both as group-bys in the same table. Rows where they agree represent single-source sessions. Rows where they differ reveal multi-source journeys. Both values are correct, they just answer different questions. > **Note:** > > The loop is closed when: > > 1. The user appears in your [filter](#step-2-confirm-the-right-users-are-in-scope) (performed both events). > 2. They appear in the Data Table under a named persisted value, not `(none)`. > 3. Their event timeline shows the source and target events within the same expiration window, with the persisted property value matching what you'd expect given your allocation method. ## Verify a property with item-level attribution If your persisted property uses [item-level attribution](https://amplitude.com/docs/data/persisted-properties#advanced-item-level-attribution), verification groups events by item identifier (such as `product.item_id`) rather than by user or session. Each item in the cart can carry a different persisted value, so checks happen for each item. For each item, confirm: - The first-touch and last-touch candidate values from your linking events. - Which value Amplitude persists onto each cart event, based on the property's allocation method. - Whether the persisted value matches what you expect. A mismatch points to an instrumentation gap on the source event or the linking event. ### Spot-check a single item 1. In _Users & Groups > [User Profiles](https://amplitude.com/docs/analytics/user-data-lookup)_, open a user who completed a `Purchase` (or `Add to Cart`) event. 2. Expand the cart array on that event. Note the item identifier (such as `product.item_id`) for one item. 3. In the same user's timeline, find the [linking events](https://amplitude.com/docs/data/persisted-properties#configure-item-level-attribution) you selected when configuring the property — for example, `View Item Details` and `Add to Cart`. Confirm each linking event carries both the source property and the item identifier. 4. Compare the persisted value on the cart event for that item against your allocation method: - **Original**: the value from the earliest linking event for that item. - **Most Recent**: the value from the latest linking event for that item before the cart event. ### Validate at scale in a Data Table Build a [Data Table](https://amplitude.com/docs/analytics/charts/data-tables/data-tables-attribute-credit) with your cart event grouped by both the persisted property and the item identifier. Rows with `(none)` are candidates to investigate — either the source event didn't fire the property for that item, or the linking events don't capture the item identifier reliably. ## Troubleshoot common issues | Symptom | Likely cause and fix | | --- | --- | | High `(none)` rate on the target event | The source event isn't firing the property on most instances, or users are reaching the target event outside the expiration window. Audit source event instrumentation first. If the journey spans multiple sessions, switch expiration from **Session** to **User**. | | Persisted property missing from Group-by | The property definition may not yet be saved or is pointing at the wrong event. Go to _Data > Properties_, open the persisted property, and confirm the source event and property name exactly match your taxonomy. | | Values don't match what you see in the user timeline | Likely an allocation mismatch. If Original is set, the value locked in is from the first source event in the session, not the one closest to the target. Re-read the timeline in session order. | | Users in Step 2 don't appear in the Data Table | The session or user expiration window may have ended between the two events. Extend the expiration, or filter the Data Table to the same date range you used in User Profiles. | ================================================================================ # Aggregated Metrics (fka Warehouse Metrics) Overview URL: https://amplitude.com/docs/data/warehouse-metrics Updated: 2026-09-22 ================================================================================ # Aggregated Metrics (fka Warehouse Metrics) Overview Aggregated Metrics (formally known as Warehouse Metrics) import precomputed metric values directly from your data warehouse into Amplitude, so your analyses use the same numbers as your warehouse source of truth. Unlike event-based metrics that Amplitude calculates from behavioral data, Aggregated Metrics (fka Warehouse Metrics) sync pre-calculated values from your warehouse. You can use business metrics like revenue, customer lifetime value, health scores, and financial KPIs alongside behavioral data in Amplitude's analytics and experimentation tools. Use Aggregated Metrics when you need numeric, time-series values that you can aggregate, set as experiment goals, or chart over time. If you only need the most current user attributes from your warehouse, use [Profiles](https://amplitude.com/docs/data/profiles) instead. > **Note:** > > To gain access, contact your Amplitude Client Success Manager. ## Plan availability Warehouse Metrics is available on all plans. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details. _Availability reflects the latest Amplitude plans. If your organization is on an older plan, your access may differ. Check your plan under [Plans & Billing in your organization settings](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._ ## How Aggregated Metrics (fka Warehouse Metrics) work Aggregated Metrics (fka Warehouse Metrics) sync on a recurring schedule from tables in your data warehouse. Each row should include the following: - **Time**: When the metric value is valid. - **User identifier**: The `user_id` or `device_id` to which the metric applies. - **Insert identifier**: An optional unique identifier for deduplication. - **Metric values**: Numeric values (like revenue: 13423, count: 50). - **Dimensions** (optional): Categorical attributes (like `health_score`: `"green"`, or `paid: true`). ## Requirements - An Amplitude project. - Read access to your Snowflake instance. - A table or view that contains metric values with timestamps and user identifiers. - Change Data Capture (CDC) enabled for your metrics table. > **Note:** Anonymous user support > > Aggregated Metrics (fka Warehouse Metrics) support both identified users (`user_id`) and anonymous users (`device_id`). ## Metric types Aggregated Metrics (fka Warehouse Metrics) supports these aggregation types on values: - **Sum**: Total of all values. - **Average**: Mean value across per-user sums. - **Min**: Minimum value. - **Max**: Maximum value. For more information, refer to [Warehouse Metric Calculations](https://amplitude.com/docs/data/warehouse-metric-calculations). ## Data types - **Metrics**: Numeric values only (integers, decimals). - **Dimensions**: String, number, or boolean values for grouping and filtering. > **Note:** > > Metrics require the source data to be numeric. ## Common use cases Aggregated Metrics (fka Warehouse Metrics) solve challenges where business metrics are difficult or impossible to calculate natively in Amplitude: ### Revenue and financial metrics - **Average Order Value (AOV)**: Precomputed. - **Credits Remaining/Used**: Account balance tracking. These metrics often require data that's too high-volume, sensitive, or non-event-based to send to Amplitude efficiently. ### Customer health metrics - **Customer Lifetime Value (LTV)**: Forward-looking revenue projections. - **Health Scores**: Composite metrics from multiple data sources. - **Churn Risk**: Machine learning predictions from your warehouse. These metrics require modeling and forecasting that happens in your data warehouse. ### State metrics - **Activation Status**: User onboarding state. - **Subscription Tier**: Current plan level. - **Beta Group Membership**: Feature access flags. - **Experiment Exposure**: Assignment tracking. These metrics track current user state rather than discrete events. ## Import metric data Aggregated Metrics (fka Warehouse Metrics) supports Snowflake. ### Enable change tracking If this is your first time importing from this table, enable change tracking in Snowflake: ```sql ALTER TABLE YOUR_DATABASE.YOUR_SCHEMA.YOUR_METRICS_TABLE SET DATA_RETENTION_TIME_IN_DAYS = 7; ALTER TABLE YOUR_DATABASE.YOUR_SCHEMA.YOUR_METRICS_TABLE SET CHANGE_TRACKING = TRUE; ``` > **Note:** Snowflake Standard Edition > > On Snowflake Standard Edition, the maximum retention time is one day. Set your sync frequency to 12 hours. ### Connect and configure Follow the instructions in [Snowflake Data Import](https://amplitude.com/docs/data/source-catalog/snowflake#set-up-and-verify-the-connection) to connect to your Snowflake instance. ## Data specifications Your metrics table must include specific required fields and can optionally include additional fields. You must include at least one metric or dimension field. ### Required fields | Field | Description | Example | | --- | --- | --- | | `time` | When the metric value is valid | `1762813185` | | `user_id` or `device_id` | A unique identifier for a user or device. | `user_12345` | > **Note:** Time conversion > > Amplitude requires the incoming time in milliseconds from the Unix epoch. Use Snowflake’s built-in conversion functions or other tooling in your data pipeline to convert to this format before Amplitude ingests the data. ### Optional fields | Field | Description | Example | | --- | --- | --- | | `insert_id` | A unique identifier for deduplication. | `51a87950-b35d-4a2f-b919-af92f00f75dd` | ### Metric fields Your metrics table must include at least one metric or dimension field. | Field Type | Description | Example | | --- | --- | --- | | Metric | Numeric value (integer or decimal) | `150.25` | | Dimension | String, boolean, or number for filtering/grouping | `"active"`, `true`, `10` | ### Example ```json { "time": "1762813185", "user_id": "user_12345", "total_revenue": 1543.5, "order_count": 12, "ltv": 15430.0, "health_score": "green", "is_paid": true } ``` ## Query template ```sql SELECT event_date AS "time", user_id AS "user_id", total_revenue AS "total_revenue", order_count AS "order_count", ltv AS "ltv", health_score AS "health_score", is_paid_customer AS "is_paid" FROM DATABASE_NAME.SCHEMA_NAME.METRICS_TABLE WHERE event_date >= CURRENT_DATE - INTERVAL '30 days' ``` ## Add your metric to an experiment Use Aggregated Metrics (fka Warehouse Metrics) in end-to-end experiments or experiment results as: - **Goals**: Measure impact on business metrics. - **Analysis metrics**: Understand how experiments affect revenue, LTV, and other KPIs. When you create or edit an experiment, select metrics from the Warehouse source in the metrics picker. > **Note:** Last synced information > > Aggregated Metrics (fka Warehouse Metrics) display when they were last synced and the next scheduled sync. ### Creating a warehouse metric in your experiment 1. In the experiment, navigate to the _Metrics_ panel. 2. Click **Create a custom metric**. 3. Enter a **Name** and **Description** for the metric. 4. Click the **Warehouse** tab. 5. Select the table you specified during data import. 6. Define the metric. Choose **Sum**, **User Average**, **Min**, or **Max**. 7. Select the column in the table you want to combine using the definition you selected. 8. Preview the results and click **Save**. > **Tip:** > > Aggregated Metrics (formally known as Warehouse Metrics) you created before appear in the _Add Metric_ dialog. You don't need to recreate them. ## Best practices 1. **Define metrics once**: Create metrics in your warehouse and reference them everywhere in Amplitude. 2. **Use descriptive names**: Name metrics clearly (like "Average Order Value" not "metric\_1"). 3. **Include descriptions**: Add descriptions in the Metrics creation flow to help users understand what each metric measures. 4. **Start with key metrics**: Begin with 5-10 critical metrics before expanding. ## Troubleshooting If you encounter issues with Aggregated Metrics (fka Warehouse Metrics), these common problems and solutions can help you resolve them. ### Sync failures - Ensure data retention period is at least seven days, unless you use Snowflake Standard Edition, then set it to one day. - Verify warehouse credentials haven't expired. - Check that the table structure hasn't changed. - Ensure Change Data Capture (CDC) is enabled in your Snowflake table or view. - Verify the sync completed successfully in the activity log. ## Limitations - Aggregated Metrics (fka Warehouse Metrics) require a unique user identifier per row. - Metric values can only be numeric (dimensions can be strings, numbers, or booleans). - Each metric represents a point-in-time value, not an event stream. - Amplitude doesn't support rollup or combined tables without unique user identifiers. - Aggregated Metrics (fka Warehouse Metrics) don't support CUPED or group by. ## Frequently asked questions ### Using Aggregated Metrics (fka Warehouse Metrics) without sending events to Amplitude Yes, but Aggregated Metrics (fka Warehouse Metrics) are most powerful when combined with behavioral events. You can create metric-only charts if needed. ### Differences between Aggregated Metrics (fka Warehouse Metrics) and profiles Profiles sync current user attributes. Aggregated Metrics (fka Warehouse Metrics) sync time-series numeric values that you can combine, use as experiment goals, and visualize over time. ================================================================================ # Connect to a source URL: https://amplitude.com/docs/data/sources/connect-to-source Updated: 2026-09-01 ================================================================================ # Connect to a source To connect a data source, select **Catalog** in the left navigation, choose the tile for the platform you want to add, and complete its setup instructions. A data source sends data from a third-party platform, warehouse, or event stream into Amplitude for analysis. Use a data source when you already have data flowing through one of these systems; if you're instrumenting your own app from scratch, use the [Amplitude SDKs](https://amplitude.com/docs/get-started/get-data-in) instead. ## Understand the interface The _Sources_ panel includes two tabs, **Sources List** and **Ingestion Debugger**. The **Sources List** tab shows the active data sources for a project, the activity status of each source, and the event volume each source sent in the last 30 days. The **Ingestion Debugger** tab shows three charts: successful requests, event and identify counts, and error requests for the endpoints you specify. You can view the last 3 hours or the last 90 days. Below the **Ingestion Debugger**, the throttled users and devices list shows which users and device IDs Amplitude has throttled in the last 30 minutes, plus any silenced device IDs. > **Note:** > > Only users with Manager permissions or higher can view throttled user IDs and device IDs in the **Ingestion Debugger**. Members and Viewers can't access the throttled users and devices list. ## Set up ingestion error alerts Configure email alerts to notify you when ingestion errors occur. Ingestion error alerts help you identify and resolve data quality issues before the issues affect your analysis. To set up ingestion error alerts, follow these steps: 1. Navigate to _Data > Sources_. 2. Select the **Ingestion Debugger** tab. 3. Select **Create A New Alert**. 4. Configure your alert settings: - **Ingestion Path**: Select the source of the error. For example, SDK or HTTP API. - **Error type**: Select the type of error that triggers the alert. - **Threshold**: Set the error rate or count that triggers an alert. - **Evaluation Window**: Set the frequency with which Amplitude checks for alerts. - **Recipients**: Add email addresses for notification recipients. - **Alert frequency**: Choose how often Amplitude sends alerts (for example, immediate, hourly, or daily). 5. Enable the alert and select **Create Alert**. After you set up alerts, Amplitude monitors ingestion error rates and sends email notifications when errors exceed your configured thresholds. Use these notifications to address data quality issues and maintain reliable analytics. > **Tip:** Best practices > > - Set up alerts for critical data sources that power key dashboards or reports. > - Include multiple team members as recipients so one person doesn't receive all alerts. > - Review and adjust thresholds periodically based on your typical error patterns. ## Add a data source To add a new data source, follow these steps: 1. In the left navigation, select **Catalog**. 2. Select the tile for the source you want to add. 3. Complete the setup for the source. Some sources redirect you to log in to your source account. Other sources show setup instructions on the source's **Set Up Connection** tab. ## Source notifications Notifications alert you when a source has an issue. By default, new sources notify the creator and Admins. ### Edit source notifications 1. In the left navigation, select **Sources**. 2. Select the source whose notifications you want to configure. 3. On the right side of the screen, select the email icon. The email icon tooltip says **Manage Notifications**. 4. Select **Subscribe** or **Unsubscribe** to change your notification subscription. To add or remove other email addresses, select **Manage Notifications**. ### Add source notifications to Slack 1. Follow [Slack's email guide](https://slack.com/help/articles/206819278-Send-emails-to-Slack#h_01F4WDZG8RTCTNAMR4KJ7D419V) to set up an email address for your Slack channel or DM. 2. Use the steps in _Edit source notifications_ to add that email address to the source notifications. ================================================================================ # Amplitude Wordpress plugin URL: https://amplitude.com/docs/data/amplitude-wordpress-plugin Updated: 2026-10-13 ================================================================================ # Amplitude Wordpress plugin The [Amplitude Wordpress Plugin](https://wordpress.org/plugins/amplitude/) instruments your Wordpress site with an advanced version of Autocapture. The Amplitude Wordpress plugin installs a version of the [Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) and adds the script before the `</head>` tag on each of your site's pages. The plugin enables an [advanced](https://github.com/amplitude/Amplitude-TypeScript/tree/main/packages/plugin-autocapture-browser) version of Autocapture that tracks the following events and associated properties: - Page viewed. - Form started. - Form submitted. - File downloaded. - Start session. - End session. - Element clicked (new in advanced DET). - Element changed (new in advanced DET). If you enable Session Replay in the plugin's settings, the plugin also initializes and adds the [Session Replay Browser SDK Plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin). ## Install the plugin Follow these instructions to install the Amplitude Wordpress plugin. 1. Log in to Wordpress and open your site's dashboard. 2. Click **Plugins** in the sidebar. 3. Click **Add New Plugin**. 4. Search for `Amplitude`. 5. Click **Install Now** on the Amplitude plugin. 6. When installation completes, click **Activate Plugin**. ## Configure the plugin With the Amplitude Wordpress plugin settings page open: 1. Enter your Amplitude project's [API key](https://amplitude.com/docs/apis/authentication). 2. (Optional) Enable Session Replay and set the [Sample Rate](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin#sampling-rate) with the slider. 3. Click **Save**. After you enable the plugin, confirm in Amplitude that your project receives data from the plugin. ## Session Replay If you enable Session Replay in the plugin, replays may not appear in Amplitude. This can happen for a few reasons: - Users must complete their interaction with the site, which happens when they close the browser or leave the site. Wait at least five minutes after a session ends before attempting to view the replay in Amplitude. You may need to refresh the Amplitude page you're on. - The sample rate you select determines the percentage of sessions that Session Replay captures. If you set the sample rate below `1`, Amplitude may not capture the specific session in question. - You don't have Session Replay enabled on your account. ## Autocapture The Wordpress plugin installs a version of the Browser SDK that enables a version of Autocapture that tracks two extra events: - `[Amplitude] Element Clicked`. - `[Amplitude] Element Changed`. These are high-volume events with a high degree of cardinality in the property values. However, Amplitude limits the "noise" to these two events and a specific set of properties, limiting the impact on your taxonomy. This approach differs from auto track or auto capture because it targets two specific interactions and a small set of elements to limit the impact of any noise in your data. ### Impact on event volume Autocapture impacts event volume because it adds new tracking, which results in more captured events. The amount of this increase depends on your organization. If you start with few precisely tracked events, expect a large increase in event volume. If your organization has an extensive tracking plan with many precisely tracked events, the impact is lower. For help or support with this plugin, contact [plugins@amplitude.com](mailto:plugins@amplitude.com). ================================================================================ # Amplitude Shopify Plugin URL: https://amplitude.com/docs/data/amplitude-shopify-plugin Updated: 2026-10-13 ================================================================================ # Amplitude Shopify Plugin [Shopify](https://www.shopify.com/) is a commerce platform that lets businesses of any size create, customize, and manage online stores. Shopify offers tools for product listings, payments, shipping, and customer engagement, streamlining the selling process online, across social media, and in person. The [Amplitude Shopify Plugin](https://apps.shopify.com/amplitude) brings data from your Shopify store into Amplitude, unlocking insights from funnel analytics, user behavior trends and charts, ROI analysis, Session Replay, and more. ## How the Shopify plugin works The Shopify plugin installs a version of the [Amplitude Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) and adds the script before the `</head>` tag of your site's pages. The script includes [Session Replay](https://amplitude.com/docs/session-replay) and [Web Experiment](https://amplitude.com/docs/web-experiment/set-up-a-web-experiment). > **Note:** Guides and Surveys > > The Shopify plugin doesn't include [Guides and Surveys](https://amplitude.com/docs/guides-and-surveys). To use Guides and Surveys on your Shopify store, install the [Guides and Surveys Web SDK](https://amplitude.com/docs/sdks/guides-and-surveys/sdk) separately. > **Warning:** Shopify and flickering > > The method Shopify uses to load Amplitude's Shopify app causes flickering. To avoid this, add the [asynchronous web script with the anti-flicker snippet](https://amplitude.com/docs/web-experiment/implementation#async-script-with-anti-flicker-snippet) to your `theme.liquid` file. The Shopify plugin captures Amplitude's default events, including [marketing attribution](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#track-marketing-attribution) and Shopify's standard [events](https://shopify.dev/docs/api/web-pixels-api/standard-events). #### Shopify plugin events and event properties | Event | Source | Properties | | --- | --- | --- | | Page viewed | Amplitude | Page counter, Page domain, Page location, Page path, Page title, Page URL, Session Replay ID (if enabled), Referrer, [Attribution](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#track-marketing-attribution), [User properties](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#user-properties). | | Start session | Amplitude | Session Replay ID (if enabled), [User properties](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#user-properties). | | End session | Amplitude | [User properties](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#user-properties). | | Form started | Amplitude | Form destination, Session Replay ID (if enabled), [User properties](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#user-properties). | | Form submitted | Amplitude | Form destination, Session Replay ID (if enabled), [User properties](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#user-properties). | | File downloaded | Amplitude | File extension, File name, Link text, Link URL, Session Replay ID (if enabled), | | Element clicked | Amplitude | Element Aria Label, Element Class, Element Hierarchy, Element href, Element ID, Element Parent Label, Element Position Left, Element Position Top, Element Selector, Element Tag, Element Text, Page Title, Page URL, Session Replay ID, Viewport Height, Viewport Width. | | Element changed | Amplitude | Element Class, Element Hierarchy, Element ID, Element Parent Label, Element Position Left, Element Position Top, Element Tag, Page Title, Page URL, Session Replay ID, Viewport Height, Viewport Width. | | Collection viewed | Shopify | Collection title | | Product viewed | Shopify | Quantity, SKU, Price, Currency Code, Type, Variant Title, Title, Vendor, Products | | Product added to cart | Shopify | Quantity, SKU, Price, Currency Code, Type, Variant Title, Title, Vendor, Products | | Product removed from cart | Shopify | Quantity, SKU, Price, Currency Code, Type, Variant Title, Title, Vendor, Products | | Checkout started | Shopify | Discounted amount, Total price, Currency code, Products | | Checkout contact info submitted | Shopify | -- | | Checkout address info submitted | Shopify | -- | | Checkout shipping info submitted | Shopify | -- | | Checkout completed | Shopify | Total tax, Discount amount, Subtotal price, Currency code, Customer id, Products | | Order created | Shopify | Customer, Products | | Search submitted | Shopify | Search query | In most scenarios, when a customer completes the checkout flow, Shopify sends the Checkout complete event, then the Order created event. If you create an order manually from your store's Admin page, only the Order created event sends. The Checkout complete event is specific to a customer completing the checkout flow. Amplitude sets User ID using the email address or phone number the customer enters in the Contact section of the checkout. > **Note:** Shopify checkout page > > Shopify prevents third-party packages from loading on your store's checkout page. As a result, Amplitude doesn't receive events from the checkout page, and you can't run experiments on it. ### Performance impact The packages that Amplitude adds to your Shopify pages weigh approximately 167kb. Internal testing showed Lighthouse performance reports averaging 98 without the plugin and 96 with the plugin. ## Install the plugin The method you use to install the Shopify plugin depends on whether you have an existing Amplitude organization. ### Install without an existing Amplitude organization 1. Find the [Amplitude Shopify plugin](https://apps.shopify.com/amplitude) in the Shopify App Store. 2. Click **Install** and confirm access to add it to your Shopify store. 3. Navigate to the [Amplitude Get Started page](https://analytics.amplitude.com/login?utm_source=shopify_app) and click to create your Amplitude account. Complete the form, agree to terms, and click **Continue**. > **Note:** Data Storage Location > > Amplitude provides data storage in the US and EU. Choose the appropriate option based on your location. 4. After you create your account, on the Amplitude setup page, click **Shopify** in the _Other ways to install_ section. 5. In the modal, copy your Amplitude project's API key. 6. Return to the Amplitude Settings screen in Shopify, enter the API key, and click **Connect**. ### Install into an existing Amplitude organization 1. Log in to Amplitude and navigate to your organization's settings. 2. Select the project within your organization that you want to connect to Shopify. 3. Find the project's API key and copy it. 4. Return to the Amplitude Settings screen in Shopify, enter the API key, and click **Connect**. ### Configure Session Replay sample rates 1. Log in to Amplitude as a manager and navigate to your organization's settings. 2. Click **Session Replay & Heatmaps** in the sidebar. 3. Select the project that matches the API key you used to install the Shopify app. 4. Input the sample rate you want under the Sampling section. 5. Save the settings. ================================================================================ # Track sessions URL: https://amplitude.com/docs/data/sources/instrument-track-sessions Updated: 2026-09-09 ================================================================================ # Track sessions A session is a continuous span when a user has your app in the foreground or your website open. Amplitude groups events into sessions by session ID, derives Start Session and End Session events, and exposes session counts and durations to the [User Sessions chart](https://amplitude.com/docs/data/user-properties-and-events). Use the default session tracking when you want Amplitude SDKs to manage session boundaries automatically. If you need session boundaries tied to specific events or a different timeout, configure a custom session definition instead. ## How Amplitude defines sessions Session behavior differs between mobile and browser applications: - For mobile, a session begins when the app moves into the foreground. A mobile session ends when the app goes into the background and sends no events for at least five minutes. Events sent within five minutes of each other count toward the current session. You can define a custom session expiration time with `setMinTimeBetweenSessionsMillis(timeout)`, where `timeout` is in milliseconds. - On a browser, a session begins when the website loads and the SDK initializes. A browser session ends when the last event occurs. Web sessions time out after 30 minutes by default. Events sent within 30 minutes of each other count toward the same session. You can customize the browser timeout window with the [Browser SDK configuration options](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2). Amplitude automatically generates a session ID for each new session. The session ID is the session's start time in milliseconds since epoch (also known as the [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time)). All events within the same session share the same session ID. Amplitude SDKs manage session IDs automatically. If you send data to Amplitude through the HTTP API, explicitly set the [session ID](https://amplitude.com/docs/apis/analytics/http-v2) field to track sessions. ### How Amplitude counts sessions To count sessions, Amplitude filters for events marked as "active," applies the project's session definition, groups the filtered events into sessions, and counts the grouped sessions. For more information about setting a project's session definition, review [Manage Organizations and Projects](https://amplitude.com/docs/admin/account-management/manage-orgs-projects#view-and-edit-your-project-information). ## How Amplitude groups events into sessions By default, Amplitude uses session ID as the session property. Amplitude groups all events with the same session ID and the same user ID into the same session. The session ID doesn't need to be unique across multiple users. You can change the property you use to group sessions. Amplitude SDKs automatically generate and manage session IDs for events. For events sent through the [HTTP API](https://amplitude.com/docs/apis/analytics/http-v2), Amplitude defaults to a session ID of `-1`. A session ID of `-1` excludes the event from all session metrics. > **Note:** > > A session ID of `-1` commonly occurs when data comes to Amplitude from Segment through a cloud-mode connection. As with data sent through the HTTP API, you need to explicitly set a session ID to track sessions. In a user's event stream, a blue line connects events in the same session. Amplitude assigns a session to a specific date based on its actual start time. The start time must fall within a chart's selected date range for Amplitude to include the session on that chart. For example, a session begins on May 17 at 8:00 PM and ends on May 18 at 1:30 AM. The session appears on charts where the selected date range includes May 17, the date when the session began. The date range for the example session can start on or before May 17 and end on or after May 17. If the chart's date range starts on May 18, the session doesn't appear on the chart, even though the session was still active on May 18. ### Start Session and End Session events By default, Amplitude derives `Start Session` and `End Session` events from each session's session ID. Amplitude also uses session ID to calculate session lengths. If you use session IDs, Amplitude doesn't add extra events to your monthly event volume limit. If you need `Start Session` and `End Session` events for analysis beyond session lengths, enable `Start Session` and `End Session` event tracking by adding the following code before initializing the SDK: For Android: ```java Amplitude amplitude = new Amplitude(new Configuration(apiKey = AMPLITUDE_API_KEY, context = applicationContext, trackingSessionEvents = true, )); ``` For iOS: ```objc [Amplitude instance].trackingSessionEvents = YES; ``` For Browser: ```js amplitude.init(API_KEY, OPTIONAL_USER_ID, { defaultTracking: { sessions: true, }, }); ``` ### Start Session and End Session limitations - Session event tracking applies only to Amplitude's [Android](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk), [iOS](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk), and [Browser](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) SDKs. - `Start Session` and `End Session` events count toward your monthly [event volume limit](https://amplitude.com/docs/faq/limits-and-quotas). - Amplitude sends the `End Session` event at the start of the user's next session. - By default, you can't add extra event properties to automatically generated `Start Session` and `End Session` events. To send event properties for session start and end events, you have two options: - Implement your own custom `Open App` and `Close App` events. - Use an [Enrichment Plugin](https://amplitude.com/docs/sdks/sdk-plugins#enrichment-plugins) to add properties to the generated session events. Enrichment plugins let you modify properties in Event objects. ### Out-of-session events You can log events outside a session by setting the session ID to `-1`. Out-of-session events aren't part of the current session and don't extend the current session. Out-of-session events are useful for events triggered by push notifications. Out-of-session events are usually server-side events received by Amplitude. For more information, refer to the [HTTP API](https://amplitude.com/docs/apis/analytics/http-v2) documentation. Out-of-session events appear in a user's event stream as disconnected green squares. ### Configure a custom session definition By default, Amplitude sorts events into sessions by session ID. You can define sessions without adding instrumentation. A custom session definition can use a constant property, a custom timeout window, or beginning and ending events. You need Admin or Manager privileges to edit session definitions. > **Note:** > > Custom session definitions are only available in the User Sessions and Pathfinder charts and user timelines. Sessions only include active events. To configure a custom session definition: 1. From the left sidebar, navigate to _Settings > Projects_. 2. Select the project you want to work with. 3. Select **Session Definitions**. The _Session Definitions_ modal appears. 4. Select **Custom Session Definition**. 5. Configure one or more conditions: - **Session property**: Select **Select property...** and choose the event or user property for grouping sessions. - **Starting Event and Ending Event**: Select **Starting Event** or **Ending Event** and choose the events that mark the beginning and end of a session. The ending event ends a session if the ending event occurs before the timeout interval elapses. - **Session timeout**: Enter the default timeout interval in minutes. Amplitude counts events from the same user that occur within the specified timeout interval as part of one session. Amplitude recommends a default of 30 minutes. 6. Enter the confirmation phrase and select **Save**. > **Note:** > > Changing the session definition applies to all User Sessions, Funnel Analysis, and Journeys charts, and to the session metric in your project. Review the impact before you configure or change a custom session definition. Amplitude combines conditions with and logic. A session must meet all configured conditions to count. If you don't configure any conditions, Amplitude uses session ID as the session-defining property. To require all events in a session to come from the same source, use session property and timeout window together: - Session property = `device ID` - Session timeout = `30 min` To define sessions based on in-app usage, use starting event and timeout window: - Start event = `app open` - Session timeout = `5 min` ================================================================================ # Track revenue URL: https://amplitude.com/docs/data/sources/instrument-track-revenue Updated: 2026-09-01 ================================================================================ # Track revenue A revenue event captures a purchase using the `price`, `quantity`, `currency`, and `revenue` fields. This page covers how to instrument revenue events with the iOS, Android, and Browser SDKs and the HTTP API so they appear in the [Revenue LTV](https://amplitude.com/docs/analytics/charts/revenue-ltv/revenue-ltv-track-new-user-monetization) chart. Only revenue events that include [revenue properties](#revenue-properties) appear in the chart, which includes both verified and unverified events. To send revenue events, refer to the following documentation: - [iOS SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk) - [Android SDK](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk) - [Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) - [HTTP API](https://amplitude.com/docs/apis/analytics/http-v2). Set the `price`, `quantity`, `currency`, and `revenue` fields to record the event as a revenue event. Amplitude counts only events that you send through the Amplitude ingestion system. Amplitude doesn't count computed events separately. Additional events attached to revenue events, such as `Revenue (Verified)` or `Revenue (Unverified)`, don't count toward your limit. ## Revenue properties Amplitude needs revenue properties to track revenue: - Send `$revenue` directly, or send `$price`. In most cases, include `$quantity`. - Amplitude calculates revenue with the formula `$price * $quantity`. If `$quantity` isn't present, Amplitude uses 1. | Name | Type | Description | Default | | --- | --- | --- | --- | | $revenue | Double | The total revenue from the user's purchase. Negative values are valid. You must send `$revenue` if you want the revenue event to appear in a Revenue LTV chart. | null | | $price | Double | The price of the products purchased. Negative values are valid. | null | | $productId | String | An identifier for the product. | null | | $quantity | Integer | The quantity of products purchased. Defaults to one if not specified. | 1 | | $revenueType | String | The type of revenue, for example, tax, refund, or income. | null | | $currency | String | The currency for the purchased item. Use a three-character uppercase [ISO 4217](https://www.iban.com/currency-codes) code, for example, USD or EUR. | null | | eventProperties | Object | An object of event properties to include in the revenue event. You can only segment on the included event properties in the [Event Segmentation](https://amplitude.com/docs/analytics/charts/event-segmentation/event-segmentation-build) chart. | null | You must explicitly send revenue properties using Amplitude's SDKs or server-side when you log revenue events. ## Track non-in-app purchases For purchases that aren't in-app purchases, there are three ways to send revenue data to Amplitude: - Use Amplitude's [SDKs](https://amplitude.com/docs/sdks/analytics) to call the `logRevenueV2` function. The `logRevenueV2` function generates `Revenue` events. - Use Amplitude's SDKs to call the `logEvent` function if you include the `$revenue` property. - Use Amplitude's HTTP API by setting the `price`, `quantity`, or `revenue` fields. Add your own event name, for example, `Purchase completed`. > **Note:** > > Amplitude performs verified revenue checks only for in-app purchases. ## Track in-app purchases (IAPs) To track IAPs, send revenue events the same way you send regular revenue events, using `logRevenueV2` or `logEvent` (with the `$revenue` property) in Amplitude's SDKs. For IAPs, you can validate purchases by passing receipt data with the revenue event. ### Enable revenue verification To enable revenue verification, copy your iTunes Connect In App Purchase Shared Secret or your Google Play License Public Key into the Sources section of your project in Amplitude Data. You must include a key for each Amplitude project where you want revenue verification. You also need to pass in receipt data for Amplitude to verify the revenue event. Amplitude can create three revenue event types from the SDK `logRevenue` call. The SDK revenue event types are separate from revenue events sent server-side through the HTTP API: | Event type | Description | | --- | --- | | `Revenue` | Amplitude logs `Revenue` for revenue events, whether revenue verification is on or off. The `Revenue` event doesn't populate the `$revenue` property. `Revenue (Verified)` and `Revenue (Unverified)` events populate `$revenue`. To include SDK revenue events in a Revenue LTV chart, turn revenue verification on. If revenue verification is on and the user activity stream shows only `Revenue`, the revenue failed verification. | | `Revenue (Verified)` | Amplitude logs `Revenue (Verified)` for legitimate transactions. The count difference between `Revenue` and `Revenue (Verified)` is the number of illegitimate app purchases. By default, revenue events recorded on SDKs appear in Amplitude dashboards as unverified revenue events. To generate `Revenue (Verified)` events, enable revenue verification. | | `Revenue (Unverified)` | An unverified revenue event didn't necessarily fail verification. An unverified event means Amplitude didn't attempt verification because the event came through the HTTP API or JavaScript SDK, or because your project didn't include revenue verification keys. If revenue verification is off, Amplitude logs `Revenue (Unverified)` for all revenue events. | > **Note:** > > You can switch verification on or off only for mobile. Web always tracks `Revenue` and `Revenue (Unverified)`. Amplitude displays revenue that doesn't fail verification. You may see both `Revenue (Verified)` and `Revenue (Unverified)` if, for example, you send both mobile and web revenue events through Amplitude SDKs. ### Receipt validation Amplitude validates in-app purchases based on the receipt from [Apple](https://developer.apple.com/library/content/releasenotes/General/ValidateAppStoreReceipt/Chapters/ValidateRemotely.html#//apple_ref/doc/uid/TP40010573-CH104-SW1) or [Google](https://developer.android.com/google/play/billing/billing_integrate.html#Purchase). ### Discrepancies Discrepancies between app store reports and Amplitude can come from time zone differences, event generation bugs, or piracy. If the discrepancy is minor and consistent day to day, the most likely cause is a time zone difference between the app store and Amplitude. Amplitude uses UTC. If the app store uses a different time zone, the app store may report a purchase event on a different day than Amplitude. No data is lost. Major discrepancies can come from client-side errors, such as the store purchase callback running multiple times for a single purchase. Call revenue events only after a successful store purchase. The following calls track the event property and revenue amount: ```plaintext AmplitudeClient.getInstance().logEvent('IAP', {type='Sale Special'}) ``` ```plaintext AmplitudeClient.getInstance().logRevenueV2("com.company.productid", 1, 2.99) ``` Piracy can also cause major discrepancies. Users can circumvent the app store and make purchases that don't appear in app store reports. To exclude pirated revenue events from your data, use Amplitude's revenue verification method. If you suspect piracy heavily skews your data, contact [Amplitude Support](https://help.amplitude.com/hc/en-us/requests/new). ### Considerations for developers Review the following points when you track revenue events: - Backward compatibility: The existing `logRevenue` methods still work but are deprecated. Events logged with the old methods miss fields such as `revenueType`, so the Amplitude platform limits segmentation on those revenue events. - Opting users out of logging: You can turn off logging for a given user by calling `setOptOut`: ```plaintext amplitude.getInstance().setOptOut(true); ``` Amplitude doesn't save or send events to the server while opt out is enabled. The opt out setting persists across page loads. You can reenable logging by calling: ```plaintext amplitude.getInstance().setOptOut(false); ``` ================================================================================ # Track unique users URL: https://amplitude.com/docs/data/sources/instrument-track-unique-users Updated: 2026-09-09 ================================================================================ # Track unique users Amplitude counts unique users by combining three identifiers (device ID, user ID, and Amplitude ID) into a single profile across anonymous sessions, sign-ins, and multiple devices. Send a stable user ID as soon as a person authenticates so anonymous events on the same device merge into one profile and your active-user counts stay accurate. ## How Amplitude identifies unique users The three IDs work like this: - **Device ID:** For mobile applications, Amplitude pulls the Identifier for Vendors, [IDFV](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk#advertiser-id), or generates a random alphanumeric string for the device ID. For web applications, Amplitude sets the device ID to a randomly generated Universally Unique Identifier, [UUID](https://amplitude.com/docs/sdks/analytics/flutter/flutter-sdk#set-a-custom-device-id), by default. The device ID persists unless a user clears browser cookies or browses in private mode. - **User ID:** You configure the user ID. Many products use a username or an internal unique identifier as the user ID. Use a stable value for the user ID. Don't assign anonymous users a user ID. Anonymous users still have Amplitude IDs and device IDs, so Amplitude might recognize them as the same user later. - **Amplitude ID:** After Amplitude receives a device ID, a user ID, or both, Amplitude generates the Amplitude ID and associates it with the collected identifiers. Amplitude needs only one identifier to generate an Amplitude ID. Amplitude prefers the user ID because multiple unique users could share the same device. > **Note:** > > If Amplitude encounters a known device ID that is already tied to a user ID in a different project, Amplitude assumes the device ID is tied to that user ID in all projects, even if you don't have the Portfolio add-on. For more information, refer to [Portfolios](https://amplitude.com/docs/admin/account-management/portfolio). When multiple projects reside in a single organization, all projects must use the same variable as the user ID. Using the same user ID variable prevents tracking discrepancies. For example, if one project uses email addresses as user IDs and another project uses phone numbers, Amplitude doesn't merge those identifiers into the same Amplitude user profile. If you're on [MTU billing](https://amplitude.com/docs/admin/billing-use/mtu-guide), you might incur charges for multiple users. ### Use advertising identifiers as the device ID You can configure Amplitude to use the Identifier for Advertiser, [IDFA for iOS](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk), and the Advertising Identifier, [AdID for Android](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk), as the device ID. For more information, refer to the relevant SDK installation guide. Using advertising identifiers causes the device ID to persist across installs. iOS users can reset the IDFA on their devices at any time. As of iOS 10, if a user limits ad tracking, iOS returns an IDFA of all zeros. Amplitude instead sets the device ID to either the IDFV or a randomly generated string. Android users can reset the AdID on their devices at any time. ### Set up cross-domain tracking You can track anonymous behavior across two domains. For example: - Site 1: `https://www.landingpage.com`. - Site 2: `https://www.productpage.com`. To track an anonymous user who starts on Site 1 and navigates to Site 2, pass both the device ID and session ID from Site 1 as URL parameters to Site 2. Passing only the device ID preserves anonymous identity but doesn't maintain session continuity. Sessions that split across the domain boundary can distort session-based metrics like traffic source analysis. For Browser SDK 2 (`@amplitude/analytics-browser` v2.8.0 and later): 1. From Site 1, get the device ID from `amplitude.getDeviceId()` and the session ID from `amplitude.getSessionId()`. 2. Pass both values to Site 2 as URL parameters when the user navigates. For example: `https://www.productpage.com?ampDeviceId=DEVICE_ID&SessionId=SESSION_ID`. 3. Initialize the Amplitude SDK on Site 2 with `amplitude.init('YOUR_API_KEY')`. The SDK reads `ampDeviceId` and `ampSessionId` from the URL automatically. > **Note:** > > A custom time-based session definition can supplement session-based reporting, but it doesn't replace passing `ampSessionId` for true SDK session continuity across domains. For full implementation details, refer to [Cross-domain tracking](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#cross-domain-tracking) in the Browser SDK 2 documentation. ## How Amplitude assigns Amplitude IDs The following scenarios show how Amplitude uses device IDs and user IDs to generate a new Amplitude ID or apply an existing Amplitude ID. ### No user ID exists If your product doesn't assign user IDs, Amplitude generates an Amplitude ID when Amplitude sees a particular device ID for the first time. | Device ID | **User ID** | **Amplitude ID** | | --- | --- | --- | | A | null | 1 | | B | null | 2 | | B | null | 2 | | C | null | 3 | | A | null | 1 | | C | null | 3 | There are three unique users in this set. The first event from each device gets a new Amplitude ID. Later events from the same device reuse the existing Amplitude ID. In this example, device A uses Amplitude ID 1, device B uses Amplitude ID 2, and device C uses Amplitude ID 3. ### User ID follows anonymous events If your product assigns user IDs, Amplitude assumes previous anonymous events on that device belong to a single user until Amplitude receives an event with a user ID. Amplitude then applies the same Amplitude ID to the anonymous events and the identified event. | **Device ID** | **User ID** | **Amplitude ID** | | --- | --- | --- | | G | null | 4 | | G | null | 4 | | G | John | 4 | There is one unique user in this set. Amplitude logs the first two events anonymously on device G and assigns them Amplitude ID 4. The third event is the first event from device G that includes a user ID. Amplitude assigns John the same Amplitude ID as the anonymous events, so Amplitude counts one unique user. ### Same user ID on multiple device IDs, with no anonymous events Amplitude prioritizes user IDs over device IDs when assigning an Amplitude ID. | **Device ID** | **User ID** | **Amplitude ID** | | --- | --- | --- | | K | Zack | 5 | | L | Zack | 5 | There is one unique user in this set. User Zack sent an event on device K, and Amplitude assigned Amplitude ID 5. Whenever Zack's user ID appears again on any device, Amplitude assigns the event Amplitude ID 5, regardless of the device ID. ### Multiple user IDs on the same device If Amplitude receives an anonymous event after at least one user ID has appeared on that device, Amplitude assumes the last known user sent the anonymous event and assigns the event that user's Amplitude ID. | **Device ID** | **User ID** | **Amplitude ID** | | --- | --- | --- | | R | Jane | 6 | | R | null | 6 | | R | Mary | 7 | | R | null | 7 | | R | null | 7 | There are two unique users in this set. Jane logs the first event on device R, and Amplitude assigns Amplitude ID 6. Amplitude receives the next event anonymously, for example after Jane logs out, but still assigns Amplitude ID 6 because Jane was the last known user. Mary sends the third event on device R, and Amplitude assigns Amplitude ID 7. Amplitude receives the next two events anonymously and assigns them Amplitude ID 7. Amplitude assumes Mary sent those events because she was the last known user. If you want to explicitly log users out or log events under an anonymous user, set the user ID to null and regenerate a new device ID. Follow the instructions in the [iOS](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk) or [Android](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk) SDK documentation. ### Same user ID on multiple devices, with anonymous events | **Device ID** | **User ID** | **Amplitude ID** | | --- | --- | --- | | Y | David | 8 | | Z | null | 9 | | Z | David | 8 | | Z | null | 8 | David logs an event on device Y, and Amplitude assigns Amplitude ID 8. Next, an anonymous user logs an event on device Z, and Amplitude assigns Amplitude ID 9 because no user is associated with the device. Then David logs into the product on device Z. The sign-in event has Amplitude ID 8 because Amplitude ID 8 belongs to David. Finally, Amplitude logs an event anonymously on device Z. The anonymous event receives Amplitude ID 8. David was the last known user, so Amplitude attributes the event to him. In this scenario, the anonymous events on device Z have two different Amplitude IDs, even though only one user ID is associated with the device. Amplitude interprets Amplitude IDs 8 and 9 as a single user: David. When Amplitude detects the relationship between Amplitude IDs 8 and 9, Amplitude merges the IDs, so Amplitude counts only one user. The merge can only happen because the event with Amplitude ID 9 didn't have a user ID present. > **Note:** > > If you're using Redshift, the data is immutable, and the anonymous event still has Amplitude ID 9 in the raw data. For more information, refer to [Merged users](#merged-users). ## Merged users Merged users occur when Amplitude determines that an anonymous user, such as a user whose only ID is a device ID, is a recognized user with an Amplitude ID. For example, a user gets a new device and logs events in your product anonymously before signing in. To Amplitude, these anonymous events look like they come from a new user, so Amplitude maps them to a new Amplitude ID. When the user logs into their existing account, Amplitude maps all subsequent events to that user's existing Amplitude ID. The separate Amplitude IDs create two problems: - Amplitude counts the user twice in active and new user counts. - Amplitude doesn't attribute events received while the user was anonymous to the true Amplitude ID and the user's actual user ID. Amplitude solves duplicate Amplitude IDs by cross-referencing the list of Amplitude IDs with an internal mapping of merged Amplitude IDs. Merged Amplitude IDs belong to the same user. Amplitude applies merged user mapping when you query on the dashboard. You can view a list of a user's merged IDs in their User Activity page, along with the merge times. > **Note:** Important note > > - Amplitude can't merge user IDs. If you create a new user ID for an existing user, Amplitude recognizes them as different unique users. > - Merged user mapping doesn't apply to raw data in Amazon [Redshift](https://amplitude.com/docs/data/destination-catalog/amazon-redshift), because the database contains raw event logs and not a merged users table. Without merged user mapping, Amplitude has observed an average change of about 5% in DAU numbers, with a higher-than-average change for web data. ### Event IDs, device IDs, and merging users After Amplitude merges users, the event ID count continues on a device-by-device basis: | **Device ID** | **User ID** | **Amplitude ID** | **Event ID** | | --- | --- | --- | --- | | A | null | 8 | 1 | | A | David | 8 | 2 | | A | David | 8 | 3 | | B | null | 9 | 1 | | B | David | 8 | 2 | | B | David | 8 | 3 | If a user clears product data, for example by deleting and reinstalling the app, the event ID resets to 1. When a user deletes and reinstalls the app, Amplitude usually generates a new device ID as well, which then triggers a new merge. After Amplitude merges users, a merged user might lose user property values that should stay unchanged, such as `Start Version` or initial UTM parameters, because the new user property values overwrite the original user property values. If merged users affect your user property values, contact Amplitude Support. ================================================================================ # Connect to a Destination URL: https://amplitude.com/docs/data/destinations Updated: 2026-09-22 ================================================================================ # Connect to a Destination Amplitude Data makes it easy to set up third-party platforms as data export destinations. You can share data generated in Amplitude with other tools and stakeholders in a variety of contexts. ## Plan availability Real-Time Streaming and Scheduled Syncs vary by plan. Some features need a higher plan or an add-on. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details. | Plan | Real-Time Streaming | Scheduled Syncs | | --- | --- | --- | | Free | 1M/month events & user property updates | Not included | | Plus | 1M/month events & user property updates | Not included | | Growth | 1M/month events & user property updates (add-on: Custom) | Limited 2 syncs (add-on: Unlimited) | | Enterprise | 1M/month events & user property updates (add-on: Custom) | Limited 2 syncs (add-on: Unlimited) | AMPL to 3rd Party Real-Time Cohort Syncs is available as an add-on on the Growth and Enterprise plans. Webhooks is available on the Plus, Growth, and Enterprise plans. One-Time Syncs and Warehouses are available on all plans. _Availability reflects the latest Amplitude plans. If your organization is on an older plan, your access may differ. Check your plan under [Plans & Billing in your organization settings](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._ ## Add a destination To add a new data destination, follow these steps: 1. From Amplitude Data, open the **Destinations** tab in the Connections section. 2. Click **Add Destination**. 3. Look for the tile or search for the name of the destination you want to add and click to select it. 4. Enter the requested information into the pop-up modal. The specific information required varies from destination to destination. 5. Click **Save**. ## Destination notifications Notifications alert you when you have an issue with your destination. By default, new destinations notify the creator and your Admins. ### Edit your notifications 1. Click **Destinations**. 2. Find the destination you want to configure notifications for, then click to select it. 3. Hover over the **Notifications Button** with an email icon on it. Click the **Manage Notifications** button when it appears. 4. From the Manage Notifications settings, you can **Subscribe** or **Unsubscribe** yourself. You can also manage notifications to add or remove other email addresses. ### Add notifications to Slack 1. Follow [this guide](https://slack.com/help/articles/206819278-Send-emails-to-Slack#h_01F4WDZG8RTCTNAMR4KJ7D419V) to set up an email for your Slack channel or DM. 2. After your Slack/email integration is complete, edit your [notifications](#edit-your-notifications) to add that email to your destination's notifications. ================================================================================ # Streaming transformations URL: https://amplitude.com/docs/data/streaming-transformations Updated: 2026-09-09 ================================================================================ # Streaming transformations Streaming transformations send transformed data from your Amplitude taxonomy, including custom events, derived properties, transformed events, and transformed properties, to your event streaming destinations, so downstream tools receive cleaned and enriched data instead of raw events. Select any transformation when you configure event streaming. You must define the transformation in Amplitude Data before you can stream it. Refer to [Transformations](https://amplitude.com/docs/data/transformations) to create custom events, derived properties, and other transformation types. ## Setup 1. In Amplitude Data, click **Catalog** and select the **Destinations** tab. 2. In the Event Streaming section, click on any streaming destination tile. 3. Enter a sync name, then click **Create Sync**. 4. Toggle _Status_ from **Disabled** to **Enabled**. 5. Paste your destination's Server Secret Key. 6. Toggle **Send events** to enable event streaming. 7. In _Select and filter events_, choose which events to send. Select only the events needed for your downstream destination. The dropdown includes any transformed events from your taxonomy. 8. (optional) In _Select additional properties_, select any event properties (including transformed event properties) to include. By default, Amplitude doesn't send any additional properties unless you explicitly select them. 9. (optional) In _Select additional user properties_, select any user properties to include. By default, Amplitude doesn't send any additional user properties unless you explicitly select them. 10. When satisfied with your configuration, click **Save**. ## Example use cases ### Streaming renamed events to AppsFlyer AppsFlyer requires unique event names for attribution and doesn't support event properties. Previously, you had to create custom events in your backend and resend them to Amplitude. You can now use Amplitude Data to rename events before streaming them to AppsFlyer, which reduces duplicate ingestion. ### Streaming derived properties to Braze To improve campaign effectiveness, you can stream derived properties from Amplitude to Braze. Select derived properties in your sync filters and include them when configuring additional properties. This enables more targeted campaigns using enriched event data from Amplitude. ## Considerations Note the following when streaming transformations from Amplitude: - Amplitude sends selected event and user properties along with the event. - Amplitude targets an end-to-end p95 latency of 60 seconds. Amplitude streams 95% of events within 60 seconds. Amplitude has internal processes, monitors, and alerts in place to meet this target. ## Transformation payload structure The streaming payload includes transformations as nested JSON fields. Understanding this structure is essential when using custom FTL (FreeMarker Template Language) templates or configuring how your destination receives data. ### Selection requirement You must explicitly select transformations in your sync configuration to include them in the streaming payload. You can select transformations in: - _Select and filter events_: For example, filtering events where a derived property isn't `null`. - _Select additional properties_: To include specific transformed properties. - _Map properties to destination_: When mapping properties to your destination's schema (if applicable). The streaming payload only includes transformations you explicitly select. ### JSON structure The payload includes transformations as nested JSON objects. The top-level field name depends on the transformation type: | Transformation Type | Top-level JSON Field Name | | --- | --- | | Merged properties | N/A (replaced in original field) | | Derived properties | `derived_properties` | | Channel properties | `derived_properties` | | Lookup properties | `lookup_properties` | Field names within these objects match the transformation names displayed in the Amplitude UI. ### Example payload If you select a derived property called `sample_derived_property_key1`, the streaming payload looks like this: ```json { "event_type": "Button Clicked", "user_id": "12345", "derived_properties": { "sample_derived_property_key1": "whatever_value" } } ``` ### Using transformations with custom FTL If your destination uses custom FTL templates, you can access transformation data using these patterns. #### Example 1: Using FtlUtils to serialize derived properties ```ftl <#assign UtilClass=statics['com.amplitude.integrations.connector.utils.FtlUtils']> { "version": "derived_properties_sample_ftl1", "derived_properties": ${UtilClass.toJson(input.derived_properties)} } ``` #### Example 2: Manually iterating over derived properties ```ftl <#assign UtilClass=statics['com.amplitude.integrations.connector.utils.FtlUtils']> { "version": "derived_properties_sample_ftl2", "derived_properties": { <#list input.derived_properties?keys as key> "${key}": "${input.derived_properties[key]}"<#sep>,</#sep> </#list> } } ``` ## Customize payloads with FreeMarker (FTL) Event streaming destinations that expose a custom payload editor use [Apache FreeMarker](https://freemarker.apache.org/) (FTL) to turn the Amplitude event into the JSON body your destination expects. The editor in the connector builder provides autocomplete, hover documentation, and inline validation for the fields and helpers below. For the FreeMarker language itself, refer to the [guide to creating templates](https://freemarker.apache.org/docs/dgui.html). ### The input object `input` is the event (or user) Amplitude forwards. Access its fields with dot notation, wrapped in `${ }` to output the value: ```ftl "${input.user_id}" "${input.event_type}" "${input.event_time}" ``` Commonly available fields include `event_type`, `user_id`, `device_id`, `time`, `event_time`, `session_id`, `platform`, `event_properties`, `user_properties`, `group_properties`, and `groups`, plus any transformations you select (`derived_properties`, `lookup_properties`). For the complete shapes, refer to the [event format](https://amplitude.com/docs/apis/analytics/export) and [user (Identify) format](https://amplitude.com/docs/apis/analytics/identify). > **Warning:** Fields aren't guaranteed > > `input` fields depend on how each user instruments events, and a selected event property might not be present on every event you stream. Reference fields defensively (refer to [Handle missing fields](#handle-missing-fields)), and keep required-field usage to common fields like `user_id`, `event_type`, and `event_time`. The payload editor flags a referenced property that isn't present on all of the events you selected. ### Dot and bracket notation Use dot notation when a property name is a valid identifier, and bracket notation when the name contains spaces or other special characters: ```ftl ${input.event_properties.plan} ${input.event_properties["Plan Type"]} ``` ### Handle missing fields Because fields aren't guaranteed, guard against missing values: - `??` tests whether a value exists: `<#if input.user_id??>…</#if>`. - `!` supplies a default when a value is missing: `${input.user_properties.email!}` (empty string) or `${input.revenue!0}`. ```ftl { <#if input.user_id??> "external_id": "${input.user_id}", </#if> "email": "${input.user_properties.email!}" } ``` ### Useful built-ins FreeMarker built-ins (`?name`) transform values. Common ones for JSON payloads: | Built-in | Use | | --- | --- | | `?c` | Format a number for computers, with no locale grouping or scientific notation. Use for numeric JSON values: `${input.revenue?c}` | | `?json_string` | Escape a string for safe use inside a JSON string: `"${value?json_string}"` | | `?keys` | Get an object's keys to iterate with `<#list>` | | `?is_number`, `?is_boolean`, `?is_string` | Test a value's type before serializing it | ### Iterate over properties Use `<#list>` with `?keys`, and `<#sep>` to place commas between items only: ```ftl "user_properties": { <#list input.user_properties?keys as key> "${key}": ${UtilClass.toJsonString(input.user_properties[key])}<#sep>,</#sep> </#list> } ``` ### Helper methods (FtlUtils) Amplitude exposes helper methods for serializing values and other common transforms, so you don't have to hand-write the logic. Assign the helper once at the top of the template, then call its methods: ```ftl <#assign UtilClass=statics['com.amplitude.integrations.connector.utils.FtlUtils']> { "user_properties": ${UtilClass.toJson(input.user_properties)} } ``` | Method | Returns | Description | | --- | --- | --- | | `toJson(value)` | string | Serializes a value to JSON. Maps, lists, and JSON values become JSON; scalars become a quoted JSON string (for example, `42` becomes `"42"`). | | `toJsonString(value)` | string | Alias of `toJson`. | | `dateStringToIso(dateTime)` | string | Converts an Amplitude datetime string to ISO 8601. | | `dateStringToEpochSeconds(dateTime)` | number | Converts an Amplitude datetime string to epoch seconds. | | `dateStringToEpochMillis(dateTime)` | number | Converts an Amplitude datetime string to epoch milliseconds. | | `epochSecondsToIso(seconds)` | string | Converts epoch seconds to ISO 8601. | | `epochSecondsTextToIso(text)` | string | Converts epoch seconds provided as text to ISO 8601. | | `epochMillisToIso(millis)` | string | Converts epoch milliseconds to ISO 8601. | | `isValidEmail(value)` | boolean | Returns whether the value is a valid email address. | | `sha256(value)` | string | Returns the SHA-256 hash of the value. If the value is already a 64-character hash, returns it unchanged. | | `cleanJsonPropertyName(name)` | string | Replaces whitespace with underscores and removes other non-alphanumeric characters. | | `getDisjointMap(source, filter)` | map | Returns the entries of `source` whose keys aren't present in `filter`. | > **Note:** Destination-specific helpers > > Some destinations provide additional helper methods tailored to that destination. You can use those helpers only in that destination's template. ### Examples Each example shows the input event Amplitude forwards, the template you write, and the result Amplitude sends to your destination. #### Simple: rename and pick fields Map a few input fields into the shape your destination expects. Input event: ```json { "event_type": "Song Played", "user_id": "user-123", "event_time": "2024-01-15T09:30:00.000", "event_properties": { "song_id": "abc-987" } } ``` Template: ```ftl { "external_id": "${input.user_id}", "name": "${input.event_type}", "song": "${input.event_properties.song_id}" } ``` Result: ```json { "external_id": "user-123", "name": "Song Played", "song": "abc-987" } ``` #### Complex: guards, bracket notation, and iteration Guard an optional field with `??`, read a property whose name has a space with bracket notation, format a number with `?c`, and serialize all user properties by looping with `<#list>`, emitting numbers and booleans raw and everything else through `toJsonString`. Input event: ```json { "event_type": "Purchase Completed", "user_id": "user-123", "revenue": 12.5, "event_properties": { "Item Name": "Pro Plan" }, "user_properties": { "email": "alex@example.com", "plan": "pro", "age": 30 } } ``` Template: ```ftl <#assign UtilClass=statics['com.amplitude.integrations.connector.utils.FtlUtils']> { "event": "${input.event_type}", <#if input.user_id??> "user_id": "${input.user_id}", </#if> "item": "${input.event_properties["Item Name"]}", "revenue": ${input.revenue?c}, "traits": { <#list input.user_properties?keys as key> <#assign value = input.user_properties[key]> "${key}": <#if value?is_number || value?is_boolean>${value}<#else>${UtilClass.toJsonString(value)}</#if><#sep>,</#sep> </#list> } } ``` Result: ```json { "event": "Purchase Completed", "user_id": "user-123", "item": "Pro Plan", "revenue": 12.5, "traits": { "email": "alex@example.com", "plan": "pro", "age": 30 } } ``` ## Supported custom events Amplitude supports streaming custom events that meet specific criteria. When you create custom events in the Amplitude taxonomy, you can select them for event streaming if they have: - **Supported properties**: User properties and event properties only. - **Supported operators**: `is`, `is not`, `contains`, and `does not contain`. Custom events that use other property types or operators aren't available for selection in event streaming configurations. ## Limitations Streaming transformations from Amplitude has some limitations: - When you rename custom events or derived properties, update any existing sync configurations that reference them. Syncs require current event and property names to work properly. Note that changing the underlying definition of a transformation doesn't affect syncing. Only name changes require sync updates. - **Lookup properties**: You can stream lookup properties by requesting access from Amplitude. Lookup properties map existing event or user properties to new properties using a CSV file upload and can enrich already-ingested events at query time. - Lookup property files with over 1000 rows don't display in the streaming setup. - After you save a lookup property file, it can take up to one hour to populate into the streaming system. - **Channel classifiers**: To stream channel classifiers, request access from Amplitude. Channels act like derived properties applied in real time during queries. Marketers primarily use channels to define acquisition channels based on UTM and referrer data. By default, you can't select channel properties in sync configuration (event filters or additional properties) unless Amplitude has already enabled this feature for your organization. - You can stream transformations to all streaming destinations except Data Warehouse destinations. - The streaming setup doesn't support the following transformation types: - Custom events that don't meet the criteria in the [Supported custom events](#supported-custom-events) section. - Group properties. - Cart properties. - Nested properties (for example, derived properties that rely on other derived properties). Exception: the UI allows selecting nested properties based on merged or cart properties, but they don't work in practice. ## FAQ #### Does this impact my event volume streaming limit? Yes, streaming transformations count towards your existing event streaming volume limit. Check your event streaming limit by navigating to _Settings > Plans & Billing_. #### Can I select both raw and transformed events/properties? Yes, you can select both raw and transformed versions in your streaming sync. For example, if a transformation merges three event types into one transformed event, all four event types (the three originals plus the merged version) appear in the selection dropdown. #### How does Amplitude handle custom events and transformed properties during streaming? Custom events and transformed properties follow the configurations set in your Amplitude Data taxonomy. Amplitude applies transformations before it streams the data to the destination. #### How can I enable channel classifiers for my event stream? Amplitude can enable channel classifier selection in event streaming sync configurations on request. Email integrations@amplitude.com with your organization ID and app IDs to request access. ================================================================================ # Sync Cohorts with Destinations URL: https://amplitude.com/docs/data/sync-cohorts-with-destinations Updated: 2026-09-22 ================================================================================ # Sync Cohorts with Destinations Cohort sync pushes cohorts to third-party [destinations](https://amplitude.com/docs/data/destination-catalog) such as ad networks, attribution providers, and marketing automation platforms. Amplitude offers three cadences: a one-time export, a scheduled hourly or daily refresh, and a real-time stream that checks for updates every minute. The cadence you pick also determines which destinations accept the sync. ## Plan availability AMPL to AMPL real-time cohort sync varies by plan. Some features need a higher plan or an add-on. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details. | Plan | AMPL to AMPL real-time cohort sync | | --- | --- | | Free | Not included | | Plus | Not included | | Growth | Not included | | Enterprise | 50 | AMPL to 3rd Party Real-Time Cohort Syncs and AMPL to AMPL real-time cohort sync are available as an add-on on the Growth and Enterprise plans. _Availability reflects the latest Amplitude plans. If your organization is on an older plan, your access may differ. Check your plan under [Plans & Billing in your organization settings](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._ ## One-time sync Use a one-time sync to send a cohort to your destination once. Use this option if you need to export a cohort to the destination and don't require continuous updates. ## Scheduled sync Use a scheduled sync to send cohort updates to your destination on an hourly or daily basis. Amplitude queues sync jobs throughout the hour or day, depending on your selection. You can't select the time of day that a sync occurs. > **Note:** Scheduled sync timing > > Amplitude schedules a time to sync the cohort as soon as you create a new cohort or update the sync details. > > The first sync occurs right after Amplitude schedules it. The first two syncs may occur more frequently than every 24 hours. > > If you don't update the sync, future sync jobs run around the same time within the time period. ## Real-time sync Use a real-time sync to keep the destination updated with the most recent cohort information. Real-time sync checks for updates and sends them to the destination every minute. Amplitude recommends real-time syncs for cohorts that require minute-by-minute precision and don't change by a large number of users from minute to minute. If you choose real-time syncing and notice in the sync history that most syncs update `0` users, hourly sync may work better for your use case. > **Warning:** Real-time sync limitations > > Real-time sync supports cohorts of 1,000,000 users or fewer, and all cohort types except: > > - Funnel > - Retention > - Stickiness > - Nth time event > - Event within > - Distinct interval > > Real-time sync supports all cohort destinations except: > > - [Facebook Ads](https://amplitude.com/docs/data/destination-catalog/facebook-ads) > - [Google Ads](https://amplitude.com/docs/data/destination-catalog/google-ads-cohort-syncing) > - [Twitter (X) Ads](https://amplitude.com/docs/data/destination-catalog/twitter-ads-cohort) > - [Hubspot](https://amplitude.com/docs/data/destination-catalog/hubspot-cohort-sync) > - [Qualtrics](https://amplitude.com/docs/data/destination-catalog/qualtrics) > - [S3 cohort sync](https://amplitude.com/docs/data/destination-catalog/amazon-s3-cohort) > - [TikTok Ads](https://amplitude.com/docs/data/destination-catalog/tiktok-ads) > - [Enterpret](https://amplitude.com/docs/data/destination-catalog/enterpret) > - [SFMC](https://amplitude.com/docs/data/destination-catalog/salesforce-marketing-cloud-v2) > - [The Trade Desk](https://amplitude.com/docs/data/destination-catalog/thetradedesk) ================================================================================ # DataGrail URL: https://amplitude.com/docs/data/pii/datagrail Updated: 2026-09-01 ================================================================================ # DataGrail > **Note:** > > For feedback on this integration or documentation, contact [support@datagrail.io](mailto:support@datagrail.io). [DataGrail](http://www.datagrail.io) is a privacy management platform for system detection and automated data subject request (DSR) fulfillment. DataGrail supports compliance with privacy laws and regulations such as GDPR, CCPA, and CPRA. The Amplitude integration helps privacy owners identify, retrieve, and delete PII from Amplitude. ## Before you begin - If you don't have admin rights in Amplitude, you can't complete the DataGrail integration. Contact your Amplitude Admin for help. - You need a paid DataGrail plan. ## Copy Amplitude credentials Copy the Amplitude API key and Secret Key for your project. Amplitude doesn't require other setup steps. ## Configure DataGrail For detailed setup information, refer to the help documentation while logged in to DataGrail. 1. Log in to the DataGrail Portal. 2. Select **Integrations** on the navigation bar, then select **Configure New Integration**. 3. Search for Amplitude by name, then select **Configure**. 4. Enter the API Key and Secret Key. 5. Select **Save Connection** to complete the setup. Your Amplitude integration is now active. Contact DataGrail's support team ([support@datagrail.io](mailto:support@datagrail.io)) with questions. ================================================================================ # Osano URL: https://amplitude.com/docs/data/pii/osano Updated: 2026-09-01 ================================================================================ # Osano [Osano](https://www.osano.com/) is a data privacy platform that helps you manage website compliance with laws such as GDPR and CCPA. Osano monitors the vendors that receive your data. Osano connects to Amplitude with a one-click integration. Osano then discovers and automatically classifies the personal data that Amplitude stores. After Osano finishes discovery and classification, you can include Amplitude in subject rights request searches. > **Note:** > > For feedback on this integration or documentation, contact [Osano's support team](https://www.osano.com/company/contact). ## Before you begin - The Osano integration requires an Osano Enterprise plan. ## Copy Amplitude credentials Copy the Amplitude API key and Secret Key for your project. Amplitude doesn't require other setup steps. ## Configure Osano 1. Log in to the Osano Portal. 2. From the **Data Discovery** menu, open the **Data Stores** page. 3. Select **+** to add a new data store. 4. Select **Connect to third-party vendors to enable automated data discovery**. 5. Select **Amplitude** from the dropdown menu. 6. Paste the Amplitude API key into **API Key**. 7. Paste the Amplitude Secret Key into **Secret Key**. 8. Select a **Data Store Owner** from the dropdown menu. 9. Save your changes. When you save, Amplitude and Osano immediately begin syncing to detect PII. Manage PII detection results from Osano. ================================================================================ # Transcend URL: https://amplitude.com/docs/data/pii/transcend Updated: 2026-09-01 ================================================================================ # Transcend [Transcend](https://transcend.io/) is a privacy platform for data transparency, consent, and control. Transcend lets you programmatically access and erase user device activity in Amplitude to comply with data privacy regulations such as GDPR and CCPA. > **Note:** Partner-maintained integration > > For feedback on this integration or documentation, contact [Transcend's support team](https://transcend.io/integration/amplitude/). ## Configure Transcend For setup instructions, refer to the [Transcend documentation](https://transcend.io/integration/amplitude/). ================================================================================ # Missing User IDs after sign-in: engineering solution URL: https://amplitude.com/docs/data/data-assistant-user-solutions/missing-user-ids-engineering Updated: 2026-09-22 ================================================================================ # Missing User IDs after sign-in: engineering solution Set a stable `user_id` as soon as your product reliably identifies a person, then include it on every authenticated event. This is an instrumentation change. Data Assistant and the Amplitude UI can't add missing identifiers to events that already arrived, so the fix lives in your code or event pipeline. Use your Analytics SDK's identity method for client events. If you send events through the HTTP API, include `user_id` in each authenticated event payload. Start from the confirmed findings in the [audit](https://amplitude.com/docs/data/data-assistant-user-solutions/missing-user-ids-audit). > **Warning:** Choose the identifier carefully > > User IDs are case-sensitive and permanent. Don't use an email address, a username, a value that can change, or a shared placeholder such as `None`. Amplitude can't merge two established User IDs later, so a bad choice now is expensive to undo. ## Update the identity flow 1. Choose the immutable account identifier your backend uses for one person. 2. Keep the Amplitude SDK anonymous until your authentication system confirms the person's identity. 3. Call the SDK's User ID method right after authentication and before you track any post-sign-in event. Follow the identity section of your [Analytics SDK documentation](https://amplitude.com/docs/sdks/analytics). 4. For server-side events, send the same canonical value in `user_id` on every authenticated event. Follow the [HTTP V2 API](https://amplitude.com/docs/apis/analytics/http-v2) request schema. 5. Use exactly the same value and casing across web, mobile, and backend sources. 6. Define logout behavior. If another person can use the same device, clear the User ID and generate a new device ID according to your SDK's logout guidance. ## Validate the fix Repeat the [audit](https://amplitude.com/docs/data/data-assistant-user-solutions/missing-user-ids-audit) in a test environment or with a test account. Confirm that anonymous events stay anonymous before authentication, and that every event after authentication carries the canonical `user_id`. For the full identity model, refer to [Track unique users](https://amplitude.com/docs/data/sources/instrument-track-unique-users). ================================================================================ # User IDs set too early: engineering solution URL: https://amplitude.com/docs/data/data-assistant-user-solutions/early-user-ids-engineering Updated: 2026-09-22 ================================================================================ # User IDs set too early: engineering solution Gate User ID assignment on your application's confirmed authentication state. This keeps anonymous visitors and people on shared devices from inheriting the wrong identity. The change lives in the application or event pipeline, not in Data Assistant. Start from the findings in the [audit](https://amplitude.com/docs/data/data-assistant-user-solutions/early-user-ids-audit). ## Correct the authentication boundary 1. Find every place that initializes Amplitude or assigns an analytics User ID. 2. Remove placeholder values such as `anonymous`, `guest`, `None`, or an empty string. Leave the User ID unset for unknown visitors. 3. Wait until your authentication system returns the canonical account identifier. 4. Assign that value through your Analytics SDK's User ID method before you track the first authenticated action. 5. When a person signs out on a shared device, clear the User ID and generate a new device ID according to the SDK's logout instructions. 6. When your app restores a valid signed-in session, assign the known User ID before it tracks authenticated events. > **Note:** Identity updates aren't retroactive > > This change protects new events. It doesn't separate historical activity that your implementation already sent under an incorrect User ID. ## Validate the fix Run the [audit](https://amplitude.com/docs/data/data-assistant-user-solutions/early-user-ids-audit) for a new visitor, a returning signed-in person, and two different accounts on the same device. Confirm that each journey crosses the authentication boundary with the intended identity. Refer to [How Amplitude identifies your users](https://amplitude.com/docs/get-started/identify-users) before you deploy. ================================================================================ # Anonymous activity lost at login: engineering solution URL: https://amplitude.com/docs/data/data-assistant-user-solutions/login-identity-merge-engineering Updated: 2026-09-22 ================================================================================ # Anonymous activity lost at login: engineering solution Preserve the anonymous device ID when you assign the stable User ID at login. Amplitude uses that relationship to join the earlier anonymous activity with the known profile. Data Assistant can't repair a relationship that was never sent, so the fix belongs in the login flow. Start from the findings in the [audit](https://amplitude.com/docs/data/data-assistant-user-solutions/login-identity-merge-audit). ## Update the login flow 1. Keep one initialized Analytics SDK instance across the anonymous and authenticated parts of the session. 2. Don't regenerate or replace the device ID during login. 3. After authentication succeeds, set the canonical User ID through the SDK before you track the next event. 4. If you use the Identify API instead of a client SDK, send an identification object that contains the existing `device_id` and the newly known `user_id`. Follow the [Identify API](https://amplitude.com/docs/apis/analytics/identify) request requirements. 5. Keep sending the same canonical User ID on later authenticated events and on other devices. > **Warning:** Don't change one established User ID into another > > Changing a non-null `user_id` creates another user. This workflow joins an anonymous device to a known User ID. It doesn't merge two established User IDs. ## Validate the fix Repeat the [audit](https://amplitude.com/docs/data/data-assistant-user-solutions/login-identity-merge-audit). Check the raw event immediately before login and the first event after login. They should share the same `device_id`, and the event after login should carry the canonical `user_id`. Refer to [Track unique users](https://amplitude.com/docs/data/sources/instrument-track-unique-users#user-id-follows-anonymous-events) for the identity sequence Amplitude expects. ================================================================================ # One person, many User IDs: engineering solution URL: https://amplitude.com/docs/data/data-assistant-user-solutions/multiple-user-ids-engineering Updated: 2026-09-23 ================================================================================ # One person, many User IDs: engineering solution Standardize every source on one immutable, case-consistent `user_id` so no new duplicate profiles appear. Amplitude's standard identity resolution can't merge two established User IDs, so no in-product action combines their historical activity into one project profile. The fix prevents future splits and the plan below handles the history you already have. Start from the findings in the [audit](https://amplitude.com/docs/data/data-assistant-user-solutions/multiple-user-ids-audit). > **Warning:** Historical User IDs stay separate > > Don't try to fix this by changing one existing non-null User ID into another. Amplitude treats the new value as a different user. Deleting a profile removes data rather than merging it. ## Prevent new duplicate profiles 1. Choose the immutable backend account ID as the canonical User ID. 2. Update every web, mobile, server, and customer data platform mapping to send that exact value and casing. 3. Stop using email addresses, usernames, or platform-specific identifiers as User IDs. 4. Add automated tests that compare the analytics User ID with the authenticated account ID. 5. Repeat the [audit](https://amplitude.com/docs/data/data-assistant-user-solutions/multiple-user-ids-audit) after you deploy. ## Handle existing history For analysis inside one standard project, record the change date and account for the break in long-term user analysis. If you must unify historical reporting, work with your data team in a warehouse, where they can apply an approved identity mapping outside the Amplitude user model. The [User Mapping API](https://amplitude.com/docs/apis/analytics/user-mapping) serves a different case. Customers with the Portfolio add-on can map different project-level User IDs to a global User ID for cross-project analysis. It doesn't rewrite the original user properties or replace correct identity instrumentation. Check [Pricing](https://amplitude.com/pricing) or contact [Amplitude Sales](https://amplitude.com/sales-contact) if cross-project Portfolio analysis fits your need. ================================================================================ # Profiles that don't join across devices: engineering solution URL: https://amplitude.com/docs/data/data-assistant-user-solutions/cross-device-identity-engineering Updated: 2026-09-22 ================================================================================ # Profiles that don't join across devices: engineering solution Send the same immutable `user_id` for a signed-in person from every platform and project in the organization. Amplitude prioritizes the User ID over device IDs when it joins known activity, so this fix belongs in each source's identity implementation. Start from the findings in the [audit](https://amplitude.com/docs/data/data-assistant-user-solutions/cross-device-identity-audit). ## Align identity across sources 1. Define one backend account field as the canonical User ID. 2. Document its exact format and casing for every client and server team. 3. On each platform, set the canonical User ID after authentication and before you track authenticated activity. 4. Remove platform prefixes, email substitutions, and transformations that make the same account produce different values. 5. If several Amplitude projects belong to one organization, use the same User ID variable in every project. 6. Add an integration test that signs the same account into each supported platform and compares the outbound User IDs. > **Note:** The fix affects new identity relationships > > Correct instrumentation joins future activity under the canonical User ID. Amplitude can't merge historical activity from two established User IDs in a standard project. ## Validate the fix Repeat the [audit](https://amplitude.com/docs/data/data-assistant-user-solutions/cross-device-identity-audit) after you deploy. For the full identity model, refer to [Track unique users](https://amplitude.com/docs/data/sources/instrument-track-unique-users). ================================================================================ # Planned events that never arrived: remove the plan entry URL: https://amplitude.com/docs/data/data-assistant-user-solutions/planned-unseen-events-engineering Updated: 2026-09-22 ================================================================================ # Planned events that never arrived: remove the plan entry Remove an approved planned event from the tracking plan in Amplitude Data. Use the Taxonomy API instead when you need an automated workflow. Data Assistant has no direct action for this task. ## Prerequisites Before you remove a planned event, you need: - The exact event name. - Permission to manage the tracking plan. - Written confirmation from the event owner. - A completed [planned unseen events audit](https://amplitude.com/docs/data/data-assistant-user-solutions/planned-unseen-events-audit) that confirms the event has never produced data. Do not use this workflow for an event that has produced data. Deleting a live event has different behavior from removing a planned event. ## Remove the planned event in Amplitude Data 1. Go to the _Events_ section in Amplitude Data. 2. Select the approved planned event. 3. Select **Delete** and complete the verification dialog. 4. Confirm the entry no longer appears in the tracking plan. Deleting a planned event removes its entry from the tracking plan. The deletion doesn't remove historical data. Use this procedure only after the audit confirms that the event has no historical data. For general UI behavior, refer to [Delete events and properties in Amplitude Data](https://amplitude.com/docs/data/remove-invalid-data#delete-events-and-properties-in-amplitude-data). ## Use the Taxonomy API for automation The Taxonomy API is an Enterprise feature. You need a project API key and secret key. Use the base URL for the project's data residency: | Data residency | Base URL | | --- | --- | | Default | `https://amplitude.com` | | EU | `https://analytics.eu.amplitude.com` | 1. Store the project API key and secret key in your approved secret-management workflow. Don't paste credentials into tickets or shared documents. 2. URL-encode the exact event name for the request path. 3. Send a `DELETE` request to the Taxonomy API. This example uses the default-residency host: ```bash curl --request DELETE \ --user "$AMPLITUDE_API_KEY:$AMPLITUDE_SECRET_KEY" \ "https://amplitude.com/api/2/taxonomy/event/URL_ENCODED_EVENT_NAME" ``` 4. Confirm the API returns `200 OK` with `"success": true`. 5. Refresh _Data > Events_ and confirm the planned entry no longer appears in the tracking plan. > **Warning:** Verify the event state > > For a planned event, the endpoint removes the event from the tracking plan. For a live event, the endpoint marks the event as deleted. Refer to [Delete an event type](https://amplitude.com/docs/apis/analytics/taxonomy#delete-an-event-type) for state-specific behavior and error responses. ================================================================================ # Failures you can't see: engineering solution URL: https://amplitude.com/docs/data/data-assistant-user-solutions/error-event-coverage-engineering Updated: 2026-09-22 ================================================================================ # Failures you can't see: engineering solution Track a failure event at the point where your product knows a critical action failed. This is product-specific code or pipeline work. Data Assistant, Autocapture, and chart configuration can't infer a backend failure your product never sends. Start from the approved gap in the [audit](https://amplitude.com/docs/data/data-assistant-user-solutions/error-event-coverage-audit). ## Design the failure signal 1. Start from the approved entry in the audit. 2. Prefer one clearly named event for a meaningful failure outcome. Use event properties when one event needs safe categories such as `flow`, `step`, `error_type`, or `error_code`. 3. Write a description that states exactly when the event fires and which source owns it. 4. Avoid stack traces, free-form messages, access tokens, payment details, email addresses, and other sensitive values. Send an approved code or category instead. 5. Add the event and its properties to the [tracking plan](https://amplitude.com/docs/data/create-tracking-plan) before you change production instrumentation. ## Implement and validate the event 1. Track the event in the code path that handles the confirmed failure, not when the action starts. 2. Include the same stable User ID and contextual properties the surrounding journey uses. 3. Prevent retries from creating duplicate failure events when one failure fires several callbacks. 4. Trigger a safe test failure and confirm the event and properties in [Event Explorer](https://amplitude.com/docs/analytics/charts/event-explorer). 5. Review [Observe](https://amplitude.com/docs/data/validate-events) and confirm the event matches the tracking plan. 6. Add the new failure event to the journey's funnel or monitoring dashboard. If Session Replay captures the affected surface, link the structured event to replay analysis for context. The event stays the reliable count. The replay explains what happened in individual sessions. ================================================================================ # No activation event: engineering solution URL: https://amplitude.com/docs/data/data-assistant-user-solutions/activation-event-engineering Updated: 2026-09-22 ================================================================================ # No activation event: engineering solution Instrument the activation outcome approved by product and data owners when no existing event accurately represents the outcome. Data Assistant can't add the signal. An analytics-only workaround works only when existing events already encode the complete outcome. Start with the activation outcome defined in the [audit](https://amplitude.com/docs/data/data-assistant-user-solutions/activation-event-audit). ## Define the event contract 1. Use the outcome and acceptance criteria from the audit. 2. Add the event to the [tracking plan](https://amplitude.com/docs/data/create-tracking-plan) with a precise trigger, owner, source, and description. 3. Add only properties that support a known analysis question. Mark required properties in the plan. 4. Decide whether the outcome occurs once or can repeat. Track the actual behavior consistently. Don't suppress legitimate repeats to force a once-per-user count. ## Implement and validate the event 1. Track the event after the product confirms the activation outcome. 2. Include the canonical User ID for authenticated people and the approved event properties. 3. Prevent duplicate callbacks or retry loops from sending the event more than once. 4. Trigger the activation journey with a test account. 5. Confirm the event, User ID, properties, and timing in [Event Explorer](https://amplitude.com/docs/analytics/charts/event-explorer). 6. Confirm that [Observe](https://amplitude.com/docs/data/validate-events) reports the event as valid. 7. Rebuild the activation funnel and retention comparison with the new event after enough representative data arrives. ## Use a custom event when existing events qualify If any of several existing events represents the full activation outcome, a [custom event](https://amplitude.com/docs/data/custom-events) can combine the events with an `OR` condition without an application release. A custom event can't create missing raw telemetry or combine an ordered sequence of actions into a new event. ================================================================================ # Missing or mistimed exposure: engineering solution URL: https://amplitude.com/docs/data/data-assistant-user-solutions/experiment-exposure-engineering Updated: 2026-09-22 ================================================================================ # Missing or mistimed exposure: engineering solution Track exposure when a user encounters an experiment variant. Choose the tracking method that matches your Experiment evaluation mode. Data Assistant can't create or retime exposure events. Changing an analysis setting can't recover exposures that your implementation never sent. Start with the findings from the [exposure audit](https://amplitude.com/docs/data/data-assistant-user-solutions/experiment-exposure-audit). ## Choose the exposure method - For a supported client-side Experiment SDK, integrate the Experiment SDK with the matching Analytics SDK. The integration tracks exposure when application code accesses the variant from the variant store. - For remote evaluation, Amplitude automatically tracks assignment events for eligible requests. Track exposure separately when the user encounters the variant. Alternatively, use the assignment event as an exposure heuristic when the event represents the user's experience. - For server-side local evaluation, use the assignment event as an exposure heuristic when the event represents the user's experience. Otherwise, send an explicit exposure when the user encounters the variant. Server-side local evaluation doesn't detect when the client renders the experience. - For custom exposure tracking, send the event only when the user experiences the variant. Don't send exposures for fallback or default values when the user has no assignment. ## Correct common implementation problems 1. Keep the `user_id` and `device_id` values consistent across evaluation, exposure, and analytics events whenever those identifiers are present. 2. Fetch or evaluate the variant again when the signed-in identity changes. 3. Access or log the variant when the application renders or uses it, not during an unused preload. 4. Send the required flag key and the actual variant value. Follow the [exposure event definition](https://amplitude.com/docs/feature-experiment/under-the-hood/event-tracking#exposure-event-definition). 5. Avoid duplicate exposure calls for one unchanged experience. ## Validate the fix Run the [exposure audit](https://amplitude.com/docs/data/data-assistant-user-solutions/experiment-exposure-audit) with test accounts in each variant. Confirm the evaluation, exposure, and analytics event sequence before you rely on experiment metrics. Refer to [Exposure tracking](https://amplitude.com/docs/feature-experiment/track-exposure) for supported SDK and API paths. ================================================================================ # No account-level analysis: engineering solution URL: https://amplitude.com/docs/data/data-assistant-user-solutions/group-types-engineering Updated: 2026-09-22 ================================================================================ # No account-level analysis: engineering solution Instrument the approved group type and a stable group value after your organization enables the Accounts add-on. Data Assistant can't add group context to events, and group changes affect new data rather than historical events. Start from the group definition in the [decision guide](https://amplitude.com/docs/data/data-assistant-user-solutions/group-types-audit), and confirm your organization enabled the Accounts add-on before you begin. ## Create the group schema 1. In Amplitude Data, go to _Data > Groups_ and select **Create group**. 2. Name the group type for the business object, such as `account` or `workspace`, rather than a specific account value. 3. Add a description, owner, source, and planned group properties. 4. Use a stable internal identifier as the group value. Send a separate human-readable group property, such as account name, for display and segmentation. ## Choose the membership model - Use an event-level group when membership applies only to specific events, or can change between events. Include the `groups` field on every relevant event through an SDK, the HTTP V2 API, or your customer data platform. - Use a user-level group when all future events from a person should belong to the group. Assign it through an SDK Identify call or the Identify API. Amplitude doesn't let you remove a user-level group association. You can only overwrite it. - Use the [Group Identify API](https://amplitude.com/docs/apis/analytics/group-identify) to set and update group properties. Group-property updates don't apply retroactively. ## Validate the group 1. Send test activity for two people in the same group. 2. Open _Users > Group Profiles_ and find the group. 3. Confirm the profile holds both people's relevant events and the expected group properties. 4. Build an Event Segmentation or Funnel Analysis chart and change the counting unit from users to the new group type. Refer to [Plan your Accounts instrumentation](https://amplitude.com/docs/analytics/plan-your-accounts-instrumentation) for the full event-level and user-level design guidance. ================================================================================ # Missing shared context: engineering solution URL: https://amplitude.com/docs/data/data-assistant-user-solutions/shared-properties-engineering Updated: 2026-09-22 ================================================================================ # Missing shared context: engineering solution Send each approved shared property from every source and event that needs it. Data Assistant and tracking-plan configuration can't populate a value the application, server, or pipeline doesn't send. Start from the property contract and affected-source list in the [audit](https://amplitude.com/docs/data/data-assistant-user-solutions/shared-properties-audit). Use a user property when the value describes the person and should persist across future activity. Use an event property when the value describes one action at the time it happens. ## Update the implementation 1. Start from the property contract and affected-source list in the audit. 2. Map the property to a trusted application or backend value. 3. For a user property, set or update it before the next event that needs the new value. Don't resend an unchanged custom user property on every event unless your integration requires it. 4. For an event property, add it to every relevant event payload at the point where the source knows the value. 5. Keep names, types, and allowed values consistent across web, mobile, backend, and customer data platform mappings. 6. Avoid deriving sensitive values or sending data that violates your organization's privacy policy. ## Validate the fix 1. Trigger representative events from every changed source. 2. Inspect the raw payloads in [Event Explorer](https://amplitude.com/docs/analytics/charts/event-explorer) or the user's event timeline. 3. Confirm that [Observe](https://amplitude.com/docs/data/validate-events) reports the required property with full expected coverage for the test window. 4. Build a chart grouped by the property and check for unexpected `(none)` values. If existing raw properties already contain the needed value, a [derived property](https://amplitude.com/docs/data/derived-properties) may support analysis without new instrumentation. Derived properties calculate at query time and don't change the source payload or fill the original property's coverage gap. ================================================================================ # Event vs user property confusion: engineering solution URL: https://amplitude.com/docs/data/data-assistant-user-solutions/property-classification-engineering Updated: 2026-09-22 ================================================================================ # Event vs user property confusion: engineering solution Send future values as the property type that matches the approved data model. Data Assistant can't reclassify the raw field, and Amplitude has no direct transformation that converts a regular event property into a regular user property or the reverse. Start from the intended type in the [audit](https://amplitude.com/docs/data/data-assistant-user-solutions/property-classification-audit). ## Plan the migration 1. Use the intended type from the audit. 2. Choose a clear target name. Reuse the old name only when analysts can unambiguously tell the property types apart in charts. 3. Add the target property to the tracking plan with its type, description, owner, and source. 4. List saved charts, cohorts, experiments, and destinations that depend on the old property. 5. Choose a migration date and tell analysts that old and new data use different fields. ## Correct the source - To move event context to a user property, update the user property before you send the next event that should use it. The new value applies to future events and doesn't rewrite earlier ones. - To move a person-level value to an event property, include the value on every event occurrence where that historical context matters. - If both meanings are valid, keep two clearly named properties and document when to use each. ## Validate and retire the old field 1. Trigger test events and inspect both event and user properties in [Event Explorer](https://amplitude.com/docs/analytics/charts/event-explorer). 2. Confirm that [Observe](https://amplitude.com/docs/data/validate-events) matches the new tracking-plan definition. 3. Update dependent charts and cohorts to use the target property for data after the migration date. 4. Hide or delete the obsolete property only after owners confirm new queries no longer need it. Refer to [Remove invalid data](https://amplitude.com/docs/data/remove-invalid-data) for the effect of each option. If you need one continuous historical field, a derived or computed property may bridge analysis when the existing data holds enough information. It doesn't rewrite the raw event history. ================================================================================ # Missing insert_id or session_id: engineering solution URL: https://amplitude.com/docs/data/data-assistant-user-solutions/event-identifiers-engineering Updated: 2026-09-22 ================================================================================ # Missing insert_id or session_id: engineering solution Add a unique `insert_id` to retryable server events and a valid `session_id` to events that should join session analysis. Data Assistant can't populate either field after ingestion, so configure the fields in the SDK, server, or customer data platform mapping. Use the [audit](https://amplitude.com/docs/data/data-assistant-user-solutions/event-identifiers-audit) to identify affected sources. ## Add `insert_id` to server events 1. Generate one stable, unique value for each logical event before the first delivery attempt. A UUID works if your system persists the UUID and reuses it for retries. 2. Send the identifier in the top-level `insert_id` field. 3. Reuse the `insert_id` when you retry the same event. Generate a new `insert_id` for a new event. 4. If an event includes `device_id`, use the same `device_id` across retries. Amplitude ignores subsequent events with the same `insert_id` on the same `device_id` within the seven-day deduplication window. 5. Store each `insert_id` long enough to support your retry policy. ## Preserve `session_id` for session analysis - For Amplitude client SDKs, keep automatic session tracking enabled unless your product uses a custom session policy. - For HTTP API events that belong to a session, send the session's start time in milliseconds since Unix epoch as the top-level `session_id`. - Use the same `session_id` for events from the same user in the same session. - Use `session_id: -1` only for an event that should stay outside session metrics. > **Note:** A custom session definition is an analysis alternative > > An Admin or Manager can define sessions from another property, from starting and ending events, or from a timeout. A custom session definition can support session analysis without changing every payload. The definition doesn't add missing raw `session_id` values and affects session-based charts across the project. ## Validate the fix Repeat the [audit](https://amplitude.com/docs/data/data-assistant-user-solutions/event-identifiers-audit) after you deploy the `insert_id` or `session_id` changes. For deduplication behavior, refer to [HTTP V2 event deduplication](https://amplitude.com/docs/apis/analytics/http-v2#event-deduplication). For session behavior, refer to [Track sessions](https://amplitude.com/docs/data/sources/instrument-track-sessions). ================================================================================ # Missing or unexpected data URL: https://amplitude.com/docs/data/troubleshooting/missing-data Updated: 2026-08-28 ================================================================================ # Missing or unexpected data This page diagnoses three common data problems: a chart that shows fewer events than you expect, user counts that look inflated or too small, and Amplitude numbers that don't match another platform. Each section below covers a common cause and how to fix it. ## Why an event or property is missing Even when you successfully send data to Amplitude, the event or property may not appear in analysis. The following sections cover common causes. ## Your project reached the instrumentation limit If your project hits its [instrumentation limit](https://amplitude.com/docs/faq/limits-and-quotas), Amplitude can't query data for any event types and event or user properties that exceed the limit. You can only access this data by exporting raw data through a CSV file or Amplitude's [Export API](https://amplitude.com/docs/apis/analytics/export). To get back under the limit, [delete unneeded event types in Amplitude Data](https://amplitude.com/docs/data/remove-invalid-data). After you're under the limit, the new event types, event properties, and user properties take approximately 24 hours to appear in Amplitude. ## Someone hid, blocked, or deleted the data Someone may have hidden, blocked, or deleted the expected data. Review the [differences between those actions](https://amplitude.com/docs/data/remove-invalid-data) from your `main` branch so Amplitude ingests the data properly. > **Note:** > > Hidden or blocked events and properties still count toward your project's [instrumentation limit](https://amplitude.com/docs/faq/limits-and-quotas). Deleted events and properties don't. The data may also have a name you don't expect, or have a [display name](https://amplitude.com/docs/data/display-names-in-amplitude-data) you're not familiar with. To adjust the name, refer to the article on [making retroactive changes to your data](https://amplitude.com/docs/data/transformations). ### Hidden events An event may appear in an event stream but not in a chart. The cause is usually a filter (such as a drop filter) or someone hiding the event from view in Amplitude Data. > **Note:** > > You can also [hide](https://amplitude.com/docs/data/troubleshooting/instrumentation-issues#hide-block-or-delete-an-event-or-property) events and properties from drop-downs, Pathfinder results, and Personas charts. ## Schema doesn't include unplanned data The missing data might count as unplanned. Unplanned data conflicts with your current schema settings, so Amplitude doesn't know how to handle it. Verify that your project's tracking plan accepts [unplanned events or properties](https://amplitude.com/docs/data/configure-schema). If it doesn't, Amplitude doesn't store the event or its properties. ## Data ingestion or access delays If event or property data appears for some users but not others, data ingestion can lag. For example, when a [Mobile SDK](https://amplitude.com/docs/sdks/sdk-maintenance-and-support) sends data to Amplitude, events may not appear immediately. The user may not have an internet connection, or the SDK may not have reached its event upload threshold. > **Note:** > > By default, Amplitude's Mobile SDKs have an event upload threshold of 30 seconds or 30 events. The SDK doesn't send event data until it reaches the threshold. New or modified user properties sent through the [Identity API](https://amplitude.com/docs/data/user-properties-and-events) can also experience ingestion delays. ## Unexpected values in user counts When you group events by an event or user property, some results may appear in a group called `(none)`. In Amplitude, `(none)` represents a null value. The following sections explain why users have null or unexpected property values. ### Why your event property appears in the `(none)` bucket Amplitude is an event-based analytics platform, and all charts and cohorts query at the event level. Charts return the event property value at the time of an event. Because an event property is a component of an event, event property values can be unique at the event level. If you send an event with a null value at the time of the event, grouping by that event property places some events or users in the `(none)` bucket. For example, User A triggered `Send Message` once on January 1st and once on February 1st. You instrumented the `Audience` event property on January 15th, so the property wasn't available when User A triggered `Send Message` on January 1st. The `Audience` property accepts only `Default` and `Mentioned_Contacts`. When User A sent `Send Message` on February 1st, the event had `Audience = Default`. Amplitude counts User A once in the `Default` bucket and once in the `(none)` bucket. User A had `Audience = Default` at the time of the February 1st event, and `Audience = (none)` at the time of the January 1st event. Amplitude sorts events and users according to the property value sent at the time of the event. ### Why your user property doesn't show the expected value Like event properties, charts return the user property value at the time of an event. Amplitude stores user properties in a separate table, then applies them to events. When a user's property values update, the user property values attached to historical events don't change. ### Why your custom property shows a null value Custom user properties attached to events reflect the user property values present at the time of the event. For example, you instrumented a user property called `Account_Type` on January 15th. User A is a registered user with an account type of `Shopper`. User A triggered `Add Item to Cart` once on January 1st and once on February 1st. Because you didn't instrument `Account_Type` until January 15th, all events triggered before January 15th have a null value for `Account_Type`. Amplitude counts User A once in the `(none)` bucket and once in the `Shopper` bucket. When measuring Uniques, Amplitude deduplicates users within each unique bucket. If User A triggered `Add Item to Cart` with their `Shopper` account type on both February 1st and February 2nd, Amplitude still counts User A only once in the `Shopper` bucket. The same logic applies for non-null user property values. Amplitude sorts events and users by the property value applied at the time of the event. Amplitude uses this logic because user attributes can change over time. `City`, for example, can change by the hour as users travel and send events from different cities. Knowing where the user was at the time of the event can be more valuable than knowing where the user is now. ### Location property shows a `(none)` value Amplitude determines location user properties (such as `[Amplitude] City`, `[Amplitude] DMA`, `[Amplitude] Region`, and `[Amplitude] Country`) by GeoIP. Amplitude uses the [MaxMind](https://www.maxmind.com/en/home) database to look up location information from the user's IP address. For client-side events, location properties can have `(none)` values when MaxMind returns null for that IP address. The accuracy and availability of city and region information varies by country. For details, refer to [MaxMind's accuracy comparison](https://www.maxmind.com/en/geoip2-city-accuracy-comparison?country=&resolution=50). For server-side events, Amplitude determines location property values either by GeoIP (which falls back on `location_lat` and `location_long` if unavailable) or by explicit definition in your API call. Amplitude's [HTTP API](https://amplitude.com/docs/apis/analytics/http-v2) lets you send custom `City`, `DMA`, `Region`, and `Country` values with your events. Amplitude doesn't modify these values to reflect GeoIP. Update all four fields together: setting any one of these fields automatically resets all others. ### Why your device property shows a `(none)` value Amplitude determines `[Amplitude] Device family` and `[Amplitude] Device type` by reading `device_brand`, `device_manufacturer`, and `device_model` strings from the user's device, then mapping these strings to Amplitude's repository of device types. When a new phone model launches, Amplitude may not have mapped some device types yet. In these cases, `[Amplitude] Device type` is `(none)`. Server-side events can also have null device information when you don't update these fields together: `platform`, `os_name`, `os_version`, `device_brand`, `device_manufacturer`, `device_model`, `carrier`, and `user_agent`. Setting any of these fields resets all other property values to null unless you set them explicitly for the same event. ## User counts from past events The user count for an earlier date can fluctuate over time. When you view data on different days, the number of users for an earlier date may increase or decrease. The user count can increase when Amplitude later ingests events that occurred in the past. Common reasons: - Amplitude's mobile SDKs batch events with a threshold of every 30 seconds, or every 30 events. When users don't meet the threshold, the SDK may not send their events until they return to your product and trigger more events. - To resolve this, adjust the event upload frequency. For [Android Kotlin SDK](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk#configure-the-sdk), configure `flushIntervalMillis` or `flushQueueSize`. For [iOS SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk#configure-the-sdk), configure `eventUploadPeriodSeconds` or `eventUploadThreshold`. For other SDKs, refer to the [SDK documentation](https://amplitude.com/docs/sdks/analytics). - Amplitude's Batch API and server-side integrations have inherent delays. - To resolve this, schedule batches more frequently. - If the user's cellular or Wi-Fi connection wasn't strong enough when they triggered events, the SDK holds those events until the connection is stronger. - There's no remedy for this issue. The user count can decrease when Amplitude merges user records. Amplitude uses a system of user IDs, device IDs, and Amplitude IDs to [track unique users](https://amplitude.com/docs/data/sources/instrument-track-unique-users). If some users don't have user IDs, or if you have many anonymous events, Amplitude first assigns these anonymous events to an anonymous profile, then later merges them into a known profile. Your data stabilizes over time as anonymous users return and merge into existing profiles. The time this takes depends on user behavior (how often they return to your product) and your settings (how often you batch events). Users who interact with your product every day have shorter merge delays. Users who return less frequently have longer delays. ## Data discrepancies with other platforms Amplitude's numbers may differ from what other vendors report. The cause can vary. Before you compare numbers, review how Amplitude tracks users and sessions. Refer to [tracking unique users](https://amplitude.com/docs/data/sources/instrument-track-unique-users) and [the definition of a session in Amplitude](https://amplitude.com/docs/data/sources/instrument-track-sessions). ## Data discrepancy checklist Use the following questions as a troubleshooting checklist for data discrepancies. If you can answer "yes" to a question, that factor is probably not the cause. ### Time zones align between Amplitude and the other platform If not, align the time zones before comparing numbers. Amplitude timestamps the data it ingests in UTC, but you can customize the time zone [within the Amplitude UI](https://amplitude.com/docs/admin/account-management/manage-orgs-projects#view-and-edit-your-project-information). ### Events tracked in Amplitude match what you track in the other platform If not, a discrepancy in users and sessions numbers becomes more likely, because both depend on the events tracked. ### Amplitude and the other platform block the same web bots and scrapers If not, a discrepancy in users and sessions numbers becomes more likely. ### Both platforms define the metric of interest the same way If not, a discrepancy is more likely. ### The other platform merges users the way Amplitude does If not, you may see a discrepancy in users and sessions numbers, depending on the identifiers the other platform uses to merge users. ### The session timeout window matches between Amplitude and the other platform If not, you're more likely to see a discrepancy in sessions numbers. > **Note:** > > For Amplitude SDKs, the default session timeout windows are 30 minutes for web and 5 minutes for mobile. These thresholds are customizable, so confirm with your developer whether they've been changed. ## Sessions in Google Analytics Google Analytics and Amplitude track sessions similarly, but certain common events can cause a discrepancy in session numbers. | **Scenario** | **Amplitude** | **Google Analytics** | **Source** | | --- | --- | --- | --- | | Time hits midnight | Session continues | The current session ends at 11:59 PM and the new session starts at 12:00 AM. | [Refer to "Time Based Expiration"](https://support.google.com/analytics/answer/2731565#time-based-expiration) | | Campaign source changes | Session continues | New session begins even if it is within the 30-minute threshold. | [Refer to "Campaign Based Expiration"](https://support.google.com/analytics/answer/2731565#campaign-based-expiration) | | Session Event Limit | No limit | After the first 10 events, Google Analytics limits tracking to 1 event per second. | [Refer to "Events Per Session Limit"](https://support.google.com/analytics/answer/1033068) | ================================================================================ # Instrumentation and governance issues URL: https://amplitude.com/docs/data/troubleshooting/instrumentation-issues Updated: 2026-09-09 ================================================================================ # Instrumentation and governance issues Answers to common instrumentation and governance questions: how Amplitude treats hidden, blocked, and deleted events, how to filter internal and bot traffic, how to modify historical data, and how the date picker handles offsets and exclusions. ## Instrumentation basics ### Can you delete or alter values after ingestion? After Amplitude ingests data, you can't alter it. Amplitude's architecture uses pre-aggregated sets by the hour, day, week, and month, for both users and events. This approach supports large-scale queries, but requires immutable data. You can delete data at the individual user level in compliance with GDPR and other privacy laws through the [User Privacy API](https://amplitude.com/docs/apis/analytics/user-privacy). ### How does Amplitude set Device ID? Amplitude sets Device IDs differently for client-side events (using Amplitude's SDKs) versus server-side events (HTTP API). - SDKs - For Android, the Device ID defaults to a randomly generated UUID, unless you opt to use Google's Advertising ID as the Device ID. - For iOS SDK, Device IDs default to the Identifier for Vendor (IDFV) if available; otherwise the SDK generates them randomly. You can choose instead to use the Advertising Identifier (IDFA), if available. - Server-side (HTTP API) - For server-side events, you must manually send Device ID in the event. If no Device ID is available, Amplitude sets the Device ID to a randomly-generated hashed version of the `user_id`. For more details, refer to the [HTTP V2 API](https://amplitude.com/docs/apis/analytics/http-v2). - If you don't maintain the same Device ID setup for server-side and client-side events, the same user has different Device IDs even when the device model, language, and carrier are the same. ### Can two different events have the same name? No. Each event name must be unique across an entire project. Amplitude treats two events with the same name as the same event. If you notice two events in a project with the same name, the display name for one of them may have been set to the same name as another event. You can confirm by expanding the event in Amplitude Data to see more details. ### Can you send array values into Amplitude? Yes. However, Amplitude doesn't support exact matching on array properties. You can use the `contains` operator to filter for values within an array. - SDK - [User Property Array](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#arrays-in-user-properties) - [Event Property Array](https://amplitude.com/docs/sdks/analytics/browser/javascript-sdk#arrays-in-event-properties) - [HTTP API Array](https://amplitude.com/docs/apis/analytics/http-v2) ### Why does device information (like Device Type or Device Family) return 'null' in my project? Amplitude returns a null value when it can't parse device information from the device or browser, or when the device isn't mapped in Amplitude's system. To map new device values, contact Amplitude's support team with the following information: - Manufacturer (for example, samsung). - Model (for example, sm-g930u). - Device Family (for example, Samsung Galaxy Phone). - Device Type (for example, Samsung Galaxy S7). ### Why do my sessions generate new Session ID values? Events ingested through Amplitude's SDK maintain the same session if the events come from the same device. Session ID changes every time the Device ID changes. The default session timeout for JavaScript SDK is 30 minutes. For iOS/Android, it's five minutes. ### How do you send recurring revenue subscription events? After the first subscription-related revenue event, Apple or Google must validate whether the subscription is active. If the subscription is active, Amplitude receives the subscription revenue event at the time interval of that subscription. ### How do I filter out bot traffic users? Amplitude SDKs use the User Agent to populate some user properties (such as device type), but don't collect or store the User Agent itself. Some customers implement logic to store User Agent as a custom user property and remove bot users that way. Alternatively, if you can determine the IP address of a suspected bot user, you can use Data Filters to block events from that IP address. To learn more, refer to Amplitude's help center article on [blocking bot web traffic](https://amplitude.com/docs/data/block-bot-traffic). ## Block and filter internal users To keep data clean, Amplitude recommends setting up a development project alongside your production project, and sending test data to the development project only. Testing your production environment can still send internal data into your production project. Because internal user events can falsely inflate your product's metrics, you must block or filter out these events for accurate reporting. ### How do I block specific users? You can block all internal event data originating from your organization's IP address from ingestion into Amplitude Analytics. Use your project's Data Filters page to set up filters. To set up a filter to block events from a specified IP address, follow these steps: 1. From Data, navigate to Filters and click **+Create Block Filter**. 2. In the fly-out panel that appears, choose which environment to apply the filter to. 3. Select **Events** from the _Block_ drop-down menu. 4. Choose **IP Address** and **equal to** from the two other drop-down menus. Then enter the IP address to block. 5. Click **Block Data**. 6. Repeat steps 4 through 6 for each IP address to block. > **Note:** > > You must be a manager or admin of your organization to add a data filter. After you set up this filter, Amplitude drops all events sent from your list of IP addresses on ingestion. This filter doesn't work if you've modified Amplitude's SDK configurations to prevent the collection of IP addresses. The filter only drops events whose collected IP address matches the IPs you've blocked. ### How do I filter out specific users? You can always segment out internal user events using the Segmentation Module of any Amplitude chart. Segment out users by user ID, device ID, Amplitude ID, IP address, or an identifiable user property (for example, username or email). ### How do I save user segments? You can save user segments and pin them to your charts so you don't have to recreate filters every time. When you set a saved segment as your default, Amplitude applies that segment to all new charts you create through the **Create Chart** or **New** button. The applied filter then appears on your chart. ### How do I maintain user lists? Your list of internal users can change over time, and maintaining this list takes effort when your users don't share a common attribute. In these cases, use Amplitude's [behavioral cohorts](https://amplitude.com/docs/analytics/behavioral-cohorts) feature and import a cohort of internal users to block on Amplitude. You can apply this cohort to charts the same way you apply user properties. After you create a user segment that excludes your internal cohort, save and pin the segment for easy access. You can also update behavioral cohorts programmatically to maintain your cohort of internal users. Review the [Behavioral Cohorts API](https://amplitude.com/docs/apis/analytics/behavioral-cohorts) for more details. ## Related resources - [Block bot web traffic](https://amplitude.com/docs/data/block-bot-traffic): Prevent bot traffic from affecting your metrics. - [Winsorization in Experiment](https://amplitude.com/docs/feature-experiment/advanced-techniques/winsorization-in-experiment): Find and resolve outliers that may skew your experiment results. ## Hide, block, or delete an event or property The differences between hiding, blocking, and deleting an event or property aren't immediately clear. Hidden and blocked events and properties still count towards your project's instrumentation [limit](https://amplitude.com/docs/faq/limits-and-quotas); deleted events and properties don't. > **Note:** > > These options only appear in the menu at the top of [Amplitude Data](https://amplitude.com/docs/data) after you select an event or property. ### What is a hidden event or property? Hide an event or property when you don't want users to query on it in Amplitude charts, but still want to collect data for it. You can hide an event or property from drop-downs, Pathfinder results, and Personas charts: - Hiding from drop-downs means you can't select that event or property from drop-down lists in any Amplitude chart. - When you hide the event or property from Pathfinder or Personas results, those charts' calculations exclude that event. Amplitude still ingests the data, and the event or property becomes queryable again after you unhide it. ### What does blocking an event or property do? Block an event or property when you want to continue querying historical data, but want to stop collecting new data. Blocking helps when a particular event is causing you to hit your monthly event volume limit. When you block an event or property, Amplitude stops ingesting and processing it. Blocked events and properties that Amplitude ingested before the block remain selectable in drop-downs and usable in charts. Data sent after you create a block doesn't appear in user streams or chart results. Blocking doesn't stop you from sending that data to Amplitude, so you still receive a success response. Amplitude drops the data before the processing stage, and you can't recover it. ### What happens to deleted events and properties? Delete an event or property that you no longer need to keep your data structure organized. Too many unnecessary events and properties can lead to hitting your project's instrumentation limit. As with blocking, Amplitude doesn't ingest deleted events and properties, and you can't recover data sent after deletion. Unlike blocked items, deleted events and properties aren't available in drop-downs. Charts that include a deleted event or property remain available, but you can't include the deleted item in new charts. If you removed a deleted event from a chart, you can't add it back unless you undelete it. Deleted events still appear in chart results, so to remove or hide chart data for a deleted event, [create a drop filter](https://amplitude.com/docs/data/remove-invalid-data) before deleting the event. ### What are the differences between hiding, blocking, and deleting? | | Blocked from ingestion | Available in data exports | Available in chart dropdowns | Count towards monthly event volume limit | Count towards 2000 event type limit | In Govern | | --- | --- | --- | --- | --- | --- | --- | | **Blocked** | Yes | No | Yes | No | Yes | All, Blocked | | **Deleted** | Yes | No | No | No | No | Deleted | | **Hidden** | No | Yes | No | Yes | Yes | All, Live, Hidden | ## Modify or delete historical data The Amplitude architecture uses pre-aggregated sets by the hour, day, week, and month for users and events. This approach scales well, but the tradeoff is that data is immutable. ### How do I modify events that Amplitude has already ingested? If your account is on the Growth or Enterprise plan, refer to [Self-service data deletion in Amplitude](https://amplitude.com/docs/admin/account-management/self-service-data-deletion-in-amplitude). For other account types, direct modification isn't possible. As a workaround: 1. Export all project data using the [Export API](https://amplitude.com/docs/apis/analytics/export). 2. Clean the data (for example, make the required changes). 3. Upload the cleaned data into a new project using the [Batch API](https://amplitude.com/docs/apis/analytics/batch-event-upload). ### I updated user properties using the Identify API. Why are there still 'none' values in my charts? The Identify API only updates user property values for future events. You can't change data that Amplitude has already ingested. Send another event for Amplitude to apply the updated property value. For more details on how Amplitude updates user properties, refer to [user properties and events](https://amplitude.com/docs/data/user-properties-and-events). ### I accidentally sent an event for a user. How do I delete this specific event for this specific user? You can't. Ingested data is immutable. For similar results, try this process: 1. [Delete or block](https://amplitude.com/docs/data/remove-invalid-data) the event: - This prevents the event from entering Amplitude for all users. - The event still appears in the user's event stream, but isn't available for querying. 2. If deleting or blocking doesn't work, try the workaround described in the previous FAQ. ### How do I backfill historical data into Amplitude? Refer to the [Data Backfill Guide](https://amplitude.com/docs/data/data-backfill). ## Date picker behavior The datepicker selects the timeframe of the analysis you're conducting. You can choose to analyze data collected between two dates, since a specific date, or in the last x days, weeks, or months. The datepicker has nuances in how it handles time. ## Offset When you use Last, your queries return data from the specified timeframe, plus the latest still-incomplete interval. For example, when you set the datepicker to the last 30 days, Amplitude retrieves data from the last 30 full days, plus the hours elapsed today. To exclude data from the incomplete day, or when you use a delayed batch ingestion system, use an offset. Click +Offset in the datepicker, then enter the number of days to offset by. To remove the offset, click 'X' near the Offset by text. ## Exclude When you use Since or the Last x days, weeks, or months options, you can also exclude the current day, week, or month. This helps when the data for the selected timeframe isn't fully available. To exclude the incomplete time interval from your chart, click +Exclude in the datepicker and select the Incomplete Interval option. The current date no longer appears framed in a dotted line, and Amplitude excludes it from your analysis. Deselect Incomplete Interval to revert this setting. Use the same process to exclude or include the current week, current month, or current quarter. > **Note:** > > Amplitude doesn't support using offset and exclude at the same time. ### Exclude specific days You can exclude specific days of the week from your analysis. This option suits organizations that operate on custom schedules. For example, retailers can exclude Sundays when stores aren't open, or SaaS companies can omit weekends to focus on workweek behavior. Excluding specific days affects both chart visuals and metric calculations like averages and rolling windows. Exclude specific days supports only the following chart types: - Segmentation. - Funnels. - Data Tables. - Retention. - Sessions. Exclude specific days supports only the following time ranges: - Last. - Since. > **Note:** > > Exclude specific days doesn't work with Period over Period analysis, and it doesn't work with `realtime` intervals. #### How Amplitude handles excluded days When you exclude days, Amplitude: - Removes the days from the calculations and from the chart visualization. - For averages, calculates on the valid days in the window. For example, if you're looking at the range Sunday - Saturday (7 days) with Wednesday removed: - For non-average time series analysis, the data shows as normal with Wednesday removed. - For aggregate data analysis, the data doesn't count the Wednesday in the aggregation. - For averaging analysis (such as the rolling window), Amplitude doesn't count the dropped days in the numerator or the denominator. If you have a 7-day rolling window, Amplitude treats the data point as a 0 and divides the average based on the valid days in the window (6 days in this example). - For non-daily or non-hourly intervals analysis, Amplitude doesn't remove data from the chart or the table. However, the data still has the underlying days removed. This method avoids artificially low averages and maintains consistent windowing on charts. ## Time input When you use Since or Between, you can narrow the range further by enabling time input. Time input lets you enter a start time or an end time to add granularity to your analysis. > **Note:** > > The datepicker's time input feature is only available for Event Segmentation and Funnel Analysis charts. To enable time granularity, click +Time in the datepicker. After you enable time input, enter the start or end times in hours, minutes, and seconds to accompany your selected date range. To turn off time input, click the 'X' near the entered time. ## Presets The datepicker also supports presets to streamline repetitive analysis and ensure consistency across teams. ### Using presets Presets give you quick access to predefined time ranges, including: - Last 7 days. - Last month. - Year to date. - Custom fiscal periods. When you select a preset, the datepicker automatically fills in the associated time range. ### Custom presets You can create custom presets for recurring analysis windows like product launches, campaigns, or testing periods. Presets can include: - Specific start/end dates. - Relative timeframes (for example, "Last 60 days"). - Optional exclusions (like incomplete data or specific weekdays). Amplitude defines presets at the project level, and they're available across the project. Admins and managers can create, edit, and manage these presets in Project Settings. ### Default presets Users can also define their own default preset for a given project. This preset automatically applies when creating new charts. ## New orgs can't open the menu ### Why can't new users navigate the left-hand menu? When you create a new org on Amplitude, all team members start on the Amplitude _Settings_ page. They don't have an option to open the left-hand menu. New users can appear "stuck" on the _Settings_ page, unable to navigate to any other page on Amplitude. This happens because Amplitude can't populate any charts until it has data to work with. To open the left-hand menu, first set up your data sources and send data to Amplitude. After the charts have data to query on, your left menu expands and you can navigate through the Amplitude UI. ## Firefox ingestion failure ### Why does Firefox block the Amplitude SDK? In Firefox, the tracking protection feature is automatically enabled in standard mode. Amplitude can't record events when you switch this feature to "strict," or when you use a private browser window. Tracking protection blocks cross-site trackers to protect user privacy when browsing across the web. To read more about what tracking protection is and how it affects tracking, refer to [Mozilla's documentation](https://support.mozilla.org/en-US/kb/enhanced-tracking-protection-firefox-desktop#w_what-enhanced-tracking-protection-blocks). Because tracking protection prevents cross-site tracking, it blocks the Amplitude SDK. Firefox blocks the network requests, which causes events to fail ingestion. The following error appears when tracking protection is enabled in the Firefox browser: Failed POST request. ### How do I fix the ingestion issue? According to the Amplitude engineering team, the best solution is to build a proxy server and point the JS SDK at it. Refer to the [documentation on how to create a proxy](https://amplitude.com/docs/analytics/domain-proxy) to learn more. ================================================================================ # Integrations and source troubleshooting URL: https://amplitude.com/docs/data/troubleshooting/integrations-and-sources Updated: 2026-10-13 ================================================================================ # Integrations and source troubleshooting This page covers troubleshooting for Amplitude data sources and integrations: missing events and properties from Segment, incorrectly tracked sessions, iOS 14 IDFA changes, missing mobile attribution events, and how to instrument Amplitude on third-party site builders like Wix and Squarespace. ## Segment-Amplitude integration ## Missing events ### Why don't I see any data in Amplitude? If the event isn't in Segment, then it isn't in Amplitude. Confirm that your requests from Segment received a successful response before considering an event missing. After you confirm that the event is in Segment and got a successful response, confirm these three things: 1. Is Amplitude enabled as a destination? 2. Is the correct API Key entered? Verify the Amplitude API Key value in project settings in your Amplitude UI matches the one in Segment. 3. Is the syntax correct? Instrumentation errors aren't always obvious. Check the code for syntax errors (the browser Console tab can help). After you confirm these requirements, send data to Amplitude by calling `track`. Data appears after you track your first event. ### Are you over the event-type instrumentation limit? If you went [over the limit](https://amplitude.com/docs/faq/limits-and-quotas), Amplitude doesn't ingest any data sent after that. To ingest more event types, delete events to get back under the limit. ### Is the event deleted or blocked from Amplitude? Check your deleted and blocked events. Deleting event types also blocks all future instances of events with the same name. If you send data to a deleted or blocked event name in Amplitude, the data doesn't come through. ### Are there any errors in Segment's debugger? Check your Debugger tab for errors. If the missing event doesn't appear in the Debugger, send a test event of that event type. If the event doesn't reach Segment, it doesn't appear in Amplitude. ### Does the event exist in Segment? For track calls, you can choose to send only certain events to certain integrations. Verify that the event is sending and that Amplitude is enabled. You can also enable or disable specific integrations directly in the instrumentation code. Check that Amplitude isn't disabled in the code. For page and screen calls, you can't see all the individual page names, but the activity shows whether Segment is receiving page calls. You can also check the raw JSON of the requests to verify whether the Amplitude integration is turned off: ```json "integrations": { "Amplitude": false } ``` ## Missing properties ### What is the difference between an event property and a user property? The article on [user properties and events](https://amplitude.com/docs/data/user-properties-and-events) explains the difference between the two types of properties. ### Why don't I see any user properties or only \[Amplitude\] user properties? To send user properties through [Segment](https://segment.com/), call `identify` and include your user properties in the `traits` field. Refer to the [Segment documentation](https://segment.com/docs/spec/identify/) for more on the `identify` call. ### Are you over the event property type instrumentation limit? If you went [over the limit](https://amplitude.com/docs/faq/limits-and-quotas), properties may be missing in Amplitude. Amplitude doesn't ingest any data sent after you exceed the limit. Delete properties to get back under the limit and ingest new properties. ### Is the property deleted or blocked from Amplitude? Check your deleted and blocked properties. Deleting properties also blocks all future instances of properties with the same name. If you send data to Amplitude with a deleted or blocked property name, the data doesn't come through. ### Did the property come through in the raw payload to Segment? If the property isn't in Segment, it isn't in Amplitude. Check Segment's debugger to confirm that the property appeared in Segment first. ### Does the property exist in Segment's schema? Check your tracked properties and confirm they exist in Segment. ### Spot any syntax code errors or other instrumentation errors? Instrumentation errors aren't always obvious. Check the code for syntax errors (the browser Console tab can help). Refer to [Segment's specs](https://segment.com/docs/spec/) for how to format your data. Amplitude has a [limit of 1024 characters](https://amplitude.com/docs/faq/limits-and-quotas). If the property value is too long, the property doesn't appear in Amplitude. ### Why does the location information (city or country) from Segment's data differ from the location information in Amplitude's data? Amplitude tries to determine the user's location from the user's IP address, if available. This location may differ from the location information Segment recorded. ## Incorrectly-tracked sessions ### What is the definition of a session? A session is a period of time when the user has the application open in the foreground. If session tracking is available, events logged within the same session share the same session ID. A new session starts when the application enters the foreground after being in the background or closed for more than five minutes. ### Why do all of my events have a `sessionId` of -1? If you use the Amplitude Classic integration in Cloud mode, Segment doesn't provide session tracking by default, so Session ID appears as -1 in Amplitude. Segment doesn't have a [concept for a session](https://segment.com/blog/facts-vs-stories-why-segment-has-no-sessions-api/). You must pass in the sessionId for your server-side calls from Segment to Amplitude. For more details, refer to [Segment's Amplitude integration docs](https://segment.com/docs/integrations/amplitude/#sessionid%C2%A0). If you use Segment's client-side bundled integration, the integration uses Amplitude's native SDKs, which track Session IDs for you. Segment provides these options: - Use the integration in device mode and use Amplitude's native SDKs' default session tracking. For details, refer to the [Segment source catalog](https://amplitude.com/docs/data/source-catalog/segment). - If you use the Amplitude Actions integration from Segment, session tracking is available in Segment's new libraries [Analytics.js 2.0](https://segment.com/docs/connections/sources/catalog/libraries/website/javascript/), [Swift](https://github.com/segmentio/analytics-swift), or [Kotlin](https://github.com/segmentio/analytics-kotlin). For details, refer to [Segment's Amplitude Actions docs](https://segment.com/docs/connections/destinations/catalog/actions-amplitude/#connection-modes-for-amplitude-actions-destination). ### Why are there no session length calculations in Amplitude Dashboard? When Session ID is -1 (refer to the previous answer), Amplitude can't calculate session length. ### What if Segment's SDK doesn't support feature X? \[device-mode\] The Segment SDK might not have all the APIs the Amplitude SDK provides. You can still access features by directly calling Amplitude's SDKs. ### Still have questions? Submit a Support ticket with the following details: - What type of connection are you using? ([cloud-mode or device-mode](https://segment.com/docs/connections/destinations/#connection-modes)). - Do you have any destination filters enabled? - Do you see any errors in the _Event Delivery_ tab? - Confirm that you're using the correct API Key for the Amplitude destination. Also share the raw data for an event that should have been in Amplitude but is missing. Amplitude needs a full payload of the event, including the endpoint used, header, and body. ## iOS 14 changes At WWDC 2020, Apple announced that iOS 14 requires users to opt in to tracking. The IDFA is only present for users who explicitly opt in, and the percentage of users who do so is likely to be low. This article covers frequently asked questions about Apple's iOS 14 IDFA changes. ### Does Amplitude accept IDFA (Identifier for Advertisers) as the device identifier on iOS? By default, Amplitude's iOS SDK uses IDFV (Identifier for Vendor) for the device ID. You can change this and use any value as the device identifier. The SDK includes an option to use IDFA as the device ID, but this option only works if the user has permitted the application to use IDFA. ### What are the implications of Apple's IDFA changes on user tracking? For logged-in users, there's no impact. Even if the device ID changes, events continue to merge from devices when Amplitude receives a common user ID. Anonymous users have some potential for impact. For anonymous users, there are no changes in most cases, because most Amplitude customers don't set IDFA as the device ID. For customers who do set IDFA as the device ID, Amplitude stores the device ID when the SDK initializes, and the SDK continues to send Amplitude the same ID as long as the application remains installed on the device. If a user deletes and reinstalls an application that uses IDFA for device ID, the SDK doesn't retain the former device ID. Instead, the SDK generates a new random device ID, unless the user grants the application permission to use IDFA. For all new application installs, the SDK accepts IDFA if the user has opted in and the application chooses to use IDFA. ### Does Amplitude require IDFA on attribution events? No. Amplitude's attribution API accepts both IDFA and IDFV, and tries to match those IDs to user events Amplitude receives later. In some cases, IDFV is enough to make a match, but some Amplitude customers' attribution providers only send IDFA. For these customers, Amplitude can no longer match attribution events unless the user has explicitly opted in to both the referring and installed application. Some attribution vendors are likely to stop sending individual attribution events. Vendors are unlikely to send aggregated data to Amplitude (because of the nature of the platform), unless customers or attribution vendors can segment that data and use it to set user properties. ### How does this affect outbound integrations? If you send data to outbound integrations, you see a lower match rate when using IDFA to match devices between Amplitude and the integration. Amplitude recommends switching to IDFV or another common identifier instead. ## Missing mobile attribution events Mobile attribution partners identify events using advertising IDs like IDFA, IDFV, or ADID. Amplitude identifies users based on a combination of `user_id`, `device_id`, and `amplitude_id`. Amplitude's [Attribution API](https://amplitude.com/docs/apis/analytics/attribution) reconciles these differences and maps attribution events to existing users in Amplitude. Some mobile attribution partners (Appsflyer, Adjust, Branch, and Singular) use this API to send their non-custom, standard data with the advertising IDs as the identifier. Amplitude stores unmapped attribution events for 72 hours. During that time, Amplitude looks for a matching IDFA, IDFV, or ADID on an existing user in an Amplitude project. If a match exists, Amplitude routes the attribution event to that user. If no match exists, Amplitude drops the attribution event after 72 hours. To support this process, instrument Amplitude with advertising IDs enabled. ## Why mobile attribution events may be missing You can resolve some causes quickly: - The attribution events didn't successfully send to Amplitude. Confirm that the attribution partner receives a success response (for example, a 200) when sending events. - Your project has reached the [instrumentation limit](https://amplitude.com/docs/faq/limits-and-quotas). Delete event types or properties to allow Amplitude Analytics to ingest new event types and properties. - You blocked or deleted the event type in the Amplitude project. Restore the event type or property through Amplitude Data to fix the issue. Other causes require more investigation: - No existing user in Amplitude with the matching IDFA, IDFV, or ADID. - Amplitude didn't complete mapping within 72 hours. ## Troubleshoot: No existing user in Amplitude with the matching IDFA, IDFV, or ADID This is the top reason why Amplitude Analytics doesn't ingest mobile attribution events. You must instrument Amplitude before you can send mobile attribution events. ### Determine if you're tracking advertising IDs Advertising IDs are IDFA, IDFV, or ADID. If you track advertising IDs in your Amplitude events, Amplitude Analytics captures their value in the respective property field. For security and PII reasons, advertising IDs don't appear as a usable property, and Amplitude removes advertising IDs from your raw data after capture (unless you instrument advertising IDs as a custom property). Amplitude stores a hashed version of the advertising IDs in a field called `amplitude_attribution_ids`. Use this field to determine whether you're instrumenting advertising IDs. If the value is `null`, Amplitude captured no advertising IDs for this user. A `null` value generally means either that you haven't instrumented Amplitude Analytics to capture advertising IDs, or that the end user has opted out of advertising ID tracking. You must honor user opt-outs. If you track advertising IDs properly and want to confirm that `amplitude_attribution_ids = null` results from a user opt-out, contact Amplitude Support. ### Solution: Tracking advertising IDs If you use JavaScript, which can't track advertising IDs automatically, send an Amplitude event with the advertising ID through the [HTTP API](https://amplitude.com/docs/data/sources/instrument-track-unique-users). ## Troubleshoot: Mapping didn't happen within 72 hours Amplitude holds an attribution event for 72 hours. If Amplitude doesn't make a match during that time, Amplitude drops the event. For example, User A downloads a game app on December 1 but doesn't open the app until December 7: - Mobile attribution partners list an Install event for User A on December 1 and send that event to Amplitude on December 1. - User A doesn't record their first event in Amplitude until they open the app on December 7. Amplitude considers User A a new user on December 7. Amplitude drops User A's `Install` event because User A didn't exist in Amplitude within 72 hours of the attribution event. User A only existed in Amplitude seven days after the `Install` event, which is longer than the 72-hour holding period. ### Determine if the attribution event came too early Amplitude's iOS SDKs capture IDFV as `device_id` by default. If you use the default setting for iOS SDKs, use this process to troubleshoot: 1. Identify an iOS SDK user in Amplitude who doesn't have an `Install` event, even though there is a value for `amplitude_attribution_ids`. 2. Copy the `device_id` (IDFV) of that user. 3. With your mobile attribution provider, look for the `Install` event of the IDFV. 4. Check the date on the `Install` event. 5. Compare that date to the New User date in Amplitude. The mobile attribution provider likely sent the `Install` event more than 72 hours before the user existed in Amplitude. You can also check whether a user already exists in Amplitude by following a similar process: 1. Identify an iOS Install event from the mobile attribution provider that doesn't appear in Amplitude yet. 2. Get the IDFV on that payload. 3. Enter the IDFV in the [user look-up](https://amplitude.com/docs/analytics/user-data-lookup) feature as the device ID. The IDFV likely doesn't associate with a profile in Amplitude Analytics, which means Amplitude hasn't seen the user yet. ### Solution: Create users before real user activity An end user exists in Amplitude when Amplitude receives the user's first event. If you don't want to wait on the end user's actions to trigger profile creation, create a profile yourself by either: - Sending a placeholder event with advertising ID and `device_id` or `user_id` through the HTTP API. - Creating a profile with advertising ID and `device_id` or `user_id` through the Identity API. Creating a profile is only possible if you can capture the advertising ID on your own. Maintain the correct `device_id` or `user_id` so you connect real-world user activity to the right profile. ## Instrument on third-party site builders > **Note:** > > These instructions may become outdated as the third-party platforms covered here make changes and upgrades. Amplitude's Support team provides support for the instructions and processes in this article only; they can't provide recommendations for anything not included here. ### How do I instrument Amplitude on a third-party website builder? If your site runs on a third-party website builder like Wix or Squarespace, most builders have an underlying code base you can use. Add Amplitude's [JavaScript SDK](https://amplitude.com/docs/sdks/analytics/browser/javascript-sdk) to that space, as if you were adding the SDK to a natively-built website. Add the [JavaScript SDK snippet](https://amplitude.com/docs/sdks/analytics/browser/javascript-sdk#install) to the header, and the rest of the JavaScript SDK code in the body. If you don't have access to the header or underlying source code, you can use [webhooks](https://en.wikipedia.org/wiki/Webhook) to combine a [trigger](https://support.zendesk.com/hc/en-us/articles/203662106) or [automation](https://support.zendesk.com/hc/en-us/articles/203662126) with an HTTP target to Amplitude's server-side endpoint, [HTTP v2](https://amplitude.com/docs/apis/analytics/http-v2). ### How do I instrument Amplitude on Wix? Wix has a Tracking Tools & Analytics feature, which you can use to embed Amplitude's JavaScript SDK snippet and code in your site. To do so, follow these steps: 1. Go to [_Settings_ in your site's dashboard](https://www.wix.com/my-account/site-selector/?buttonText=Manage%20Settings&title=Select%20a%20Site&autoSelectOnSingleSite=true&actionUrl=https://www.wix.com/dashboard/%7B%7BmetaSiteId%7D%7D/manage-website). 2. Click the **Tracking & Analytics** tab, under _Advanced Settings_. 3. Click **+ New Tool** and select **Custom**. 4. Set up your custom code: 1. Enter your custom code. 2. Select the relevant domain. This option appears only if you have multiple domains. 3. Enter a name for your custom code. 4. Add Code to Pages: Select which pages to add your code to: - All Pages: Click the dropdown and select either **Load code once**, or [**Load code on each new page**](https://support.wix.com/en/article/custom-code-loading-options). - Choose specific pages: Begin typing the name of the relevant pages. Then click the checkbox next to the relevant page. 5. Place Code in: Select where to place the code snippet in your site's code. - Head: This is where to place the [JS SDK install snippet](https://amplitude.com/docs/sdks/analytics/browser/javascript-sdk#install) on every page to track analytics. - Body: This is where all other calls like [logEvent](https://amplitude.com/docs/sdks/analytics/browser/migrate-from-javascript-sdk-to-browser-sdk-1-0#logevent) and [user properties](https://amplitude.com/docs/sdks/analytics/browser/migrate-from-javascript-sdk-to-browser-sdk-1-0#set-user-properties) should go. 5. Click **Apply**. Some customers have reported that Wix lets you add header scripts but not call functions from them. One workaround is to put the necessary script in the Public folder. #### Further reading on Wix - [Adding custom code to your site](https://support.wix.com/en/article/about-tracking-tools-analytics). - [Embedding custom code on your site](https://support.wix.com/en/article/embedding-custom-code-to-your-site). ### How do I instrument Amplitude on Squarespace? Squarespace's Code Injection and Code Block features let you embed Amplitude's JS SDK snippet and code in your site. > **Note:** > > These features may be premium features, only available in Business and Commerce plans. #### Code Injection Use Code Injection to add Amplitude's JavaScript SDK install snippet and other scripts that enhance specific parts of your site, like an order confirmation page. To add JavaScript to a Code Injection field, surround the code with `<script></script>` tags. Site-wide and per-page code injection options are both available. For the per-page code injection option, refer to [Squarespace's Code Injection article](https://support.squarespace.com/hc/en-us/articles/205815908). If you add code to Code Injection, Squarespace may ask you to [disable the code while editing your site](https://support.squarespace.com/hc/articles/205815908#toc-disable-scripts-in-preview). To add the JavaScript SDK install snippet with Code Injection: 1. Open Code Injection. In the _Home_ menu, navigate to _Settings > Advanced > Code Injection_. 2. Add JavaScript SDK code into the appropriate Code Injection fields for the header, footer, lock page, or order confirmation page. - Header: Code added here goes into the `<head>` tag on every page in your site. The Amplitude JavaScript SDK install snippet belongs here. - For information on the other three options, refer to [Squarespace's Code Injection article](https://support.squarespace.com/hc/en-us/articles/205815908). 3. After adding your code, click **Save**. #### Code Block Use Code Block to set up logEvent, user properties, and similar calls. To add JavaScript to a Code Block field, surround the code with `<script></script>` tags. To add a Code Block, follow these steps: 1. Edit a page or post, click an insert point, and select **Code** from the menu. For help, refer to [Adding content with blocks](https://support.squarespace.com/hc/articles/206543757). 2. [Add your code](https://support.squarespace.com/hc/en-us/articles/206543167#toc-add-code) in the text field. For event and property calls, refer to the [Browser SDK 2 documentation](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#track-an-event). 3. If you're using the Code Block to [display code snippets](https://support.squarespace.com/hc/en-us/articles/206543167#toc-display-source), check **Display Source**. 4. Click **Apply** to save your changes. ================================================================================ # Common Patterns URL: https://amplitude.com/docs/data/common-patterns Updated: 2026-07-22 ================================================================================ # Common Patterns Amplitude fits into many different data stacks. Most customers use one of four patterns: 1. Amplitude as the primary analytics destination. 2. Amplitude with a Customer Data Platform (CDP) such as Segment. 3. Amplitude with a data warehouse such as Snowflake, BigQuery, Redshift, or Databricks. 4. Amplitude with both a CDP and a data warehouse. Across all four, Amplitude's web, mobile, and server SDKs give you a single way to collect events, power Session Replay, and stream that same data to the rest of your stack through Event Stream and exports. After you instrument your product, you rarely need to change application code when you add new destinations. You can instrument Amplitude Session Replay in several ways. For the browser, use the Session Replay plugin for the Amplitude Browser SDK, a standalone Session Replay SDK, Google Tag Manager, or a Segment integration. For iOS, Android, and React Native, use plugins that sit on top of Amplitude's analytics SDKs, standalone Session Replay SDKs, or Segment-based options. Instrumenting Session Replay together with events gives you three main benefits: - You can trace every chart, funnel, and cohort back to real user sessions so teams can watch what users did. - Product and engineering teams can debug issues faster by combining quantitative signals such as drop-offs or errors with qualitative evidence from replays. - You get a single set of SDKs and privacy controls for both analytics events and replay, which simplifies governance. The sections below describe how each data stack pattern works. ## Amplitude only In this setup, Amplitude and its SDKs are your main event collection, Session Replay, and analytics layer. ### Data flow Your website, mobile apps, and backend services send behavioral events directly to Amplitude using Amplitude SDKs or HTTP APIs. The same web and mobile SDKs can capture Session Replay data for selected sessions. Amplitude stores and processes everything for product analytics, experimentation, journey analysis, cohorts, and session-level insights. From there, you can sync events, cohorts, and selected replay links to downstream tools. ### Role of the SDKs and Session Replay Because Amplitude SDKs collect events and replay, you can later turn on Event Stream and forward those same events from Amplitude to other tools such as a warehouse, CDP, or marketing systems, without changing tracking in your application. Session Replay shares the same user and session identifiers as your events, so product teams can move from a funnel in Amplitude to a specific session and watch what happened at a critical step. ### When this works well This pattern is ideal when you're building a new analytics stack, don't yet have a central warehouse or CDP, and want to standardize tracking and replay quickly with one SDK implementation. ### Key benefits - Fast time to value with minimal infrastructure. - Single place to define events, properties, identities, and replay settings. - You can use Event Stream from Amplitude as you add new tools later. - Direct connection between quantitative analysis and qualitative replay for faster debugging and UX improvement. ## Amplitude with a CDP Here, a CDP is the primary collection and routing layer, and Amplitude is a downstream analytics and activation destination. ### Data flow Your product sends events to the CDP using CDP SDKs. The CDP forwards a copy of those events to Amplitude and routes them to marketing tools and ad platforms. Amplitude uses that behavioral data for product analytics, experimentation, cohorts, and activation. You can instrument Session Replay in four main ways. The last method uses a CDP: 1. Using the [Amplitude Session Replay SDK](https://amplitude.com/docs/sdks/session-replay/session-replay-standalone-sdk). 2. Using the [Amplitude Session Replay Browser SDK plugin](https://amplitude.com/docs/sdks/session-replay/session-replay-plugin). 3. Using [Google Tag Manager](https://amplitude.com/docs/sdks/session-replay/session-replay-google-tag-manager). 4. Using [Segment](https://amplitude.com/docs/sdks/session-replay/session-replay-integration-with-segment). These methods let you keep the CDP as the central event router while still getting session-level visibility inside Amplitude. ### Role of the SDKs and Session Replay Most customers either instrument events only through the CDP SDKs and use Amplitude's SDKs specifically for Session Replay and any extra product-only events, or combine CDP and Amplitude SDKs more broadly for redundancy and lower latency. In all cases, Amplitude can still use Event Stream to forward its copy of events to other destinations. ### When this works well This pattern is common when you've already deployed a CDP that owns identity resolution and audience syncs, and marketing teams rely on it. Amplitude becomes the main product analytics and Session Replay surface while the CDP remains the system through which events pass. ### Key benefits - Single event schema in the CDP shared across Amplitude and marketing tools. - Amplitude benefits from the CDP's unified identities while adding deep product analytics and replay. - You can use Session Replay to explain patterns seen in CDP-driven campaigns and journeys. - You can stream Amplitude's enriched event data into other systems. ## Amplitude with a data warehouse In this pattern, Amplitude is the product analytics and event collection layer, and the warehouse is the central storage and business intelligence layer. ### Data flow Your applications send events and Session Replay data into Amplitude using Amplitude SDKs. Amplitude stores and processes events and replay for analytics and troubleshooting. Amplitude then exports raw or modeled event data to your warehouse on a schedule or through streaming. Business intelligence tools query the warehouse to combine Amplitude events with billing, CRM, support, and other data. You can activate this data out of the warehouse with a Reverse ETL tool like Hightouch. ### Role of the SDKs and Session Replay Amplitude SDKs define a behavioral schema optimized for product analytics and replay. After you instrument, you don't need separate tracking for warehouse use. Events flow first into Amplitude, then into the warehouse through exports or Event Stream. Session identifiers and user identifiers stay consistent across analytics in Amplitude and tables in the warehouse, so data teams can link warehouse-based models such as churn or lifetime value back to specific replays for qualitative investigation. ### When this works well This pattern fits organizations where product teams rely on Amplitude for self-service analytics and debugging, while the data team uses the warehouse for cross-domain reporting and modeling. ### Key benefits - One instrumentation path for both analytics and warehouse use. - The warehouse receives clean event data that Amplitude has already validated. - Data teams can join behavioral events with other domains while still using Amplitude for quick analysis and Session Replay. - Replays give valuable context when investigating anomalies or model outputs discovered in warehouse-based dashboards. ## Amplitude with CDP and data warehouse This pattern combines all three components. The CDP (or a CDI like Snowplow) is the real-time collection and routing layer, the warehouse is the long-term storage and modeling layer, and Amplitude is the product analytics, Session Replay, and activation layer. ### Data flow Your applications send events into the CDP using its SDKs. The CDP forwards those events to Amplitude and to the warehouse. Amplitude instruments Session Replay through its own SDKs, plugins, or Segment-based integrations, and attaches replays to the sessions that originate from CDP events. The warehouse receives event data from the CDP or Amplitude, and data teams build models and aggregate tables there. You can send modeled attributes and scores back into Amplitude or the CDP with reverse ETL. ### Role of the SDKs and Session Replay CDP SDKs typically provide the core event stream. Amplitude SDKs focus on Session Replay and any Amplitude-specific instrumentation that you choose to add. Amplitude can still stream enriched events and replay metadata to the warehouse or other tools. This combination gives you multiple controlled paths for data without duplicating tracking logic in code. ### When this works well This pattern fits data-mature organizations where: - The CDP owns event collection, identity resolution, and routing. - The warehouse owns storage, modeling, and governance. - Amplitude owns behavioral analytics, experimentation, Session Replay, and product-led activation. ### Key benefits - Shared behavioral data across product, marketing, sales, and analytics teams. - Strong governance for schemas and identities with clear ownership in CDP and warehouse. - Session Replay directly tied to CDP-based journeys and warehouse-based models to explain the why behind metrics. - You can stream Amplitude events and replay context to many downstream tools without new SDK work in the product. ## Choosing the right pattern Many customers evolve through these patterns over time. 1. Start with Amplitude only and instrument both events and Session Replay with Amplitude SDKs to get quick value and a consistent behavioral model. 2. Add a CDP to standardize collection for marketing and other tools while still using Amplitude for analytics and replay. 3. Add a warehouse to centralize storage, join across systems, and support advanced modeling and business intelligence. 4. Connect all three so that the system best suited for each job handles collection, analytics, replay, and storage. Across all four scenarios, Amplitude's instrumentation layer for events and Session Replay is reusable and extensible. After data flows into Amplitude, you can use Event Stream and exports to route events and replay context across your stack, so your architecture can evolve while your tracking plan remains stable. ================================================================================ # Autocapture Events and Properties URL: https://amplitude.com/docs/data/autocapture-events-and-properties Updated: 2026-07-14 ================================================================================ # Autocapture Events and Properties This reference lists Autocapture event types and event property names for web when you use the [Browser SDK 2](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2). Use this reference to understand what Amplitude captures automatically, configure your tracking plan, or set up pipelines and validation. For a machine-readable version of this page, go to [Web Autocapture Schema](https://amplitude.com/docs/data/web-autocapture-schema). For native iOS and Android Autocapture event properties, go to [Mobile Autocapture Schema](https://amplitude.com/docs/data/mobile-autocapture-schema). ## Shared conventions - Property names in bold (for example, **Page URL**) reflect how they appear in Amplitude. - Autocapture prefixes some properties with `[Amplitude]`. Amplitude generates these automatically and marks them as read-only. - Configure which events Amplitude captures through `AutocaptureOptions` in the Browser SDK 2. ## Sessions ### Session started Captures when a user session begins, either on first page load or after a period of inactivity. | Property Name | Description | | --- | --- | | _No properties collected_ | | ### Session ended Captures when a user session ends due to inactivity or the browser tab closing. | Property Name | Description | | --- | --- | | _No properties collected_ | | ## Page views ### Page viewed Captures each time a user loads or navigates to a page, including single-page app route changes. | Property Name | Description | | --- | --- | | **Page Domain** | The full hostname from the current web address, including any subdomains such as `www` or `app`. | | **Page Location** | The full URL of the current page, including any URL Search Parameters. | | **Page Path** | The pathname of the current page. This excludes any URL Search Parameters and URL Fragments. | | **Page Title** | The title of the page. | | **Page URL** | The URL of the page excluding the URL Search Parameters. | ## File downloads ### File downloaded Captures when a user clicks a link that triggers a file download. | Property Name | Description | | --- | --- | | **File Extension** | The extension of the downloaded file. For example: .pdf, .docx, .zip, and so forth. | | **File Name** | The full pathname of the downloaded file. This can include more than just the filename of the file. | | **Link ID** | The ID of the link element. | | **Link Text** | The text content of the link element. | | **Link URL** | The link address of the file download. | ## Form interactions Autocapture captures forms that use the `<form>` tag. ### Form started Captures when a user initially interacts with a form element, including modifications to a text input, radio button, or dropdown. | Property Name | Description | | --- | --- | | **Form Destination** | The action attribute of the form element. For example, for `<form action="/subscribe">`, the value is `/subscribe`. | | **Form ID** | The ID of the form element. | | **Form Name** | The name attribute of the form element. | ### Form submitted Captures when a user submits the form. | Property Name | Description | | --- | --- | | **Form Destination** | The action attribute of the form element. For example, for `<form action="/subscribe">`, the value is `/subscribe`. | | **Form ID** | The ID of the form element. | | **Form Name** | The name attribute of the form element. | ## Element interactions ### Element clicked Captures clicks on page elements. The default configuration captures user interactions with interactive elements on your page. The default eliminates event noise such as clicks to highlight text and white-space clicks. The default captures the following: - All clicks on form elements: `<a>`, button, input, select, text area, label, and elements where `contentEditable` is set to `true`. - All clicks on video and audio elements. - Clicks on select elements that result in a change on your page (for example, a modal appearing) or navigation to another page. These elements include divs, spans, and headers. - All clicks on elements with an attribute of `data-amp-default-track` or a class of `amp-default-track`. - You can customize this configuration to add or remove selectors. You can choose whether Amplitude always tracks those selectors or only when the click results in a change to the page. | Property Name | Description | | --- | --- | | **Element ID** | The `id` attribute of the HTML element. For example, an element with `id="myID"` produces the value `myID`. | | **Element Class** | The `class` attribute of the HTML element. For example, an element with `class="myClass"` produces the value `myClass`. | | **Element Tag** | The tag name of the HTML element. For example, an `<a>` element produces the value `a`. | | **Element Text** | The text content (`innerText`) of the HTML element. Only applies to the Element Clicked event. For example, a link with text "Home" produces the value `Home`. | | **Element Href** | The `href` attribute of the HTML element. Only applies to `<a>` tags on the Element Clicked event. Amplitude truncates values longer than 128 bytes. | | **Element Position Left** | The distance of the element from the left of the screen view, in pixels. For example, a value of `600` means the element was 600px from the left. | | **Element Position Top** | The distance of the element from the top of the screen view, in pixels. For example, a value of `400` means the element was 400px from the top. | | **Viewport Height** | The height of the viewport in pixels when the element was clicked. For example, a value of `900` means the viewport was 900 pixels tall. | | **Viewport Width** | The width of the viewport in pixels when the element was clicked. For example, a value of `1200` means the viewport was 1200 pixels wide. | | **Page URL** | The URL of the page where the element was clicked. | | **Page Title** | The page title of the page where the element was clicked. | | **Element Hierarchy** | DOM elements and attributes of the element clicked and its parent or sibling elements. Amplitude uses this for visual labeling. | | **Element Selector** | **Deprecated** in favor of Element Hierarchy. A unique CSS selector of the element. For example, an element with `id="myID"` produces the value `#myID`. | | **Element Attributes** | Unique attributes associated with click events through the `dataAttributePrefix` setting. For example, an element with attribute `id="feature-start"` produces a property `[Amplitude] Element Attributes.id` with the value `feature-start`. | | **Element Aria Label** | The `aria-label` of the element, used for interactive elements without visible text. For example, an element with `aria-label="Close"` produces the value `Close`. | | **Element Parent Label** | The text label in the parent element (or upper ancestors if not found in the one-level parent) of the element. | ### Element changed Captures form element interactions, such as changes to a dropdown or entering text in a text box. | Property Name | Description | | --- | --- | | **Element ID** | The `id` attribute of the HTML element. | | **Element Class** | The `class` attribute of the HTML element. | | **Element Tag** | The tag name of the HTML element. | | **Element Position Left** | The distance of the element from the left of the screen view, in pixels. | | **Element Position Top** | The distance of the element from the top of the screen view, in pixels. | | **Viewport Height** | The height of the viewport in pixels when the element changed. | | **Viewport Width** | The width of the viewport in pixels when the element changed. | | **Page URL** | The URL of the page where the element changed. | | **Page Title** | The page title of the page where the element changed. | | **Element Hierarchy** | DOM elements and attributes of the element changed and its parent or sibling elements. Amplitude uses this for visual labeling. | | **Element Selector** | **Deprecated** in favor of Element Hierarchy. A unique CSS selector of the element. | | **Element Attributes** | Unique attributes associated with change events through the `dataAttributePrefix` setting. | | **Element Aria Label** | The `aria-label` of the element, used for interactive elements without visible text. | | **Element Parent Label** | The text label in the parent element (or upper ancestors if not found in the one-level parent) of the element. | ## Network requests Captures when the application makes a network request. By default, Amplitude tracks network requests with a response code in the range 500-599 and excludes requests made to any `amplitude.com` domain. To enable network request tracking, set `config.autocapture.networkTracking` to `true` in your SDK configuration. | Property Name | Description | | --- | --- | | **\[Amplitude\] URL** | The URL of the network request with sensitive information masked. | | **\[Amplitude\] URL Query** | The query parameters of the URL. | | **\[Amplitude\] URL Fragment** | The fragment identifier of the URL. | | **\[Amplitude\] Request Method** | The HTTP method used for the request (for example, GET, POST, PUT, or DELETE). | | **\[Amplitude\] Status Code** | The HTTP status code of the response. | | **\[Amplitude\] Error Code** | The local error code if the request failed without a status code. | | **\[Amplitude\] Error Message** | The local error message if the request failed without a status code. | | **\[Amplitude\] Start Time** | The timestamp when the request started, in milliseconds since Unix epoch. | | **\[Amplitude\] Completion Time** | The timestamp when the request completed, in milliseconds since Unix epoch. | | **\[Amplitude\] Duration** | The duration of the request in milliseconds. | | **\[Amplitude\] Request Body Size** | The size of the request body in bytes. | | **\[Amplitude\] Response Body Size** | The size of the response body in bytes. | | **\[Amplitude\] Request Body** | The captured JSON request body (when you configure a `requestBody` capture rule). | | **\[Amplitude\] Response Body** | The captured JSON response body (when you configure a `responseBody` capture rule). | For more information about configuring network tracking, including advanced capture rules and filtering options, refer to [Track network requests](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#track-network-requests) in the Browser SDK 2 documentation. ## Web Vitals Captures Core Web Vitals performance metrics when the browser tab hides. | Property Name | Description | | --- | --- | | **Page Domain** | The full hostname from the current web address, including any subdomains such as `www` or `app`. | | **Page Location** | The full URL of the current page, including any URL Search Parameters. | | **Page Path** | The pathname of the current page. This excludes any URL Search Parameters and URL Fragments. | | **Page Title** | The title of the page. | | **Page URL** | The URL of the page excluding the URL Search Parameters. | | **LCP (Largest Contentful Paint)** | The time it takes for the largest content element to become visible in the viewport. Measured in milliseconds. | | **FCP (First Contentful Paint)** | The time it takes for the first content element to be painted on the screen. Measured in milliseconds. | | **INP (Interaction to Next Paint)** | The time from a user interaction to the next paint. Measured in milliseconds. | | **CLS (Cumulative Layout Shift)** | The sum of all individual layout shift scores for unexpected layout shifts. A dimensionless value. | | **TTFB (Time to First Byte)** | The time from the navigation start to when the first byte of the response is received. Measured in milliseconds. | Each metric includes a performance rating (good, needs-improvement, or poor) based on Web Vitals thresholds and timing data. ================================================================================ # Web Autocapture Schema URL: https://amplitude.com/docs/data/web-autocapture-schema Updated: 2026-09-09 ================================================================================ # Web Autocapture Schema This reference lists Autocapture event types and event property names for web when you use the [Browser SDK 2](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2). Use it when you need a stable contract for pipelines, partners, or validation. For Autocapture setup steps, go to [Autocapture](https://amplitude.com/docs/get-started/autocapture). For full property descriptions with examples, go to [Autocapture events and properties](https://amplitude.com/docs/data/autocapture-events-and-properties). For native iOS and Android Autocapture event properties, go to [Mobile Autocapture Schema](https://amplitude.com/docs/data/mobile-autocapture-schema). ## Shared conventions - Event type values match what Amplitude stores as `event_type` (for example, `Page viewed`). - Web event types don't use the `[Amplitude]` prefix, except for `[Amplitude] Network Request`. - Property names appear in Amplitude exactly as listed here. - Session events carry no additional properties beyond standard user and session context. ## Machine-readable schema ```json { "description": "Web Autocapture event types and event property names for the Amplitude Browser SDK 2.", "documentation": "/docs/data/web-autocapture-schema", "web": { "sdk": "Browser SDK 2", "events": { "Session Started": { "properties": [] }, "Session Ended": { "properties": [] }, "Page viewed": { "properties": ["Page Domain", "Page Location", "Page Path", "Page Title", "Page URL"] }, "File Downloaded": { "properties": ["File Extension", "File Name", "Link ID", "Link Text", "Link URL"] }, "Form Started": { "properties": ["Form Destination", "Form ID", "Form Name"] }, "Form Submitted": { "properties": ["Form Destination", "Form ID", "Form Name"] }, "Element Clicked": { "properties": [ "Element ID", "Element Class", "Element Tag", "Element Text", "Element Href", "Element Position Left", "Element Position Top", "Viewport Height", "Viewport Width", "Page URL", "Page Title", "Element Hierarchy", "Element Attributes", "Element Aria Label", "Element Parent Label" ] }, "Element Changed": { "properties": [ "Element ID", "Element Class", "Element Tag", "Element Position Left", "Element Position Top", "Viewport Height", "Viewport Width", "Page URL", "Page Title", "Element Hierarchy", "Element Attributes", "Element Aria Label", "Element Parent Label" ] }, "[Amplitude] Network Request": { "properties": [ "[Amplitude] URL", "[Amplitude] URL Query", "[Amplitude] URL Fragment", "[Amplitude] Request Method", "[Amplitude] Status Code", "[Amplitude] Error Code", "[Amplitude] Error Message", "[Amplitude] Start Time", "[Amplitude] Completion Time", "[Amplitude] Duration", "[Amplitude] Request Body Size", "[Amplitude] Response Body Size", "[Amplitude] Request Body", "[Amplitude] Response Body" ] }, "Web Vitals": { "properties": [ "Page Domain", "Page Location", "Page Path", "Page Title", "Page URL", "LCP (Largest Contentful Paint)", "FCP (First Contentful Paint)", "INP (Interaction to Next Paint)", "CLS (Cumulative Layout Shift)", "TTFB (Time to First Byte)" ] } } } } ``` ## Web (Browser SDK 2) Configure which events Amplitude captures using `AutocaptureOptions` in the Browser SDK 2. Go to [Autocapture (Browser SDK 2)](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#autocapture-replaces-defaulttracking) for configuration options. | Event type | When it fires | Typical event properties | | --- | --- | --- | | `Session Started` | Session begins on first page load or after inactivity. | None. | | `Session Ended` | Session ends due to inactivity or browser tab closing. | None. | | `Page viewed` | User loads or navigates to a page, including single-page app route changes. | `Page Domain`, `Page Location`, `Page Path`, `Page Title`, `Page URL`. | | `File Downloaded` | User clicks a link that triggers a file download. | `File Extension`, `File Name`, `Link ID`, `Link Text`, `Link URL`. | | `Form Started` | User initially interacts with a form element (text input, radio button, or dropdown). | `Form Destination`, `Form ID`, `Form Name`. | | `Form Submitted` | User submits a form. | `Form Destination`, `Form ID`, `Form Name`. | | `Element Clicked` | User clicks an interactive page element. | `Element ID`, `Element Class`, `Element Tag`, `Element Text`, `Element Href`, `Element Position Left`, `Element Position Top`, `Viewport Height`, `Viewport Width`, `Page URL`, `Page Title`, `Element Hierarchy`, `Element Attributes`, `Element Aria Label`, `Element Parent Label`. | | `Element Changed` | User changes a form element such as a dropdown or text input. | `Element ID`, `Element Class`, `Element Tag`, `Element Position Left`, `Element Position Top`, `Viewport Height`, `Viewport Width`, `Page URL`, `Page Title`, `Element Hierarchy`, `Element Attributes`, `Element Aria Label`, `Element Parent Label`. | | `[Amplitude] Network Request` | Application makes a tracked HTTP request (response codes 500–599 by default). | `[Amplitude] URL`, `[Amplitude] URL Query`, `[Amplitude] URL Fragment`, `[Amplitude] Request Method`, `[Amplitude] Status Code`, `[Amplitude] Error Code`, `[Amplitude] Error Message`, `[Amplitude] Start Time`, `[Amplitude] Completion Time`, `[Amplitude] Duration`, `[Amplitude] Request Body Size`, `[Amplitude] Response Body Size`, `[Amplitude] Request Body`, `[Amplitude] Response Body`. | | `Web Vitals` | Browser tab hides; Amplitude collects Core Web Vitals. | `Page Domain`, `Page Location`, `Page Path`, `Page Title`, `Page URL`, `LCP (Largest Contentful Paint)`, `FCP (First Contentful Paint)`, `INP (Interaction to Next Paint)`, `CLS (Cumulative Layout Shift)`, `TTFB (Time to First Byte)`. | ================================================================================ # Mobile Autocapture Schema URL: https://amplitude.com/docs/data/mobile-autocapture-schema Updated: 2026-09-09 ================================================================================ # Mobile Autocapture Schema This reference lists Autocapture event types and event property names for native iOS and Android when you use the [iOS Swift SDK](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk) and [Android-Kotlin SDK](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk). Use it when you need a stable contract for pipelines, partners, or validation. > **Note:** React Native packages > > Amplitude doesn't ship a separate React Native Autocapture package. React Native apps that need comparable behavior typically instrument events manually or bridge to native SDKs. This schema applies to native iOS and Android Autocapture only. For Autocapture setup steps, go to [Autocapture](https://amplitude.com/docs/get-started/autocapture). For web Autocapture event properties, go to [Autocapture events and properties](https://amplitude.com/docs/data/autocapture-events-and-properties). For a machine-readable web schema, go to [Web Autocapture Schema](https://amplitude.com/docs/data/web-autocapture-schema). ## Machine-readable schema ```json { "description": "Native mobile Autocapture event types and event property names for Amplitude iOS Swift SDK and Android-Kotlin SDK. React Native is not included.", "documentation": "/docs/data/mobile-autocapture-schema", "ios": { "events": { "[Amplitude] Start Session": { "properties": [] }, "[Amplitude] End Session": { "properties": [] }, "[Amplitude] Application Installed": { "properties": ["[Amplitude] Version", "[Amplitude] Build"] }, "[Amplitude] Application Updated": { "properties": [ "[Amplitude] Version", "[Amplitude] Build", "[Amplitude] Previous Version", "[Amplitude] Previous Build" ] }, "[Amplitude] Application Opened": { "properties": [ "[Amplitude] Version", "[Amplitude] Build", "[Amplitude] From Background" ] }, "[Amplitude] Application Backgrounded": { "properties": [] }, "[Amplitude] Screen Viewed": { "properties": ["[Amplitude] Screen Name"] }, "[Amplitude] Deep Link Opened": { "properties": ["[Amplitude] Link URL", "[Amplitude] Link Referrer"] }, "[Amplitude] Network Request": { "properties": [ "[Amplitude] URL", "[Amplitude] URL Query", "[Amplitude] URL Fragment", "[Amplitude] Request Method", "[Amplitude] Status Code", "[Amplitude] Error Code", "[Amplitude] Error Message", "[Amplitude] Start Time", "[Amplitude] Completion Time", "[Amplitude] Duration", "[Amplitude] Request Body Size", "[Amplitude] Response Body Size", "[Amplitude] Request Body", "[Amplitude] Response Body", "[Amplitude] Request Headers", "[Amplitude] Response Headers" ] }, "[Amplitude] Element Interacted": { "properties": [ "[Amplitude] Action", "[Amplitude] Target View Class", "[Amplitude] Target Text", "[Amplitude] Target Accessibility Label", "[Amplitude] Target Accessibility Identifier", "[Amplitude] Action Method", "[Amplitude] Gesture Recognizer", "[Amplitude] Hierarchy", "[Amplitude] Screen Name" ] }, "[Amplitude] Rage Click": { "properties": [ "[Amplitude] Begin Time", "[Amplitude] End Time", "[Amplitude] Duration", "[Amplitude] Click Count", "[Amplitude] Clicks", "[Amplitude] Action", "[Amplitude] Target View Class", "[Amplitude] Target Text" ] }, "[Amplitude] Dead Click": { "properties": [ "[Amplitude] Begin Time", "[Amplitude] End Time", "[Amplitude] Duration", "[Amplitude] Action", "[Amplitude] Target View Class", "[Amplitude] Target Text" ] } } }, "android": { "events": { "[Amplitude] Start Session": { "properties": [] }, "[Amplitude] End Session": { "properties": [] }, "[Amplitude] Application Installed": { "properties": ["[Amplitude] Version", "[Amplitude] Build"] }, "[Amplitude] Application Updated": { "properties": [ "[Amplitude] Version", "[Amplitude] Build", "[Amplitude] Previous Version", "[Amplitude] Previous Build" ] }, "[Amplitude] Application Opened": { "properties": [ "[Amplitude] Version", "[Amplitude] Build", "[Amplitude] From Background" ] }, "[Amplitude] Application Backgrounded": { "properties": [] }, "[Amplitude] Screen Viewed": { "properties": ["[Amplitude] Screen Name"] }, "[Amplitude] Fragment Viewed": { "properties": [ "[Amplitude] Screen Name", "[Amplitude] Fragment Class", "[Amplitude] Fragment Identifier", "[Amplitude] Fragment Tag" ] }, "[Amplitude] Deep Link Opened": { "properties": ["[Amplitude] Link URL", "[Amplitude] Link Referrer"] }, "[Amplitude] Network Request": { "properties": [ "[Amplitude] URL", "[Amplitude] URL Query", "[Amplitude] URL Fragment", "[Amplitude] Request Method", "[Amplitude] Status Code", "[Amplitude] Error Message", "[Amplitude] Start Time", "[Amplitude] Completion Time", "[Amplitude] Duration", "[Amplitude] Request Body Size", "[Amplitude] Response Body Size" ] }, "[Amplitude] Element Interacted": { "properties": [ "[Amplitude] Action", "[Amplitude] Target Class", "[Amplitude] Target Resource", "[Amplitude] Target Tag", "[Amplitude] Target Text", "[Amplitude] Target Source", "[Amplitude] Hierarchy", "[Amplitude] Screen Name" ] }, "[Amplitude] Rage Click": { "properties": [] }, "[Amplitude] Dead Click": { "properties": [] } } } } ``` ## Shared conventions - Event type values match what Amplitude stores as `event_type` (for example, `[Amplitude] Screen Viewed`). - Property names use the `[Amplitude] ...` prefix in the product and in this doc. - Session events typically carry only standard user and session context unless you add more in code. ## iOS (Swift SDK) Enable options through `AutocaptureOptions`. Go to [Autocapture (iOS)](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk#autocapture) for configuration options. | Event type | When it fires | Typical event properties | | --- | --- | --- | | `[Amplitude] Start Session` | Session starts | User properties (when you enable user property collection). | | `[Amplitude] End Session` | Session ends | User properties (when you enable user property collection). | | `[Amplitude] Application Installed` | First open after install | `[Amplitude] Version`, `[Amplitude] Build`. | | `[Amplitude] Application Updated` | First open after update | `[Amplitude] Version`, `[Amplitude] Build`, `[Amplitude] Previous Version`, `[Amplitude] Previous Build`. | | `[Amplitude] Application Opened` | Launch or foreground after first open | `[Amplitude] Version`, `[Amplitude] Build`, `[Amplitude] From Background` (when applicable). | | `[Amplitude] Application Backgrounded` | App enters background | None. | | `[Amplitude] Screen Viewed` | UIKit screen appears | `[Amplitude] Screen Name`. | | `[Amplitude] Deep Link Opened` | Deep link opens | `[Amplitude] Link URL`, `[Amplitude] Link Referrer`. | | `[Amplitude] Network Request` | SDK captures HTTP traffic (per SDK rules) | `[Amplitude] URL`, `[Amplitude] URL Query`, `[Amplitude] URL Fragment`, `[Amplitude] Request Method`, `[Amplitude] Status Code`, `[Amplitude] Error Code`, `[Amplitude] Error Message`, `[Amplitude] Start Time`, `[Amplitude] Completion Time`, `[Amplitude] Duration`, `[Amplitude] Request Body Size`, `[Amplitude] Response Body Size`, plus optional experimental body and header properties when you enable them. | | `[Amplitude] Element Interacted` | `UIControl` / gesture interaction | `[Amplitude] Action`, `[Amplitude] Target View Class`, `[Amplitude] Target Text`, `[Amplitude] Target Accessibility Label`, `[Amplitude] Target Accessibility Identifier`, `[Amplitude] Action Method`, `[Amplitude] Gesture Recognizer`, `[Amplitude] Hierarchy`, `[Amplitude] Screen Name`. | | `[Amplitude] Rage Click` | Frustration (rage click) | Go to [Track frustration interactions](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk#track-frustration-interactions) for more information. | | `[Amplitude] Dead Click` | Frustration (dead click) | Same as [Rage Click](https://amplitude.com/docs/sdks/analytics/ios/ios-swift-sdk#track-frustration-interactions). | ## Android (Kotlin SDK) Enable options through `AutocaptureOption`. Go to [Autocapture (Android)](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk#autocapture) for configuration options. | Event type | When it fires | Typical event properties | | --- | --- | --- | | `[Amplitude] Start Session` | Session starts | User properties (when you enable user property collection). | | `[Amplitude] End Session` | Session ends | User properties (when you enable user property collection). | | `[Amplitude] Application Installed` | First open after install | `[Amplitude] Version`, `[Amplitude] Build`. | | `[Amplitude] Application Updated` | First open after update | `[Amplitude] Version`, `[Amplitude] Build`, `[Amplitude] Previous Version`, `[Amplitude] Previous Build`. | | `[Amplitude] Application Opened` | Launch or foreground after first open | `[Amplitude] Version`, `[Amplitude] Build`, `[Amplitude] From Background` (when applicable). | | `[Amplitude] Application Backgrounded` | App backgrounds | None. | | `[Amplitude] Screen Viewed` | Activity appears | `[Amplitude] Screen Name`. | | `[Amplitude] Fragment Viewed` | Fragment appears | `[Amplitude] Screen Name`, `[Amplitude] Fragment Class`, `[Amplitude] Fragment Identifier`, `[Amplitude] Fragment Tag`. | | `[Amplitude] Deep Link Opened` | Deep link opens | `[Amplitude] Link URL`, `[Amplitude] Link Referrer`. | | `[Amplitude] Network Request` | SDK captures HTTP traffic (plugin) | `[Amplitude] URL`, `[Amplitude] URL Query`, `[Amplitude] URL Fragment`, `[Amplitude] Request Method`, `[Amplitude] Status Code`, `[Amplitude] Error Message`, `[Amplitude] Start Time`, `[Amplitude] Completion Time`, `[Amplitude] Duration`, `[Amplitude] Request Body Size`, `[Amplitude] Response Body Size`. | | `[Amplitude] Element Interacted` | Clickable view or Compose | `[Amplitude] Action`, `[Amplitude] Target Class`, `[Amplitude] Target Resource`, `[Amplitude] Target Tag`, `[Amplitude] Target Text`, `[Amplitude] Target Source`, `[Amplitude] Hierarchy`, `[Amplitude] Screen Name`. | | `[Amplitude] Rage Click` | Frustration (optional) | Go to [Track frustration interactions](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk#track-frustration-interactions) for more information. | | `[Amplitude] Dead Click` | Frustration (optional) | Same as [Rage Click](https://amplitude.com/docs/sdks/analytics/android/android-kotlin-sdk#track-frustration-interactions). | ================================================================================ # Manage your Amplitude Data settings URL: https://amplitude.com/docs/data/amplitude-data-settings Updated: 2026-09-22 ================================================================================ # Manage your Amplitude Data settings On the Amplitude Data settings page, you configure and govern your Amplitude Data project, from naming and schema rules to integrations, API tokens, and permissions. Use these settings to: - Name your project and specify the naming conventions you use for events and properties. - Specify whether you require team reviews for all changes to main. - Set the Amplitude projects for your environments. - Add integrations. - Generate API tokens. - Delete your Amplitude Data project. These settings and features appear on five tabs: General, Environments, Integrations, API Tokens, and Schema Settings. This article describes each tab. > **Note:** > > Configure your settings before setting up your first Amplitude Data project. ## Plan availability Catalog: Public Links and Naming Convention Standards are available on all plans. Go to [Amplitude pricing](https://amplitude.com/pricing) for plan details. _Availability reflects the latest Amplitude plans. If your organization is on an older plan, your access may differ. Check your plan under [Plans & Billing in your organization settings](https://amplitude.com/docs/admin/account-management/account-settings#organizational-settings), or contact your Amplitude account representative._ ## Roles and permissions in Amplitude Data > **Note:** Role-based Access Controls (RBAC) > > For Enterprise organizations with Role-based Access Controls (RBAC) enabled, review the available [Data Roles and Permissions](https://amplitude.com/docs/admin/account-management/role-based-access-controls-rbac#rbac-permission-reference). | Role | Permissions | | --- | --- | | Admin | Configure workspace settings, approve tracking plan changes, and modify the tracking plan. | | Manager | Approve tracking plan changes and modify the tracking plan. | | Member | Modify the tracking plan for approval. | | Viewer | View the tracking plan and comment. | You can also restrict data management access while keeping permissions the same for other areas of Amplitude. Refer to [The Permissions tab](#the-permissions-tab) for more details. > **Info:** > > If you disable the **Require team reviews to make changes to the main branch** option in the project settings, members can modify the tracking plan, but approval isn't required. All other permissions remain the same. ## General The General tab is where you set the project name, the event and property naming conventions, team review requirements for changes on main, and where you delete your project. It's also where you find a public link to a read-only version of your tracking plan, so you can share it with stakeholders across your organization. ### Naming conventions Amplitude Data requires a consistent naming convention for events and properties. Without one, your tracking plan becomes harder to read and manage, because multiple events or properties can share the same name with different capitalization. Specify a custom naming convention, or choose from the following: - lower case. - Sentence case. - Title Case. - CamelCase. - lowerCamelCase. - snake\_case. ### Team reviews For larger teams and organizations, require team reviews for changes made to main. With this option, make any changes to your tracking plan in a branch other than main. Specify the number of reviewers required for approval, up to seven. ### Public link to your tracking plan To share your tracking plan, use the public link on the _General_ tab. Copy it to your clipboard and paste it into an email or Slack message. Stakeholders can read it but can't make changes. You can also enable or disable the public link, which changes the availability for the selected project. Click **Create Public Link** or **Delete Public Link**. ## Integrations Integrate Amplitude Data with existing tools to streamline your analytics workflow. To integrate a platform, click **Connect** or **Add** next to its name. ## API Tokens Use API tokens to authenticate to Amplitude Data using credentials other than your email address and password. Tokens authorize applications to use the same roles and permissions you have when you log in personally. To create an API token, click **Create Token**. Amplitude Data generates the token and displays it in a modal window. Click **Copy to clipboard** immediately, because you can't retrieve the token later. ## Schema Settings Amplitude Data might receive data from your app that it doesn't know what to do with. This is usually the result of a schema violation, meaning your schema doesn't account for the received data. This usually happens when you don't plan for a particular data type or value when first setting up your schema. Configure your schema settings to tell Amplitude how to handle these situations. For any unplanned events, event properties, event property types, user properties, or user property types, tell Amplitude Data to either mark them as unexpected or to reject them outright. Amplitude Data ingests any unexpected events or properties and sends a notification to everyone subscribed to this schema. If you reject unexpected data, Amplitude Data doesn't ingest or store the rejected data, but subscribers still receive a notification. Click **Save** to apply any changes to your schema settings. ## The Permissions tab Data permissions restrictions limit who can perform Data Management functions. For example, you might want most users to have the Member role so they can create dashboards and charts, but limit custom event creation and other data management features to managers or administrators. In the Permissions tab, add restrictions for selected roles to limit data management access while keeping other permissions unchanged for those roles. Under Restrict access in Amplitude Data, choose from the following options to restrict permissions to the viewer level on a per-project basis: - Use Default Restrictions. - Restrict Members. - Restrict Members and Managers. Then click **Save**. Permission restrictions are available for Enterprise customers only. Only administrators can access the Permissions tab. ### Copy to other projects Click **Copy to Other Projects** to apply the current permission restriction settings to another project. ## Autocapture The Autocapture settings in Amplitude Data let you change the configuration of the Analytics Browser SDK directly from within Amplitude, so you can make changes without code changes or releases. These settings merge with any configuration you defined locally in your SDK initialization code on your website. ### Availability Autocapture settings are available on projects that use version 2.10.0 or higher of the [Amplitude Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2) with `fetchRemoteConfig` enabled. To disable remote configuration, set `fetchRemoteConfig` to `false`. Disabling `fetchRemoteConfig` doesn't disable the remote configuration options in Data Settings. > **Note:** Remote configuration by default > > SDK version 2.16.1 and higher enable `fetchRemoteConfig` by default. ### How it works When the SDK initializes with `fetchRemoteConfig` enabled, the SDK retrieves configuration settings from Amplitude's servers using the project's API key. These remote settings merge with any local configuration you defined on your site. After merging, the SDK completes its initialization along with any plugins using this combined configuration. Remote configuration doesn't impact the load time of pages on your site but may impact SDK initialization time. > **Note:** Configuration timeout > > If the configuration takes longer than 5 seconds to load from Amplitude's servers, the SDK falls back to the local configuration set during initialization. On the Settings page, each configuration category offers three options: - **Default**: Keeps the local configuration in the SDK as-is. Settings in the UI don't override it. - **On**: Overrides the local configuration and sets the category to true. All settings within the category (for example, Element Interactions) follow the configuration in the UI. - **Off**: Overrides the local configuration and sets the category to false. > **Note:** Disabling Session Tracking > > If you use Session Replay, ensure your Session Replay SDK version is 1.12.1 or above. Changes made through the UI take effect after 10 minutes. ### Element interactions When you enable Element Interactions, several options appear: | Option | Purpose | | --- | --- | | CSS Selector Allowlist | Selectors for elements that users interact with, such as links and form elements. If you have custom or non-standard elements that users interact with, specify them here. | | Action Click Allowlist | Amplitude tracks the elements in this list only when a user clicks them and the click results in a page or DOM change. | | Page URL Allowlist | Specify URLs or URL patterns (using glob or regular expression) on which Amplitude tracks element click and change events. | | Data Attribute Prefix | Specify a prefix for data attributes, for example `data-amp-track`. Amplitude saves the value of these attributes as event properties. | [Zoning Insights](https://amplitude.com/docs/zoning-insights) also uses element interaction data to analyze engagement within defined areas of your pages. To use Zoning Insights, enable element interactions (and optionally configure allowlists) here or in your [Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2#track-element-interactions) initialization. > **Tip:** Lower event volume > > These options can help you control event volume. By ignoring dead clicks, the Action Click Allowlist is the most efficient method to reduce volume while still tracking relevant interactions.