---
title: "Update a unit cost"
method: PUT
path: "/api/v2/cost/unit_costs/{unit_cost_id}"
tags: ["Cloud Cost Management"]
---

# Update a unit cost

`PUT /api/v2/cost/unit_costs/{unit_cost_id}`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/cost/unit_costs/{unit_cost_id}`
- Auth: one of:
  - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`
  - OAuth 2
    - Authorization code: `/oauth2/v1/authorize`
    - Token URL: `/oauth2/v1/token`
- TypeScript: <https://skmtc.dev/datadog/apis/datadog-api-v2-collection/docs/api/v2/cost/unit_costs/:unit_cost_id/put.ts> (a function with typed inputs; its response is checked against the schema)

Replace an ROI metric (unit cost) with a new set of attributes.

## Path parameters

- `unit_cost_id` string, uuid, required

## Request body

- UnitCostUpdateRequest: A request to replace a unit cost.
  - `data` UnitCostUpdateRequestData, required: The data object of a unit cost replace request.
    - `attributes` UnitCostRequestAttributes, required: The attributes of a unit cost create or replace request.
      - `denominator_query` UnitCostQueryDefinition, required: A timeseries object containing `queries` and `formulas` arrays.
        - `formulas` UnitCostFormula[], required: The list of formulas applied to the queries for this side of the ratio.
        - `queries` UnitCostQuery[], required: The list of queries evaluated for this side of the ratio.
      - `description` string, nullable: An optional description of the unit cost. At most 2000 characters.
      - `name` string, required: The name of the unit cost. At most 200 characters.
      - `numerator_query` UnitCostQueryDefinition, required: A timeseries object containing `queries` and `formulas` arrays.
        - `formulas` UnitCostFormula[], required: The list of formulas applied to the queries for this side of the ratio.
        - `queries` UnitCostQuery[], required: The list of queries evaluated for this side of the ratio.
      - `unit_label` string, required: The label describing the denominator unit, for example `user`. At most 100 characters.
    - `id` string, uuid, required: The UUID of the unit cost being replaced. Must match the `unit_cost_id` path parameter.
    - `type` 'unit_cost', required: The JSON:API resource type for a unit cost.

## Response `200`

OK

- UnitCostResponse: A response containing a single unit cost.
  - `data` UnitCostDataResponse, required: The data object of a unit cost response.
    - `attributes` UnitCostDataAttributesResponse, required: The attributes of a unit cost.
      - `created_at` string, date-time, required: The time the unit cost was created.
      - `created_by` string, uuid, required: The UUID of the user who created the unit cost.
      - `denominator_query` UnitCostQueryDefinition, required: A timeseries object containing `queries` and `formulas` arrays.
        - `formulas` UnitCostFormula[], required: The list of formulas applied to the queries for this side of the ratio.
        - `queries` UnitCostQuery[], required: The list of queries evaluated for this side of the ratio.
      - `denominator_type` string, required: The data source of the denominator queries, or `multisource` when the denominator queries span more than one data source.
      - `description` string, nullable: The description of the unit cost. Omitted when the unit cost has no description.
      - `name` string, required: The name of the unit cost.
      - `numerator_query` UnitCostQueryDefinition, required: A timeseries object containing `queries` and `formulas` arrays.
        - `formulas` UnitCostFormula[], required: The list of formulas applied to the queries for this side of the ratio.
        - `queries` UnitCostQuery[], required: The list of queries evaluated for this side of the ratio.
      - `org_id` integer, required: The ID of the organization the unit cost belongs to.
      - `unit_label` string, required: The label describing the denominator unit.
      - `updated_at` string, date-time, required: The time the unit cost was last updated.
      - `updated_by` string, uuid, required: The UUID of the user who last updated the unit cost.
    - `id` string, uuid, required: The UUID of the unit cost.
    - `type` 'unit_cost', required: The JSON:API resource type for a unit cost.

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `404`: Not Found
- `429`: Too many requests

---

[API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/3f70db624329?raw)