---
title: "Update a project metric's curation"
method: PATCH
path: "/api/v1/projects/{projectId}/metrics/{metricKey}"
tags: ["Projects"]
---

# Update a project metric's curation

`PATCH /api/v1/projects/{projectId}/metrics/{metricKey}`

## Request

- Base URL: `https://app.khotan.com`
- URL: `https://app.khotan.com/api/v1/projects/{projectId}/metrics/{metricKey}`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Changes a metric's display name, position, hidden flag, or headline flag. Reports never overwrite these. Hiding a headline metric clears headline; a project has at most three headline metrics, and a scatter metric cannot be headline.

## Path parameters

- `projectId` string, required
- `metricKey` string, required

## Request body

- object
  - `displayName` string, nullable: Curated name. Null clears it, so the reported name shows again.
  - `position` integer: Sort position among the project's metrics, ascending.
  - `hidden` boolean: Hides the metric from readers. Hiding also clears headline.
  - `headline` boolean: Leads the Metrics tab and the project card. At most 3 per project; a fourth returns 409.

## Response `200`

The updated metric.

- object
  - `key` string, required
  - `name` string, required: The name shown: the curated name, else the reported name, else the key.
  - `displayName` string, nullable, required
  - `reportedName` string, nullable, required
  - `shape` 'series' | 'breakdown' | 'scatter', required
  - `grain` 'day' | 'hour', nullable, required
  - `unit` string, required
  - `goal` 'increase' | 'decrease' | 'neutral', required: Which direction of change is good news.
  - `aggregate` 'sum' | 'average' | 'latest', required: How values across a range combine into one number.
  - `description` string, nullable, required
  - `axes` object, nullable, required
    - `xLabel` string, required
    - `xUnit` string, required
    - `yLabel` string, required
    - `yUnit` string, required
  - `position` integer, required
  - `hidden` boolean, required
  - `headline` boolean, required
  - `headlineSlot` integer, nullable, required
  - `lastReportedAt` string, nullable, required
  - `createdAt` string, required
  - `updatedAt` string, required

## Other responses

- `401`: Authentication is missing or invalid.
- `403`: The caller is not permitted to perform this action.
- `404`: The resource was not found.
- `409`: The project already has three headline metrics.
- `422`: The patch is invalid, including headline on a hidden or scatter metric.
- `429`: Too many requests; retry after the indicated delay.

---

[API](https://skmtc.dev/khotan/apis/khotan-api.md) - [All operations](https://skmtc.dev/khotan/apis/khotan-api/llms.txt) - [OpenAPI document](https://skmtc.dev/khotan/apis/khotan-api/revisions/90b512a53e42?raw)