Authorization

CloudZero uses key-based authorization to secure API access. To authenticate your requests, include your API key in the Authorization header:

curl -X GET https://api.cloudzero.com/v2/insights \
  -H "Authorization: AbCd1234EfGh5678AbCd1234EfGh5678AbCd12"

Manage API keys

An organization can have multiple API keys. To view and manage all API keys for your organization, navigate to Settings > API Keys.

Only users with the necessary permissions can manage keys. Each key can be assigned one or more API scopes, which grant access to specific endpoints in the CloudZero API.

The API Keys page displays a list of keys with the following information:

• Name
• Description
• Created By: Email of the user who created the key
• Updated By: Email of the user who last modified the key
• Last Modified: Last update timestamp
• Last Accessed: Last usage timestamp, or "Not In Use" if the key has never been used
• Scopes: Number of granted API scopes
• Status: Enabled or Disabled

If your organization had an API key before multiple keys were supported, it is listed as Legacy API Key.

Create an API key

1. Navigate to Settings > API Keys.

2. Select Create API Key.

3. Enter a name for the key (minimum 3 characters, must be unique).

4. Enter a description (optional).

5. Under Scopes, select the API scopes to assign to the key. You must select at least one. Use the search bar or expand categories to find specific scopes. For information about each scope, refer to API key scopes.

6. Select Create API Key.
7. Copy the API key displayed. It will not be shown again.

8. Select Done.

New keys are Enabled by default.

Edit an API key

1. On the API Keys page, locate the key you want to modify.
2. Click the key name, or select the three-dot icon in the Actions column and select Edit.
3. Modify the Name, Description, or Scopes as needed. For information about each scope, refer to API key scopes.
4. Select Save Changes.

Enable or disable an API key

1. On the API Keys page, locate the key you want to modify.
2. Select the three-dot icon in the Actions column.
3. Select Enable or Disable.

The Status column updates to reflect the change.

Delete an API key

1. On the API Keys page, locate the key you want to delete.
2. Select the three-dot icon in the Actions column.
3. Select Delete.
4. Type the exact name of the API key to confirm deletion.
5. Select Delete.

API key scopes

CloudZero organizes API scopes into categories. Each scope grants access to specific API endpoints. When creating or editing an API key, select the scopes that match how the key will be used.

AI Telemetry

Ingest AI inference telemetry from supported platforms and collectors.

• AI Inference Events (ai-telemetry-ingest:ingest-ai-inference-event-v2)
• Bifrost (ai-telemetry-ingest:ingest-bifrost-v1) — guide
• Claude Code (ai-telemetry-ingest:ingest-claude-code-v1) — guide
• GitHub Copilot (OTLP traces path) (ai-telemetry-ingest:ingest-copilot-traces-v1)
• GitHub Copilot (ai-telemetry-ingest:ingest-copilot-v1)
• Custom AI Telemetry (ai-telemetry-ingest:ingest-cz-collector-v1)
• CloudZero macOS Collector (ai-telemetry-ingest:ingest-cz-telemetry-v1) — guide
• LiteLLM (ai-telemetry-ingest:ingest-litellm-v1) — guide
• OpenTelemetry GenAI (ai-telemetry-ingest:ingest-otel-genai-v1) — guide
• OpenTelemetry (OTLP) (ai-telemetry-ingest:ingest-otlp-v1)

Cost & Usage Data

Read cost, usage, dimension, and resource-tag data via the API.

• Read Cost Data (billing:read_costs) — reference
• Read Dimensions (billing:read_dimensions) — reference
• Read Resource Tags (billing:read_resource_tags)

Views

Create, read, update, and delete saved Views.

• Create Views (views:create_view)
• Delete Views (views:delete_view)
• Read a View (views:read_view) — reference
• List Views (views:read_views) — reference
• Update Views (views:update_view)

Budgets

Create, read, update, and delete budgets.

• Create Budgets (budgets:create_budget) — reference
• Delete Budgets (budgets:delete_budget) — reference
• Read a Budget (budgets:read_budget) — reference
• List Budgets (budgets:read_budgets) — reference
• Update Budgets (budgets:update_budget) — reference

Insights & Anomalies

Create, read, update, and comment on cost anomalies and insights.

• Create Insights (insights:create_insight) — reference
• Comment on Insights (insights:create_insight_comment) — reference
• Delete Insights (insights:delete_insight) — reference
• Read an Insight (insights:read_insight) — reference
• Read Insight Comments (insights:read_insight_comments) — reference
• List Insights (insights:read_insights) — reference
• Update Insights (insights:update_insight) — reference
• Update Insight Comments (insights:update_insight_comment) — reference

Optimization & Savings

Read and manage savings recommendations and their comments.

• Check Optimization Access (optimize:check)
• Comment on Recommendations (optimize:create_comments)
• Delete Recommendation Comments (optimize:delete_comment)
• Read Optimization Dimensions (optimize:get_available_dimensions)
• Read a Recommendation (optimize:get_recommendation)
• Read a Recommendation Type (optimize:get_recommendation_type)
• List Recommendation Comments (optimize:list_comments)
• List Recommendation Types (optimize:list_recommendation_types)
• List Recommendations (optimize:list_recommendations)
• Update Recommendation Comments (optimize:update_comment)
• Update Recommendation Types (optimize:update_recommendation_type)
• Update Recommendations (optimize:update_recommendations)

Cost Allocation (CostFormation)

Manage CostFormation definitions, namespaces, and publish jobs for cost allocation.

• Cancel Publish Jobs (costformation:cancel_publish_job)
• Create Definitions (costformation:create_definition_async)
• Create Definition Versions (costformation:create_definition_version) — reference
• Create Namespaces (costformation:create_namespace)
• Create Namespaced Definitions (costformation:create_namespaced_definition_async)
• Delete Namespaces (costformation:delete_namespace)
• List Publish Jobs (costformation:list_publish_jobs)
• List Namespaces (costformation:read_all_namespaces)
• Read a Definition Version (costformation:read_definition_version) — reference
• List Definition Versions (costformation:read_definition_versions) — reference
• Read a Namespace (costformation:read_namespace)
• Read a Publish Job (costformation:read_publish_job)
• Update Namespaces (costformation:update_namespace)

Kubernetes Agent

Send-only permissions for the CloudZero Kubernetes agent to upload container metrics.

• Abandon Metric Uploads (container-metrics_v1:abandon) — guide
• Read Metric Upload Status (container-metrics_v1:get-status) — guide
• Legacy Metric Upload (container-metrics_v1:legacy) — guide
• Upload Container Metrics (container-metrics_v1:upload) — guide

Kubernetes Clusters

Read and manage CloudZero Kubernetes cluster configuration. Not required by the Kubernetes agent to send data.

• List Clusters (container:get-clusters)
• Update Clusters (container:update-cluster)

Cloud & Billing Connections

Create and manage cloud billing connections, including AnyCost Stream connections.

• Create Billing Connections (connections:create_billing) — reference
• Send AnyCost Billing Data (connections:create_billing_anycost_billing_drop) — reference
• Validate AnyCost Billing Data (connections:create_billing_anycost_validate_billing_drop) — reference
• Delete Billing Connections (connections:delete_billing) — reference
• Read a Billing Connection (connections:read_billing) — reference
• List AnyCost Billing Drops (connections:read_billing_anycost_billing_drops) — reference
• List Monthly AnyCost Billing Drops (connections:read_billing_anycost_billing_drops_month) — reference
• List Billing Connections (connections:read_billings) — reference
• Update Billing Connections (connections:update_billing) — reference

AI Hub (MCP)

Access the CloudZero AI Hub over MCP for AI assistants and agents.

• AI Hub (MCP) Access (ai-hub:mcp) — guide

Telemetry & Usage Streams

Create and manage unit-cost telemetry streams and submit telemetry records.

• Send Usage Events (events_v1:create_event) — reference
• Create Telemetry Streams (unit-cost_v1:create_telemetry_stream)
• Delete Telemetry Streams (unit-cost_v1:delete_telemetry_stream) — reference
• Manage Telemetry Records (unit-cost_v1:manage_telemetry_records) — post, sum, replace, and delete records for both allocation telemetry and unit cost metric telemetry streams
• Read Telemetry (unit-cost_v1:read_telemetry) — read telemetry stream records and metrics records

Roles & Access Control

Manage CloudZero roles and read permission sets via the API.

• Create Roles (access-control:create_role)
• Delete Roles (access-control:delete_role)
• Read Permission Sets (access-control:read_permission_sets)
• Read a Role (access-control:read_role)
• List Roles (access-control:read_roles)
• Update Roles (access-control:update_role)