Skip to main content
Gainsight Inc.

Gainsight PX Data Loader

A useful utility script to load or update Gainsight PX user, account and custom event data.

  • Generate A REST API key (see below for details) from an active PX subscription.


  • An input file containing either user, account or custom event data in CSV format is used to update and optionally insert the corresponding records into Gainsight PX. If any errors are encountered during the process, they are logged to the screen and the process continues.
  • Mac or Windows machine that is able to run python scripts. 

Use Cases for Using PX Data Loader

  • Seeding User and Account attributes such as 'sign-up date' that may impact metrics like 'New Users' or user onboarding engagements driven by user sign-up.
  • Update tracked user preferences 
  • Seeding recent custom event data of key user actions (limited by size/rate)


Download the script to your local computer using this link: gainsight-px-data-loader

Depends on python (> v3.x) being installed locally and being present in the path. Most Macs already have Python installed.

There is an install script that will perform the remaining steps on OSX/Mac, download here:

Run install script:

chmod u+x ./
bash ./


For Windows, perform the following steps:

  1. Download the script to your local computer from here: gainsight-px-data-loader
  2. Install Python (> v3.x). For more information, refer to this article.
  3. Add the following to the PATH in the environment variable on the Windows machine:
  1. Depending on the version of Python installed, install the libraries using pip:
Python: python -m pip install requests pytz python.dateutil
Python 3: python3 -m pip3 install requests pytz python.dateutil


gainsight-px-data-loader [--insertMissing] [--verbose] [--dryRun] [-n startRow] [-l lastRow] config.json [USER|ACCOUNT|CUSTOM_EVENT|USER_PREFERENCES] input.csv

  • Data type (second argument) should either be USER, ACCOUNT, CUSTOM_EVENT or USER_PREFERENCES
  • If insertMissing is specified, will insert missing records. Default behavior is to update records that are found
  • insertMissing does not apply to custom events, or user preferences
  • If verbose is specified, each operation is logged to stdout
  • If dryRun is specified, no data is changed, inputs are parsed
  • The -n and -l flags can be used to only process a portion of the file. For instance, -n 7 would start the processing on the seventh line of the file.

Mac Example For Updating User Data:

./gainsight-px-data-loader config.json USER users.csv

Windows Example For Updating User Data:

python gainsight-px-data-loader config.json USER users.csv

User CSV File Example:

Account ID,Account Name,User ID,Job Title,Email,First Name,Last Name,Sign-Up Date UTC-MS,Role,Phone,Time Zone
3,HideMyStuff,tinylion155,BigData Engineer,,Corey,Thomas,2020-11-29T17:05:23,Admin,(814)-853-6602,GMT+7

CSV details:

* Date values are specified as ISO 8601 strings, either "YYYY-MM-DD" or "YYYY-MM-DDTHH:mm:ss"

* String values can optionally be surrounded with double quotes to escape commas

Custom Event CSV File Example:

Account ID,User ID,Event Name,Event Date UTC-MS,Source,Terms,Category
3,tinylion155,Search,2020-11-28,CSV,Example of search terms,Enterprise

Mac Example For Updating Custom Event Data:

./gainsight-px-data-loader  --verbose config.json CUSTOM_EVENT custom-events.csv

Download Examples

Config File Example:

    "productKey": "AP-XXXXXXXXXXXX-2",
    "timezone": "America/Los_Angeles",
    "fieldMapping": {
        "USER": {
            "identifyId": "User ID",
            "title": "Job Title",
            "email": "Email",
            "firstName": "First Name",
            "lastName": "Last Name",
            "signUpDate": "Sign-Up Date UTC-MS",
            "role": "Role",
            "phone": "Phone",
            "location.timeZone": "Time Zone"

        "ACCOUNT": {
            "id": "Account ID",
            "name": "Account Name"
        "CUSTOM_EVENT": {
            "identifyId": "User ID",
            "accountId": "Account ID",
            "eventName": "Event Name",
            "date": "Event Date UTC-MS",
            "attributes.Source": "Source",
            "attributes.Terms": "Terms",
            "attributes.Category": "Category"
            "identifyId": "User_Id",
            "trackUsage": "track_usage",
            "productUpdates": "product_updates",
            "guidedTours": "guided_tours",
            "surveys": "surveys",
            "onboardingBot": "onboarding_bot"
  • apiKey: From the Gainsight PX Settings/REST API/New API Key screen
  • productKey: From the Gainsight PX Settings/Products screen (if you need to set more than one product key on a user or account, pass as an array: ['key1','key2'])
  • timezone: Optional setting, use if date or time values in the file are in a timezone other than UTC.
    Valid values:
  • fieldMapping:
    • Specifies which Gainsight PX fields will be used as targets for the data in the input file.
    • The first field name (the key of the fieldMapping map) is the Gainsight PX name, the second (the value) is the name in the CSV input file.
    • The unique identifier field is required for both users, custom events (identifyId) and account (id)
    • To specify nested fields, use periods as separators (see location and customAttributes examples above)
    • Custom events: eventName and attributes correspond to the name and attributes usually passed in the Javascript API

Migrating Historical Data

If you're interested in migrating historical data from Amplitude, MixPanel, Google analytics, Pendo or other analytics solutions please reach out to your account manager for a price quote.

When reaching out please provide:

  • Total number of users and events
  • Event types: page views, clicks, custom events, super properties
  • Event time range

The historical data should exist in JSON or CSV files. 

  • Was this article helpful?