# 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](https://replicated-vendor-api.readme.io/reference/listappinstanceevents) 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: ```bash 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: ```shell 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: ```shell 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: ```bash 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: ```bash 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](/images/customers-download-csv.png) [View a larger version of this image](/images/customers-download-csv.png) 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](https://replicated-vendor-api.readme.io/reference/listappcustomerinstances) 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