Skip to main content

Export Customer and Instance Data

This topic describes how to download and export customer and instance data from the Replicated Vendor Portal.

Overview

While you can always consume customer and instance insight data directly in the Replicated Vendor Portal, the data is also available in a CSV format so that it can be imported into any other system, such as:

  • Customer Relationship Management (CRM) systems like Salesforce or Gainsight
  • Data warehouses like Redshift, Snowflake, or BigQuery
  • Business intelligence (BI) tools like Looker, Tableau, or PowerBI

By collecting and organizing this data wherever it is most visible and valuable, you can enable your team to make better decisions about where to focus efforts across product, sales, engineering, and customer success.

Bulk Export Instance Event Timeseries Data

You can use the Vendor API v3 /app/{app_id}/events endpoint to programatically access historical timeseries data containing instance level events, including any custom metrics that you have defined. For more information about the endpoint, see Get instance events in either JSON or CSV format in the Vendor API v3 documentation.

The /app/{app_id}/events endpoint returns data scoped to a given application identifier. It also allows filtering based on time periods, instances identifiers, customers identifers, and event types. You must provide at least one query parameter to scope the query in order to receive a response.

By bulk exporting this instance event data with the /app/{app_id}/events endpoint, you can:

  • Identify trends and potential problem areas
  • Demonstrate the impact, adoption, and usage of recent product features

Filter Bulk Data Exports

You can use the following types of filters to filter timeseries data for bulk export:

  • Filter by date:
    • Get instance events recorded at or before the query date. For example:
      curl -H "Authorization: $REPLICATED_API_TOKEN" \ 
      "https://api.replicated.com/vendor/v3/app/:appID/events?before=2023-10-15"
    • Get instance events recorded at or after the query date. For example:
      curl -H "Authorization: $REPLICATED_API_TOKEN" \ 
      "https://api.replicated.com/vendor/v3/app/:appID/events?after=2023-10-15"
    • Get instance events recorded within a range of dates [after, before]. For example:
      curl -H "Authorization: $REPLICATED_API_TOKEN" \ 
      "https://api.replicated.com/vendor/v3/app/:appID/events?after=2023-05-02&before=2023-10-15"
  • Filter by customer: Get instance events from one or more customers using a comma-separated list of customer IDs. For example:
    curl -H "Authorization: $REPLICATED_API_TOKEN" \ 
    "https://api.replicated.com/vendor/v3/app/:appID/events?customerIDs=1b13241,2Rjk2923481"
  • Filter by event type: Get instance events by event type using a comma-separated list of event types. For example:
    curl -H "Authorization: $REPLICATED_API_TOKEN" \ 
    "https://api.replicated.com/vendor/v3/app/:appID/events?eventTypes=numUsers,numProjects"
note

If any filter is passed for an object that does not exist, no warning is given. For example, if a customerIDs filter is passed for an ID that does not exist, or for an ID that the user does not have access to, then an empty array is returned.

Download Customer Instance Data CSVs

You can download customer and instance data from the Download CSV dropdown on the Customers page:

Download CSV button in the Customers page

View a larger version of this image

The Download CSV dropdown has the following options:

  • Customers: Includes details about your customers, such as the customer's channel assignment, license entitlements, expiration date, last active timestamp, and more.

  • (Recommended) Customers + Instances: Includes details about the instances assoicated with each customer, such as the Kubernetes distribution and cloud provider of the cluster where the instance is running, the most recent application instance status, if the instance is active or inactive, and more. The Customers + Instances data is a super set of the customer data, and is the recommended download for most use cases.

You can also export customer instance data as JSON using the Vendor API v3 customer_instances endpoint. For more information, see Get customer instance report in CSV or JSON format in the Vendor API v3 documentation.

Data Dictionary

The following table lists the data fields that can be included in the customers and instances CSV downloads, including the label, data type, and description.

LabelTypeDescription
customer_idstringCustomer identifier
customer_namestringThe customer name
customer_created_datetimestamptzThe date the license was created
customer_license_expiration_datetimestamptzThe expiration date of the license
customer_channel_idstringThe channel id the customer is assigned
customer_channel_namestringThe channel name the customer is assigned
customer_app_idstringApp identifier
customer_last_activetimestamptzThe date the customer was last active
customer_typestringOne of prod, trial, dev, or community
customer_statusstringThe current status of the customer
customer_is_airgap_enabledbooleanThe feature the customer has enabled - Airgap
customer_is_geoaxis_supportedbooleanThe feature the customer has enabled - GeoAxis
customer_is_gitops_supportedbooleanThe feature the customer has enabled - KOTS Auto-GitOps
customer_is_embedded_cluster_download_enabledbooleanThe feature the customer has enabled - Embedded Cluster
customer_is_identity_service_supportedbooleanThe feature the customer has enabled - Identity
customer_is_snapshot_supportedbooleanThe feature the customer has enabled - Snapshot
customer_has_entitlementsbooleanIndicates the presence or absence of entitlements and entitlment_* columns
customer_entitlement__*string/integer/booleanThe values of any custom license fields configured for the customer. For example, customer_entitlement__active-users.
customer_created_by_idstringThe ID of the actor that created this customer: user ID or a hashed value of a token.
customer_created_by_typestringThe type of the actor that created this customer: user, service-account, or service-account.
customer_created_by_descriptionstringThe description of the actor that created this customer. Includes username or token name depending on actor type.
customer_created_by_linkstringThe link to the actor that created this customer.
customer_created_by_timestamptimestamptzThe date the customer was created by this actor. When available, matches the value in the customer_created_date column
customer_updated_by_idstringThe ID of the actor that updated this customer: user ID or a hashed value of a token.
customer_updated_by_typestringThe type of the actor that updated this customer: user, service-account, or service-account.
customer_updated_by_descriptionstringThe description of the actor that updated this customer. Includes username or token name depending on actor type.
customer_updated_by_linkstringThe link to the actor that updated this customer.
customer_updated_by_timestamptimestamptzThe date the customer was updated by this actor.
instance_idstringInstance identifier
instance_is_activebooleanThe instance has pinged within the last 24 hours
instance_first_reported_attimestamptzThe timestamp of the first recorded check-in for the instance.
instance_last_reported_attimestamptzThe timestamp of the last recorded check-in for the instance.
instance_first_ready_attimestamptzThe timestamp of when the cluster was considered ready
instance_kots_versionstringThe version of KOTS or the Replicated SDK that the instance is running. The version is displayed as a Semantic Versioning compliant string.
instance_k8s_versionstringThe version of Kubernetes running in the cluster.
instance_is_airgapbooleanThe cluster is airgaped
instance_is_kurlbooleanThe instance is installed in a Replicated kURL cluster (embedded cluster)
instance_last_app_statusstringThe instance's last reported app status
instance_clientstringIndicates whether this instance is managed by KOTS or if it's a Helm CLI deployed instance using the SDK.
instance_kurl_node_count_totalintegerTotal number of nodes in the cluster. Applies only to kURL clusters.
instance_kurl_node_count_readyintegerNumber of nodes in the cluster that are in a healthy state and ready to run Pods. Applies only to kURL clusters.
instance_cloud_providerstringThe cloud provider where the instance is running. Cloud provider is determined by the IP address that makes the request.
instance_cloud_provider_regionstringThe cloud provider region where the instance is running. For example, us-central1-b
instance_app_versionstringThe current application version
instance_version_agestringThe age (in days) of the currently deployed release. This is relative to the latest available release on the channel.
instance_is_gitops_enabledbooleanReflects whether the end user has enabled KOTS Auto-GitOps for deployments in their environment
instance_gitops_providerstringIf KOTS Auto-GitOps is enabled, reflects the GitOps provider in use. For example, GitHub Enterprise.
instance_is_skip_preflightsbooleanIndicates whether an end user elected to skip preflight check warnings or errors
instance_preflight_statusstringThe last reported preflight check status for the instance
instance_k8s_distributionstringThe Kubernetes distribution of the cluster.
instance_has_custom_metricsbooleanIndicates the presence or absence of custom metrics and custom_metric__* columns
instance_custom_metrics_reported_attimestamptzTimestamp of latest custom_metric
custom_metric__*string/integer/booleanThe values of any custom metrics that have been sent by the instance. For example, custom_metric__active_users
instance_has_tagsbooleanIndicates the presence or absence of instance tags and instance_tag__* columns
instance_tag__*string/integer/booleanThe values of any instance tag that have been set by the vendor. For example, instance_tag__name