1 files changed, 160 insertions, 0 deletions
diff --git a/doc/api/usage_data.md b/doc/api/usage_data.md
new file mode 100644
index 00000000000..024caa96565
--- /dev/null
+++ b/doc/api/usage_data.md
@@ -0,0 +1,160 @@
+---
+stage: Growth
+group: Product Intelligence
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+type: reference, api
+---
+
+# Usage Data API **(FREE SELF)**
+
+The Usage Data API is associated with [Usage Ping](../development/usage_ping/index.md).
+
+## Export metric definitions as a single YAML file
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57270) in GitLab 13.11.
+
+Export all metric definitions as a single YAML file, similar to the [Metrics Dictionary](../development/usage_ping/dictionary.md), for easier importing.
+
+```plaintext
+GET /usage_data/metric_definitions
+```
+
+Example request:
+
+```shell
+curl "https://gitlab.example.com/api/v4/usage_data/metric_definitions"
+```
+
+Example response:
+
+```yaml
+---
+- key_path: redis_hll_counters.search.i_search_paid_monthly
+  description: Calculated unique users to perform a search with a paid license enabled
+    by month
+  product_section: enablement
+  product_stage: enablement
+  product_group: group::global search
+  product_category: global_search
+  value_type: number
+  status: data_available
+  time_frame: 28d
+  data_source: redis_hll
+  distribution:
+  - ee
+  tier:
+  - premium
+  - ultimate
+...
+```
+
+## Export Usage Ping SQL queries
+
+This action is available only for the GitLab instance [Administrator](../user/permissions.md) users.
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57016) in GitLab 13.11.
+> - [Deployed behind a feature flag](../user/feature_flags.md), disabled by default.
+
+Return all of the raw SQL queries used to compute Usage Ping.
+
+```plaintext
+GET /usage_data/queries
+```
+
+Example request:
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/usage_data/queries"
+```
+
+Example response:
+
+```json
+{
+  "recorded_at": "2021-03-23T06:31:21.267Z",
+  "uuid": null,
+  "hostname": "localhost",
+  "version": "13.11.0-pre",
+  "installation_type": "gitlab-development-kit",
+  "active_user_count": "SELECT COUNT(\"users\".\"id\") FROM \"users\" WHERE (\"users\".\"state\" IN ('active')) AND (\"users\".\"user_type\" IS NULL OR \"users\".\"user_type\" IN (NULL, 6, 4))",
+  "edition": "EE",
+  "license_md5": "c701acc03844c45366dd175ef7a4e19c",
+  "license_id": null,
+  "historical_max_users": 0,
+  "licensee": {
+    "Name": "John Doe1"
+  },
+  "license_user_count": null,
+  "license_starts_at": "1970-01-01",
+  "license_expires_at": "2022-02-23",
+  "license_plan": "starter",
+  "license_add_ons": {
+    "GitLab_FileLocks": 1,
+    "GitLab_Auditor_User": 1
+  },
+  "license_trial": null,
+  "license_subscription_id": "0000",
+  "license": {},
+  "settings": {
+    "ldap_encrypted_secrets_enabled": false,
+    "operating_system": "mac_os_x-11.2.2"
+  },
+  "counts": {
+    "assignee_lists": "SELECT COUNT(\"lists\".\"id\") FROM \"lists\" WHERE \"lists\".\"list_type\" = 3",
+    "boards": "SELECT COUNT(\"boards\".\"id\") FROM \"boards\"",
+    "ci_builds": "SELECT COUNT(\"ci_builds\".\"id\") FROM \"ci_builds\" WHERE \"ci_builds\".\"type\" = 'Ci::Build'",
+    "ci_internal_pipelines": "SELECT COUNT(\"ci_pipelines\".\"id\") FROM \"ci_pipelines\" WHERE (\"ci_pipelines\".\"source\" IN (1, 2, 3, 4, 5, 7, 8, 9, 10, 11, 12, 13) OR \"ci_pipelines\".\"source\" IS NULL)",
+    "ci_external_pipelines": "SELECT COUNT(\"ci_pipelines\".\"id\") FROM \"ci_pipelines\" WHERE \"ci_pipelines\".\"source\" = 6",
+    "ci_pipeline_config_auto_devops": "SELECT COUNT(\"ci_pipelines\".\"id\") FROM \"ci_pipelines\" WHERE \"ci_pipelines\".\"config_source\" = 2",
+    "ci_pipeline_config_repository": "SELECT COUNT(\"ci_pipelines\".\"id\") FROM \"ci_pipelines\" WHERE \"ci_pipelines\".\"config_source\" = 1",
+    "ci_runners": "SELECT COUNT(\"ci_runners\".\"id\") FROM \"ci_runners\"",
+...
+```
+
+## UsageDataNonSqlMetrics API
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/57050) in GitLab 13.11.
+> - [Deployed behind a feature flag](../user/feature_flags.md), disabled by default.
+
+Return all non-SQL metrics data used in the usage ping.
+
+Example request:
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/usage_data/non_sql_metrics"
+```
+
+Sample response:
+
+```json
+{
+  "recorded_at": "2021-03-26T07:04:03.724Z",
+  "uuid": null,
+  "hostname": "localhost",
+  "version": "13.11.0-pre",
+  "installation_type": "gitlab-development-kit",
+  "active_user_count": -3,
+  "edition": "EE",
+  "license_md5": "bb8cd0d8a6d9569ff3f70b8927a1f949",
+  "license_id": null,
+  "historical_max_users": 0,
+  "licensee": {
+    "Name": "John Doe1"
+  },
+  "license_user_count": null,
+  "license_starts_at": "1970-01-01",
+  "license_expires_at": "2022-02-26",
+  "license_plan": "starter",
+  "license_add_ons": {
+    "GitLab_FileLocks": 1,
+    "GitLab_Auditor_User": 1
+  },
+  "license_trial": null,
+  "license_subscription_id": "0000",
+  "license": {},
+  "settings": {
+    "ldap_encrypted_secrets_enabled": false,
+    "operating_system": "mac_os_x-11.2.2"
+  },
+...
+```