DOCS-2955: Add Usage API doc for Calico Cloud

calico-cloud/operations/usage-api.mdx

@@ -0,0 +1,43 @@
+---
+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 with the **Owner** role.
+
+## Create an API key for usage metrics
+
+1. In the web console, click the user icon <IconUser width="20"/> **> 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
+
+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.
+1. In the command, replace `<your-secret>` 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)

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',