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.

Cost & Usage Data

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

• billing:read_costs: Get billing costs
• billing:read_dimensions: Get billing dimensions
• billing:read_resource_tags: Read resource tag data

Views

Create, read, update, and delete saved Views.

• views:create_view: Create a View
• views:delete_view: Delete a View
• views:read_view: Get one View
• views:read_views: Get a list of Views
• views:update_view: Update a View

Budgets

Create, read, update, and delete budgets.

• budgets:create_budget: Create a budget
• budgets:delete_budget: Delete a budget
• budgets:read_budget: Get one budget
• budgets:read_budgets: Get a list of budgets
• budgets:update_budget: Update a budget

Insights & Anomalies

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

• insights:create_insight: Create an insight
• insights:create_insight_comment: Create a comment for an insight
• insights:delete_insight: Delete an insight
• insights:read_insight: Get one insight
• insights:read_insight_comments: Get a list of comments for an insight
• insights:read_insights: Get a list of insights
• insights:update_insight: Update an insight
• insights:update_insight_comment: Update a comment for an insight

Optimization & Savings

Read and manage savings recommendations and their comments.

• optimize:check: Check optimization status
• optimize:create_comments: Create recommendation comments
• optimize:delete_comment: Delete a recommendation comment
• optimize:get_available_dimensions: Get available dimensions for optimization
• optimize:get_recommendation: Get one recommendation
• optimize:get_recommendation_type: Get one recommendation type
• optimize:list_comments: List recommendation comments
• optimize:list_recommendation_types: List recommendation types
• optimize:list_recommendations: List recommendations
• optimize:update_comment: Update a recommendation comment
• optimize:update_recommendation_type: Update a recommendation type
• optimize:update_recommendations: Update recommendations

Cost Allocation (CostFormation)

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

• costformation:cancel_publish_job: Cancel a publish job
• costformation:create_definition_async: Create a definition asynchronously
• costformation:create_definition_version: Create a CostFormation definition version
• costformation:create_namespace: Create a namespace
• costformation:create_namespaced_definition_async: Create a namespaced definition asynchronously
• costformation:delete_namespace: Delete a namespace
• costformation:list_publish_jobs: List publish jobs
• costformation:read_all_namespaces: Read all namespaces
• costformation:read_definition_version: Get one CostFormation definition version
• costformation:read_definition_versions: Get a list of CostFormation definition versions
• costformation:read_namespace: Read one namespace
• costformation:read_publish_job: Read one publish job
• costformation:update_namespace: Update a namespace

Kubernetes

Send Kubernetes container metrics and manage cluster details.

• container-metrics_v1:abandon: Required scope for the CloudZero Agent for Kubernetes
• container-metrics_v1:get-status: Required scope for the CloudZero Agent for Kubernetes
• container-metrics_v1:legacy: Required scope for the CloudZero Agent for Kubernetes
• container-metrics_v1:upload: Required scope for the CloudZero Agent for Kubernetes
• container:get-clusters: Get Kubernetes cluster details
• container:update-cluster: Update Kubernetes cluster details

Cloud & Billing Connections

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

• connections:create_billing: Create a billing connection
• connections:create_billing_anycost_billing_drop: Create an AnyCost Stream connection billing drop
• connections:create_billing_anycost_validate_billing_drop: Validate an AnyCost Stream connection billing drop
• connections:delete_billing: Delete a billing connection
• connections:read_billing: Get one billing connection
• connections:read_billing_anycost_billing_drops: Get a list of billing drops for an AnyCost Stream connection
• connections:read_billing_anycost_billing_drops_month: Get contents of one billing drop for an AnyCost Stream connection
• connections:read_billings: Get a list of billing connections
• connections:update_billing: Update a billing connection

AI Telemetry

Ingest AI inference telemetry from supported platforms and collectors.

• ai-telemetry-ingest:ingest-ai-inference-event-v2: Ingest AI inference events (v2)
• ai-telemetry-ingest:ingest-bifrost-v1: Ingest telemetry from Bifrost
• ai-telemetry-ingest:ingest-claude-code-v1: Ingest telemetry from Claude Code
• ai-telemetry-ingest:ingest-cz-collector-v1: Ingest telemetry from the CloudZero macOS Collector
• ai-telemetry-ingest:ingest-cz-telemetry-v1: Ingest CloudZero telemetry (v1)
• ai-telemetry-ingest:ingest-litellm-v1: Ingest telemetry from LiteLLM
• ai-telemetry-ingest:ingest-otel-genai-v1: Ingest telemetry via OpenTelemetry
• ai-telemetry-ingest:ingest-otlp-v1: Ingest telemetry via OTLP (v1)

AI Hub (MCP)

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

• ai-hub:mcp: Connect to the AI Hub MCP endpoint

Telemetry & Usage Streams

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

• events_v1:create_event: Post an event
• unit-cost_v1:create_telemetry_stream: Create a telemetry stream
• unit-cost_v1:delete_telemetry_stream: Delete a telemetry stream
• unit-cost_v1:manage_telemetry_records: Manage telemetry records for allocation and unit cost metric streams. Grants access to post, sum, replace, and delete records for both allocation telemetry and unit cost metric telemetry streams.
• unit-cost_v1:read_telemetry: Get telemetry stream records and Get metrics records

Roles & Access Control

Manage CloudZero roles and read permission sets via the API.

• access-control:create_role: Create a role
• access-control:delete_role: Delete a role
• access-control:read_permission_sets: Read permission sets
• access-control:read_role: Read one role
• access-control:read_roles: Read all roles
• access-control:update_role: Update a role