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"
- Get instance events recorded at or before the query date. For example:
- 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"
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:
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.
| Label | Type | Description |
|---|---|---|
| customer_id | string | Customer identifier |
| customer_name | string | The customer name |
| customer_created_date | timestamptz | The date the license was created |
| customer_license_expiration_date | timestamptz | The expiration date of the license |
| customer_channel_id | string | The channel id the customer is assigned |
| customer_channel_name | string | The channel name the customer is assigned |
| customer_app_id | string | App identifier |
| customer_last_active | timestamptz | The date the customer was last active |
| customer_type | string | One of prod, trial, dev, or community |
| customer_status | string | The current status of the customer |
| customer_is_airgap_enabled | boolean | The feature the customer has enabled - Airgap |
| customer_is_geoaxis_supported | boolean | The feature the customer has enabled - GeoAxis |
| customer_is_gitops_supported | boolean | The feature the customer has enabled - KOTS Auto-GitOps |
| customer_is_embedded_cluster_download_enabled | boolean | The feature the customer has enabled - Embedded Cluster |
| customer_is_identity_service_supported | boolean | The feature the customer has enabled - Identity |
| customer_is_snapshot_supported | boolean | The feature the customer has enabled - Snapshot |
| customer_has_entitlements | boolean | Indicates the presence or absence of entitlements and entitlment_* columns |
| customer_entitlement__* | string/integer/boolean | The values of any custom license fields configured for the customer. For example, customer_entitlement__active-users. |
| customer_created_by_id | string | The ID of the actor that created this customer: user ID or a hashed value of a token. |
| customer_created_by_type | string | The type of the actor that created this customer: user, service-account, or service-account. |
| customer_created_by_description | string | The description of the actor that created this customer. Includes username or token name depending on actor type. |
| customer_created_by_link | string | The link to the actor that created this customer. |
| customer_created_by_timestamp | timestamptz | The date the customer was created by this actor. When available, matches the value in the customer_created_date column |
| customer_updated_by_id | string | The ID of the actor that updated this customer: user ID or a hashed value of a token. |
| customer_updated_by_type | string | The type of the actor that updated this customer: user, service-account, or service-account. |
| customer_updated_by_description | string | The description of the actor that updated this customer. Includes username or token name depending on actor type. |
| customer_updated_by_link | string | The link to the actor that updated this customer. |
| customer_updated_by_timestamp | timestamptz | The date the customer was updated by this actor. |
| instance_id | string | Instance identifier |
| instance_is_active | boolean | The instance has pinged within the last 24 hours |
| instance_first_reported_at | timestamptz | The timestamp of the first recorded check-in for the instance. |
| instance_last_reported_at | timestamptz | The timestamp of the last recorded check-in for the instance. |
| instance_first_ready_at | timestamptz | The timestamp of when the cluster was considered ready |
| instance_kots_version | string | The version of KOTS or the Replicated SDK that the instance is running. The version is displayed as a Semantic Versioning compliant string. |
| instance_k8s_version | string | The version of Kubernetes running in the cluster. |
| instance_is_airgap | boolean | The cluster is airgaped |
| instance_is_kurl | boolean | The instance is installed in a Replicated kURL cluster (embedded cluster) |
| instance_last_app_status | string | The instance's last reported app status |
| instance_client | string | Indicates whether this instance is managed by KOTS or if it's a Helm CLI deployed instance using the SDK. |
| instance_kurl_node_count_total | integer | Total number of nodes in the cluster. Applies only to kURL clusters. |
| instance_kurl_node_count_ready | integer | Number of nodes in the cluster that are in a healthy state and ready to run Pods. Applies only to kURL clusters. |
| instance_cloud_provider | string | The cloud provider where the instance is running. Cloud provider is determined by the IP address that makes the request. |
| instance_cloud_provider_region | string | The cloud provider region where the instance is running. For example, us-central1-b |
| instance_app_version | string | The current application version |
| instance_version_age | string | The age (in days) of the currently deployed release. This is relative to the latest available release on the channel. |
| instance_is_gitops_enabled | boolean | Reflects whether the end user has enabled KOTS Auto-GitOps for deployments in their environment |
| instance_gitops_provider | string | If KOTS Auto-GitOps is enabled, reflects the GitOps provider in use. For example, GitHub Enterprise. |
| instance_is_skip_preflights | boolean | Indicates whether an end user elected to skip preflight check warnings or errors |
| instance_preflight_status | string | The last reported preflight check status for the instance |
| instance_k8s_distribution | string | The Kubernetes distribution of the cluster. |
| instance_has_custom_metrics | boolean | Indicates the presence or absence of custom metrics and custom_metric__* columns |
| instance_custom_metrics_reported_at | timestamptz | Timestamp of latest custom_metric |
| custom_metric__* | string/integer/boolean | The values of any custom metrics that have been sent by the instance. For example, custom_metric__active_users |
| instance_has_tags | boolean | Indicates the presence or absence of instance tags and instance_tag__* columns |
| instance_tag__* | string/integer/boolean | The values of any instance tag that have been set by the vendor. For example, instance_tag__name |