---
updatedAt: 2026-10-13T13:30:51.000Z
agentTools:
  projectIndex: https://docs.cloudzero.com/llms.txt
---

# MCP Server Reference

Use the CloudZero MCP server to query cost data, retrieve optimization recommendations, explore Dimensions, access telemetry, manage organization context, and log and manage [Insights](/docs/insights). These are the same tools that power AI Hub. In the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), tools are functions that an MCP server exposes for AI clients to call.

This reference documents each tool, its parameters, and which [skills](/docs/ai-skills) use it. Skills are guided analysis workflows available through the CloudZero Plugin that combine multiple tools into structured investigations. For setup instructions, see [Set Up AI Hub](/docs/ai-getting-started).

## Authentication

The MCP server supports three authentication methods:

* **CloudZero account (OAuth):** On first use, a browser window opens to sign in. Sessions persist across AI tool restarts. See [Set Up AI Hub](/docs/ai-getting-started) for setup.
* **API key:** Pass an `X-Api-Key` header for automation, CI/CD, or clients that do not support OAuth. API key usage is metered with a [daily quota](#usage-quotas). See [API Key Authentication](/docs/ai-mcp-api-key-auth) for setup.
* **OAuth client:** Register a client ID and client secret for an enterprise agent platform that cannot register itself with the MCP server. Users still sign in individually, so data access controls and permission sets apply. See [Connect an Agent Platform with MCP OAuth Clients](/docs/ai-mcp-oauth-clients) for setup.

## Access and permissions

The MCP server enforces the same roles and permissions as the CloudZero application.

### Data access controls

Your role's data access filters apply to all cost queries. If your role restricts visibility to specific Dimensions (for example, only `Team = Engineering`), the MCP server returns only matching data. API key users have full access to all cost data in the organization.

The [Insights](#insights) tools (`create_insight`, `update_insight`, and `delete_insight`) require full data access. If your role has any data access filters, these tools return an error stating that they require full data access.

See [Users and Permissions](/docs/users-and-permissions) for details.

### Permission sets

Some tools require specific permission sets on your role. If the required permission set is not granted, the tool returns an authorization error.

The **MCP Settings** permission sets control who can manage [OAuth clients](/docs/ai-mcp-oauth-clients). They grant no access to the tools below.

| Tool                     | Required permission set                                      | Required scope                               |
| ------------------------ | ------------------------------------------------------------ | -------------------------------------------- |
| `create_insight`         | Insights / Anomalies (Create/Modify Insights / Anomalies)    | `insights:create-insight`                    |
| `delete_insight`         | Insights / Anomalies (Delete Insights / Anomalies)           | `insights:delete-insight`                    |
| `download_costformation` | Dimension Definition Settings (View Dimension Definitions)   | `cost-contexts:get-definition-download-link` |
| `get_container_usage`    | Kubernetes Cluster Details (View Kubernetes Cluster Details) | `container:get_usage`                        |
| `get_costformation_vers` | Dimension Definition Settings (View Dimension Definitions)   | `cost-contexts:get-contexts`                 |
| `get_optimize_recs`      | Optimize (View Recommendations)                              | `insights-workflow:list-recommendations`     |
| `get_realized_savings`   | Optimize (View Recommendations)                              | `insights-workflow:get-realized-savings`     |
| `get_resource_metadata`  | Resource Provider (View resource provider)                   | `resource-provider:get-resource-by-czrn`     |
| `get_telemetry_data`     | Telemetry Stream Settings (View Telemetry Streams)           | `unit-cost:get-records`                      |
| `get_telemetry_streams`  | Telemetry Stream Settings (View Telemetry Streams)           | `unit-cost:streams`                          |
| `set_generated_context`  | Organization Administration (Modify Organization Settings)   | `czca-server:set-org-context`                |
| `set_org_context`        | Organization Administration (Modify Organization Settings)   | `czca-server:set-org-context`                |
| `update_insight`         | Insights / Anomalies (Create/Modify Insights / Anomalies)    | `insights:update-insight`                    |

All other tools are available to any authenticated user.

<Callout icon="⚠️" theme="warning">
  API key users have full access to all cost data and all tools. Role-based data access filters and permission set restrictions do not apply. Use OAuth authentication when role-based access control is required.
</Callout>

## Usage quotas

API key calls are subject to a daily usage quota per organization. OAuth users are not metered.

<Callout icon="ℹ️" theme="info">
  Each organization has a default quota of **3,000 API key tool calls per UTC calendar day**. The quota resets at midnight UTC.
</Callout>

### Quota warnings

As your organization approaches the daily limit, the MCP server appends a warning to tool results at the following thresholds:

| Threshold | Example warning                                                           |
| --------- | ------------------------------------------------------------------------- |
| 50%       | "Your organization has used 50% (1500/3000) of the daily API call quota." |
| 75%       | "Your organization has used 75% (2250/3000) of the daily API call quota." |
| 90%       | "Your organization has used 90% (2700/3000) of the daily API call quota." |

### Quota exceeded

When the daily quota is exceeded, the MCP server returns an error and no further API key tool calls succeed until the quota resets at midnight UTC.

## Response size limit

The MCP server enforces a 5 MB maximum on individual tool responses. When a query produces a response above the limit, the server returns a tool error with the actual response size and guidance for narrowing the query:

`"Tool '<tool_name>' produced a response of <X.X> MB, which exceeds the 5 MB limit. To recover, narrow your query: shrink date_range, add or tighten filters, reduce the limit parameter, or change group_by to a less granular dimension."`

AI agents that receive this error can retry with a narrower query automatically.

### Per-tool limit caps

Query-style tools also enforce a maximum value for the `limit` parameter. Requests that exceed the cap are rejected before the tool runs.

| Tool                       | Maximum `limit` |
| -------------------------- | --------------- |
| `get_available_dimensions` | 1,000           |
| `get_container_usage`      | 1,000           |
| `get_cost_data`            | 5,000           |
| `get_dimension_values`     | 1,000           |
| `get_optimize_recs`        | 1,000           |
| `get_telemetry_data`       | 5,000           |

## Tools

| Category      | Tool                                                     | Description                                                              |
| ------------- | -------------------------------------------------------- | ------------------------------------------------------------------------ |
| Allocations   | [get\_available\_dimensions](#get_available_dimensions)  | List Dimensions for filtering and grouping                               |
| Allocations   | [get\_dimension\_values](#get_dimension_values)          | Get values for a specific Dimension                                      |
| Context       | [get\_org\_context](#get_org_context)                    | Retrieve organization context: custom instructions and generated context |
| Context       | [get\_org\_context\_versions](#get_org_context_versions) | List available context versions                                          |
| Context       | [set\_generated\_context](#set_generated_context)        | Replace the generated context that `/init` derives from query history    |
| Context       | [set\_org\_context](#set_org_context)                    | Replace the custom instructions that agents follow                       |
| CostFormation | [download\_costformation](#download_costformation)       | Get a download link for a CostFormation definition                       |
| CostFormation | [get\_costformation\_vers](#get_costformation_vers)      | List versions of a CostFormation definition                              |
| Insights      | [create\_insight](#create_insight)                       | Log a finding as an Insight                                              |
| Insights      | [delete\_insight](#delete_insight)                       | Delete a manually created Insight and its comments                       |
| Insights      | [update\_insight](#update_insight)                       | Change the status or effort of a manually created Insight                |
| Kubernetes    | [get\_container\_usage](#get_container_usage)            | Get Kubernetes CPU and memory usage versus requests                      |
| Optimization  | [get\_optimize\_recs](#get_optimize_recs)                | Get cost optimization recommendations                                    |
| Optimization  | [get\_realized\_savings](#get_realized_savings)          | Track realized savings from addressed recommendations                    |
| Query         | [get\_cost\_data](#get_cost_data)                        | Query cost data with filters and groupings                               |
| Query         | [get\_recent\_query\_history](#get_recent_query_history) | View recent cost queries                                                 |
| Reference     | [get\_reference\_info](#get_reference_info)              | Get reference documentation                                              |
| Resource      | [get\_resource\_metadata](#get_resource_metadata)        | Retrieve metadata for a single cloud resource                            |
| Telemetry     | [get\_telemetry\_data](#get_telemetry_data)              | Retrieve telemetry metrics                                               |
| Telemetry     | [get\_telemetry\_streams](#get_telemetry_streams)        | List available telemetry streams                                         |

## Allocations

### get\_available\_dimensions

Lists all available Dimensions for filtering or grouping cost data, including both standard CloudZero Dimensions and custom Dimensions.

#### Parameters

| Parameter        | Required | Description                          |
| ---------------- | -------- | ------------------------------------ |
| `filter`         | No       | Filter Dimensions by name pattern    |
| `force_refresh`  | No       | Bypass cache and fetch fresh data    |
| `include_hidden` | No       | Include hidden Dimensions in results |
| `limit`          | No       | Maximum Dimensions to return         |

**Skills:** custom-dimension-analysis, tag-coverage-analysis, understand-cloudzero-organization

### get\_dimension\_values

Retrieves the available values for a specific Dimension, such as all account names, service types, or team values.

#### Parameters

| Parameter    | Required | Description                     |
| ------------ | -------- | ------------------------------- |
| `date_range` | No       | Time period to scope the values |
| `dimension`  | Yes      | The Dimension to get values for |
| `limit`      | No       | Maximum values to return        |
| `match`      | No       | Filter values by pattern        |

**Skills:** cost-comparison, custom-dimension-analysis, tag-coverage-analysis, understand-cloudzero-organization

## Context

Organization context is the guidance every agent reads at the start of a cost analysis session. It has two sections with different owners:

| Section             | Written by                                                                 | What it holds                                                                                                                           |
| ------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Custom Instructions | You, with [set\_org\_context](#set_org_context) or by asking the agent     | Rules agents must follow: business rules, Dimension preferences, team structures and cost ownership, cost allocation policies           |
| Generated Context   | The `/init` prompt, with [set\_generated\_context](#set_generated_context) | What `/init` derives from your recent query history: Dimension definitions, common workflows, team structures, cost allocation patterns |

Each tool writes only its own section and carries the other forward unchanged. Custom Instructions take precedence when the two overlap.

### Keep custom guidance across /init

The `/init` prompt (`/plugin:cost-analyst:cloudzero:init` in the Claude Code Plugin) replaces Generated Context in full on every run and never edits Custom Instructions. To add a rule that persists, such as "exclude tax and support charges by default," save it to Custom Instructions with [set\_org\_context](#set_org_context) or ask the agent to save it for you. For setup steps, see [Set Up AI Hub](/docs/ai-getting-started).

If you ran `/init` before context was split into two sections, your earlier generated content is stored as Custom Instructions and preserved as written. The next `/init` run offers to move those sections out of Custom Instructions and removes only what you confirm.

### get\_org\_context

Retrieves your organization's context for cost analysis. The `instructions` field returns up to two sections: `# Custom Instructions`, authored by your organization with [set\_org\_context](#set_org_context), followed by `# Generated Context`, derived from query history by the `/init` prompt. Custom Instructions take precedence. A section is omitted when it is empty.

#### Parameters

| Parameter | Required | Description                                                   |
| --------- | -------- | ------------------------------------------------------------- |
| `version` | No       | Specific context version to retrieve (defaults to the latest) |

**Skills:** understand-cloudzero-organization, all other skills (consume cached context)

### get\_org\_context\_versions

Lists all available versions of organization context for reviewing historical configurations. Every save with [set\_org\_context](#set_org_context) or [set\_generated\_context](#set_generated_context) creates a timestamped version. Prior versions are retained for 30 days; the current version never expires.

#### Parameters

None.

**Skills:** understand-cloudzero-organization

### set\_generated\_context

Replaces the Generated Context section with content derived from recent query history. The `/init` prompt calls this tool after you review and confirm the proposed context. Custom Instructions are preserved exactly as stored, so every rule a person added survives the refresh.

#### Parameters

| Parameter   | Required | Description                                                                                                            |
| ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `generated` | Yes      | The complete generated context. Replaces the current Generated Context section; Custom Instructions are left unchanged |

**Skills:** Used by the `/init` prompt rather than by a skill

### set\_org\_context

Replaces the Custom Instructions section with guidance you want every agent to follow: business rules, Dimension preferences, team structures and cost ownership, cost allocation policies. The tool leaves Generated Context unchanged, and `/init` in turn never modifies Custom Instructions. Because the call replaces the whole section, pass the full updated text when adding to existing instructions, not just the addition.

#### Parameters

| Parameter | Required | Description                                                                                                             |
| --------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `context` | Yes      | The complete custom instructions. Replaces the current Custom Instructions section; Generated Context is left unchanged |

**Skills:** understand-cloudzero-organization

## CostFormation

These tools read the YAML Dimension definitions you manage with [CostFormation](/docs/allocate-through-yaml).

### download\_costformation

Returns a pre-signed, temporary download link for a CostFormation Dimension definition file, along with metadata about when the definition was last updated and by whom. The link expires shortly after it is issued. Request a new link rather than retrying an expired one.

#### Parameters

| Parameter | Required | Description                                                                               |
| --------- | -------- | ----------------------------------------------------------------------------------------- |
| `fqn`     | No       | Fully qualified name of the CostFormation definition (defaults to the default definition) |
| `version` | No       | Version identifier to download (defaults to the latest version)                           |

**Skills:** Available for direct CostFormation review and export workflows

### get\_costformation\_vers

Lists the available versions of a CostFormation Dimension definition. Returns version identifiers with human-readable creation dates, most recent first. Use this to find a version before downloading it with [download\_costformation](#download_costformation).

#### Parameters

| Parameter | Required | Description                                                                               |
| --------- | -------- | ----------------------------------------------------------------------------------------- |
| `fqn`     | No       | Fully qualified name of the CostFormation definition (defaults to the default definition) |
| `limit`   | No       | Maximum number of versions to return (default: `10`)                                      |

**Skills:** Available for direct CostFormation review and export workflows

## Insights

These tools let an agent log a finding as an [Insight](/docs/insights) and track it as your team works on it. They act on the same Insights you create from Explorer, and the results appear on the **Insights** tab in Optimize. All three tools require [full data access](#data-access-controls).

`update_insight` and `delete_insight` work only on Insights that a person created, through Explorer or with `create_insight`. They reject Insights that CloudZero generates automatically, such as cost anomalies and recommendations.

### create\_insight

Creates an Insight with the same fields and validation as the **Create Insight** form in Explorer. CloudZero removes HTML from the title and description, and accepts a link only when it is an `https://` URL on a `cloudzero.com` domain, such as a link back to an Explorer query. Returns the new Insight, including its ID.

#### Parameters

| Parameter     | Required | Description                                                                          |
| ------------- | -------- | ------------------------------------------------------------------------------------ |
| `category`    | Yes      | Insight category: `Trend`, `Optimization`, or `Other`                                |
| `cost_impact` | No       | Estimated cost impact in your organization's currency                                |
| `description` | Yes      | What you found and why it matters                                                    |
| `effort`      | No       | Estimated effort to address: `not_set`, `low`, `medium`, or `high`                   |
| `link`        | No       | `https://` link on a `cloudzero.com` domain that points to supporting detail         |
| `status`      | No       | Initial status (default: `new`). See [Insight status values](#insight-status-values) |
| `title`       | Yes      | Short name for the finding                                                           |

**Skills:** Available for direct Insight logging

### delete\_insight

Permanently deletes an Insight and all of its comments. A deleted Insight cannot be restored. To close an Insight and keep its history, set its status to `addressed` or `ignored` with [update\_insight](#update_insight) instead. Returns the deleted Insight's ID and the number of comments deleted.

#### Parameters

| Parameter    | Required | Description                 |
| ------------ | -------- | --------------------------- |
| `insight_id` | Yes      | ID of the Insight to delete |

**Skills:** Available for direct Insight management

### update\_insight

Changes the status or effort of a manually created Insight. Pass at least one of `status` or `effort`; fields you leave out keep their current values. Returns the updated Insight.

#### Parameters

| Parameter    | Required | Description                                                     |
| ------------ | -------- | --------------------------------------------------------------- |
| `effort`     | No       | New effort estimate: `not_set`, `low`, `medium`, or `high`      |
| `insight_id` | Yes      | ID of the Insight to update                                     |
| `status`     | No       | New status. See [Insight status values](#insight-status-values) |

#### Insight status values

| Value         | Description                                                       |
| ------------- | ----------------------------------------------------------------- |
| `addressed`   | The Insight has been acted on (closes the Insight).               |
| `ignored`     | The Insight has been reviewed and dismissed (closes the Insight). |
| `in_progress` | Someone is actively working on the Insight.                       |
| `new`         | The Insight has been logged but no action has been taken.         |
| `on_hold`     | Work on the Insight is paused.                                    |

**Skills:** Available for direct Insight management

## Kubernetes

### get\_container\_usage

Reports how much CPU and memory Kubernetes workloads actually use versus what they request, for rightsizing and container-efficiency analysis. Data comes from the [CloudZero Agent for Kubernetes](/docs/installation-of-cloudzero-agent-for-kubernetes), so it covers only clusters running the agent. Cost is not included here; use the cost tools for spend and pair the two to size the savings available from rightsizing.

#### Parameters

| Parameter      | Required | Description                                                                                                              |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `date_range`   | No       | Time period to query (defaults to the last 30 days)                                                                      |
| `filters`      | No       | Filter criteria as a dict mapping a dimension to the values to include, for example `{"k8s_workload": ["checkout-api"]}` |
| `limit`        | No       | Maximum entities to return, from 1 to 1000 (default: `100`)                                                              |
| `partition_by` | Yes      | Kubernetes entity to key the results by                                                                                  |

#### Partition values

| Value           | Description              |
| --------------- | ------------------------ |
| `k8s_cluster`   | Key results by cluster   |
| `k8s_namespace` | Key results by namespace |
| `k8s_workload`  | Key results by workload  |

Valid `filters` dimensions are `k8s_cluster`, `k8s_namespace`, `k8s_workload`, `cloud_account_id`, `cloud_provider`, and `cloud_region`.

#### Response

Each entity reports `p95_used` (the 95th-percentile amount used over the date range, which absorbs short spikes), `requested` (the amount reserved), and `efficiency` (`p95_used / requested`). Efficiency well under 1.0 means the workload reserves far more than it uses and is a rightsizing candidate; near 1.0 means it is sized about right; above 1.0 means it is using more than it requested and risks CPU throttling or OOM kills. Efficiency is capped at 2.0, so that value means "at least twice its request" rather than an exact ratio. Any of the three values can be `null`, most often for workloads that set no resource requests.

CPU is reported in cores and memory in GiB. The response echoes `cpu_unit`, `memory_unit`, and the effective `date_range` used.

The response holds at most `limit` entities, chosen by the most CPU requested, so the largest reservations come first. `total_entities` reports how many entities matched the query, and `truncated` is `true` when that count is higher than the number returned. Organization-wide `k8s_workload` queries can match tens of thousands of workloads. To see past the largest ones, narrow the query with a `k8s_cluster` or `k8s_namespace` filter rather than raising `limit`.

**Skills:** Available for direct Kubernetes rightsizing lookups

## Optimization

### get\_optimize\_recs

Retrieves cost optimization recommendations from CloudZero, including rightsizing, Reserved Instance, and Savings Plan opportunities.

#### Parameters

| Parameter    | Required | Description                       |
| ------------ | -------- | --------------------------------- |
| `limit`      | No       | Maximum recommendations to return |
| `offset`     | No       | Pagination offset                 |
| `sort_key`   | No       | Field to sort results by          |
| `sort_order` | No       | Sort direction: `asc` or `desc`   |
| `status`     | No       | Filter by recommendation status   |

#### Status values

| Value         | Description        |
| ------------- | ------------------ |
| `addressed`   | Completed          |
| `ignored`     | Dismissed          |
| `in_progress` | Being implemented  |
| `not_started` | Not yet acted upon |

**Skills:** service-cost-deep-dive

### get\_realized\_savings

Retrieves realized savings from addressed Optimize recommendations over a time period, with optional breakdowns by Dimension.

#### Parameters

| Parameter        | Required | Description                                                                     |
| ---------------- | -------- | ------------------------------------------------------------------------------- |
| `end_date`       | No       | End date in `YYYY-MM-DD` format (defaults to today)                             |
| `filters`        | No       | Filter criteria as a JSON object (for example, `{"service": ["EC2"]}`)          |
| `max_partitions` | No       | Maximum number of partitions to return (default: `10`)                          |
| `partition_by`   | No       | Dimension to partition results by (for example, `service`, `account`, `region`) |
| `start_date`     | No       | Start date in `YYYY-MM-DD` format (defaults to 30 days ago)                     |

**Skills:** Available for direct savings analysis and reporting

## Query

### get\_cost\_data

Queries cost data from CloudZero with support for grouping, filtering, and time-based analysis. This is the primary tool for retrieving cost information.

#### Parameters

| Parameter     | Required | Description                                                        |
| ------------- | -------- | ------------------------------------------------------------------ |
| `cost_type`   | No       | Type of cost metric (default: `real_cost`)                         |
| `date_range`  | No       | Time period to query (defaults to the last 30 days)                |
| `filters`     | No       | Filter criteria to narrow results                                  |
| `granularity` | No       | Time granularity: `hourly`, `daily`, `weekly`, `30days`, `monthly` |
| `group_by`    | No       | Dimensions to group results by (up to 3)                           |
| `limit`       | No       | Maximum results to return (default: `50`)                          |

#### Response

Each result row includes `projected_row_count`, the number of underlying cost records aggregated into that row. This is useful for diagnosing Dimension cardinality and allocation complexity. The value is `null` for hourly granularity.

**Skills:** cost-anomaly-detection, cost-comparison, cost-spike-investigation, cost-trend-analysis, custom-dimension-analysis, service-cost-deep-dive, tag-coverage-analysis, top-cost-drivers

### get\_recent\_query\_history

Returns an analysis of your organization's cost query patterns over the last 30 days, including the most frequently used queries (overall and over the last 7 days), the most frequently used Dimensions, and total query counts.

#### Parameters

None.

**Skills:** All skills (for context)

## Reference

### get\_reference\_info

Retrieves reference documentation about CloudZero concepts, workflows, and best practices.

#### Parameters

| Parameter        | Required | Description                   |
| ---------------- | -------- | ----------------------------- |
| `reference_type` | Yes      | Type of reference to retrieve |

#### Reference types

| Value                        | Description                      |
| ---------------------------- | -------------------------------- |
| `cost_analyst_instructions`  | General cost analyst guidance    |
| `cost_analysis_workflow`     | Best practices for cost analysis |
| `cost_types`                 | Available cost metrics           |
| `custom_dimensions_workflow` | Working with custom Dimensions   |
| `dimensions`                 | Standard Dimensions              |
| `filtering_workflow`         | How to filter cost data          |

**Skills:** understand-cloudzero-organization, all skills (for reference lookups)

## Resource

### get\_resource\_metadata

Retrieves metadata for a single cloud resource by its CloudZero Resource Name (CZRN), including provider service, resource type, lifecycle state, tags, and relationships.

#### Parameters

| Parameter | Required | Description                                                 |
| --------- | -------- | ----------------------------------------------------------- |
| `czrn`    | Yes      | The CloudZero Resource Name (CZRN) identifying the resource |

**Skills:** Available for direct resource metadata lookups

## Telemetry

### get\_telemetry\_data

Retrieves telemetry metrics from configured telemetry streams for correlating costs with operational metrics.

#### Parameters

| Parameter     | Required | Description                                                                                                                                                         |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `date_range`  | No       | Time period for telemetry data (defaults to the last 30 days)                                                                                                       |
| `filters`     | No       | Filter criteria to narrow results; only Dimensions in the stream's keys can be used as filters                                                                      |
| `granularity` | No       | Time granularity: `hourly`, `daily`, `weekly`, `30days`, `monthly`; defaults to the stream's native granularity and cannot be finer than the stream's natural grain |
| `group_by`    | No       | Dimensions to group results by; only target Dimensions in the stream's keys are valid                                                                               |
| `limit`       | No       | Maximum results to return (default: `50`)                                                                                                                           |
| `stream_name` | Yes      | The name of the telemetry stream to query                                                                                                                           |

**Skills:** cost-trend-analysis, service-cost-deep-dive

### get\_telemetry\_streams

Lists all available telemetry streams configured in your CloudZero organization.

#### Parameters

None.

**Skills:** cost-trend-analysis, service-cost-deep-dive

## Parameter reference

### Cost types

The `cost_type` parameter accepts the following values:

| Value                                                                     | Description                                                                                           |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| [`amortized_cost`](/docs/cost-types#amortized-cost)                       | Upfront payments spread over term                                                                     |
| [`billed_cost`](/docs/cost-types#billed-cost)                             | As invoiced                                                                                           |
| `custom_cost`                                                             | A cost calculation defined for your organization, available when CloudZero has configured one for you |
| [`discounted_amortized_cost`](/docs/cost-types#discounted-amortized-cost) | Amortized with discounts                                                                              |
| [`discounted_cost`](/docs/cost-types#discounted-cost)                     | Discount amounts applied                                                                              |
| [`invoiced_amortized_cost`](/docs/cost-types#invoiced-amortized-cost)     | Recurring commitment charges amortized; upfront charges remain separate line items                    |
| [`on_demand_cost`](/docs/cost-types#on-demand-cost)                       | On-demand pricing                                                                                     |
| [`real_cost`](/docs/cost-types#real-cost)                                 | After all discounts (default)                                                                         |
| `usage_amount`                                                            | Usage quantities (for example, GB-hours or compute-hours) instead of cost                             |

### Granularity options

The `granularity` parameter accepts:

| Value     | Description                   |
| --------- | ----------------------------- |
| `30days`  | Fixed 30-day period breakdown |
| `daily`   | Day-by-day breakdown          |
| `hourly`  | Hour-by-hour breakdown        |
| `monthly` | Month-by-month breakdown      |
| `weekly`  | Week-by-week breakdown        |

Omit the `granularity` parameter to return the total for the period with no time breakdown.

<Callout icon="ℹ️" theme="info">
  Have questions or feedback? Reach out to your account manager.
</Callout>