---
title: "Get a project metric"
method: GET
path: "/api/v1/projects/{projectId}/metrics/{metricKey}"
tags: ["Projects"]
---

# Get a project metric

`GET /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`

Returns one metric's points over a range, with the range value, the preceding range's value, and the change. An empty range has a null value, never 0.

## Path parameters

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

## Query parameters

- `range` '7d' | '30d' | '90d': The range to summarize, ending today. Defaults to 30 days.

## Response `200`

The metric over the requested range.

- 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
  - `range` '7d' | '30d' | '90d', required
  - `from` string, required: Inclusive start of the range.
  - `to` string, required: Exclusive end of the range.
  - `value` number, nullable, required: Null when the range holds no points — never 0.
  - `previousValue` number, nullable, required
  - `change` object, nullable, required
    - `absolute` number, required
    - `ratio` number, required: Change relative to the preceding value's magnitude; -0.4 is a 40% fall.
  - `categories` object[], required
    - `category` string, required
    - `value` number, required
  - `points` object[], required
    - `bucket` string, required: `YYYY-MM-DD` for day grain, an ISO 8601 UTC hour for hour grain.
    - `category` string, nullable, required
    - `value` number, required
  - `scatterPoints` object[], required
    - `id` string, required
    - `x` number, required
    - `y` number, required
    - `label` string, nullable, required
    - `observedAt` string, nullable, required
    - `receivedAt` string, required

## Other responses

- `401`: Authentication is missing or invalid.
- `404`: The resource was not found.
- `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)