From 087fba0df168c32d0221ab76a77ad89db1952602 Mon Sep 17 00:00:00 2001 From: Christopher Tauchen Date: Tue, 7 Jul 2026 16:30:08 +0100 Subject: [PATCH 1/4] Add Usage API doc for Calico Cloud Documents creating a read-only API key in the web console and using it to call the Usage API for vCPU usage data. Adds the page to the operations sidebar after usage-metrics. --- calico-cloud/operations/usage-api.mdx | 45 +++++++++++++++++++++++++++ sidebars-calico-cloud.js | 1 + 2 files changed, 46 insertions(+) create mode 100644 calico-cloud/operations/usage-api.mdx diff --git a/calico-cloud/operations/usage-api.mdx b/calico-cloud/operations/usage-api.mdx new file mode 100644 index 0000000000..c3fff1198f --- /dev/null +++ b/calico-cloud/operations/usage-api.mdx @@ -0,0 +1,45 @@ +--- +description: Create a read-only API key in the Calico Cloud web console and use it to call the Usage API to retrieve vCPU usage data programmatically. +--- + +import IconUser from '/img/icons/user-icon.svg'; + +# Access usage data programmatically + +You can create a read-only API key in the web console and use it to call the $[prodname] Usage API. +The API returns the same vCPU usage and managed cluster data shown on the [Usage Metrics](usage-metrics.mdx) page, so you can pull it into your own capacity planning, FinOps, and license-compliance workflows instead of exporting it by hand. +API keys are read-only and scoped to your organization. + +## Prerequisites + +* You are signed in to the web console as a user with the **Admin** and **Usage Metrics** roles, or the **Owner role**. + +## Create an API key for usage metrics + +1. In the web console, click the user icon **> Settings**. +1. Under the **API Keys** tab, click **Generate new key**. +1. Enter a description, choose a validity period, and then click **Create**. +1. Copy or download the generated key and store it in a secure location. + + :::important + + The key is shown only once, at creation. You cannot retrieve it again after you close the dialog. + + ::: + +## Call the Usage API + +The web console generates ready-to-run commands for each API key, so you don't need to construct requests by hand. + +1. On the **API Keys** tab, locate your key and click **Actions > Generate commands**. +1. Select the command for the data you want: + * **Summary** — per-project vCPU totals and usage over time, across all projects. + * **Managed clusters** — per-cluster usage rows, with optional project filtering and CSV output. + * **Contracts** — your organization's contracts, including start and end dates, vCPU hours, package, and add-ons. +1. Copy the generated command. Each command is available as curl, Python, and JavaScript. +1. In the command, replace `` with your API key, and set any query parameters, such as `startTime`, `endTime`, and `granularity`, for your query. +1. Run the command. A successful call returns an HTTP `200` response with your usage data in JSON. + +## Additional information + +* [Usage metrics](usage-metrics.mdx) diff --git a/sidebars-calico-cloud.js b/sidebars-calico-cloud.js index df1ec860cd..17c81b4fdd 100644 --- a/sidebars-calico-cloud.js +++ b/sidebars-calico-cloud.js @@ -394,6 +394,7 @@ module.exports = { 'operations/cluster-management', 'operations/disconnect', 'operations/usage-metrics', + 'operations/usage-api', 'operations/comms/index', { type: 'category', From 9d4e352e74e089fb89df44777ee15cc62d9f750b Mon Sep 17 00:00:00 2001 From: Christopher Tauchen Date: Tue, 7 Jul 2026 16:41:01 +0100 Subject: [PATCH 2/4] Address review: fix Owner role bolding and Usage Metrics link casing --- calico-cloud/operations/usage-api.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/calico-cloud/operations/usage-api.mdx b/calico-cloud/operations/usage-api.mdx index c3fff1198f..ce9eba058b 100644 --- a/calico-cloud/operations/usage-api.mdx +++ b/calico-cloud/operations/usage-api.mdx @@ -12,7 +12,7 @@ API keys are read-only and scoped to your organization. ## Prerequisites -* You are signed in to the web console as a user with the **Admin** and **Usage Metrics** roles, or the **Owner role**. +* You are signed in to the web console as a user with the **Admin** and **Usage Metrics** roles, or with the **Owner** role. ## Create an API key for usage metrics @@ -42,4 +42,4 @@ The web console generates ready-to-run commands for each API key, so you don't n ## Additional information -* [Usage metrics](usage-metrics.mdx) +* [Usage Metrics](usage-metrics.mdx) From 1ca5b08228952c2e856af80ed90f9fa843f7c914 Mon Sep 17 00:00:00 2001 From: Christopher Tauchen Date: Tue, 7 Jul 2026 16:46:43 +0100 Subject: [PATCH 3/4] Correct command language: console generates curl only --- calico-cloud/operations/usage-api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/calico-cloud/operations/usage-api.mdx b/calico-cloud/operations/usage-api.mdx index ce9eba058b..a979f3ea65 100644 --- a/calico-cloud/operations/usage-api.mdx +++ b/calico-cloud/operations/usage-api.mdx @@ -36,7 +36,7 @@ The web console generates ready-to-run commands for each API key, so you don't n * **Summary** — per-project vCPU totals and usage over time, across all projects. * **Managed clusters** — per-cluster usage rows, with optional project filtering and CSV output. * **Contracts** — your organization's contracts, including start and end dates, vCPU hours, package, and add-ons. -1. Copy the generated command. Each command is available as curl, Python, and JavaScript. +1. Copy the generated `curl` command. 1. In the command, replace `` with your API key, and set any query parameters, such as `startTime`, `endTime`, and `granularity`, for your query. 1. Run the command. A successful call returns an HTTP `200` response with your usage data in JSON. From 66159842d26a9182d98f19a2f53b12889ada3acc Mon Sep 17 00:00:00 2001 From: Christopher Tauchen Date: Tue, 7 Jul 2026 16:47:29 +0100 Subject: [PATCH 4/4] Drop tool-specific wording and ready-to-run intro line --- calico-cloud/operations/usage-api.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/calico-cloud/operations/usage-api.mdx b/calico-cloud/operations/usage-api.mdx index a979f3ea65..a606efcc7d 100644 --- a/calico-cloud/operations/usage-api.mdx +++ b/calico-cloud/operations/usage-api.mdx @@ -29,14 +29,12 @@ API keys are read-only and scoped to your organization. ## Call the Usage API -The web console generates ready-to-run commands for each API key, so you don't need to construct requests by hand. - 1. On the **API Keys** tab, locate your key and click **Actions > Generate commands**. 1. Select the command for the data you want: * **Summary** — per-project vCPU totals and usage over time, across all projects. * **Managed clusters** — per-cluster usage rows, with optional project filtering and CSV output. * **Contracts** — your organization's contracts, including start and end dates, vCPU hours, package, and add-ons. -1. Copy the generated `curl` command. +1. Copy the generated command. 1. In the command, replace `` with your API key, and set any query parameters, such as `startTime`, `endTime`, and `granularity`, for your query. 1. Run the command. A successful call returns an HTTP `200` response with your usage data in JSON.