---
title: "Create a custom metric definition"
method: POST
path: "/api/v1/eng-intel/custom-metrics"
tags: ["Custom Metrics"]
---

# Create a custom metric definition

`POST /api/v1/eng-intel/custom-metrics`

## Request

- Base URL: `https://api.getcortexapp.com`
- URL: `https://api.getcortexapp.com/api/v1/eng-intel/custom-metrics`
- Auth: HTTP bearer

Defines a custom metric of type `PUBLIC_API`, which you then record data points against. The key cannot change after creation. API key must have the `Configure Eng Intelligence custom metrics` permission.

## Request body

- CreateCustomMetricDefinitionRequest: A custom metric to define
  - `category` string: Free-text group for the metric
  - `description` string: What the metric measures
  - `isDraft` boolean: A draft metric still accepts data points but is hidden from Eng Intelligence. Defaults to false.
  - `key` string, required: Unique key that data points are recorded against. Letters, digits, and hyphens, 2 to 255 characters, starting and ending with a letter or digit.
  - `name` string, required: Display name
  - `valence` 'POSITIVE' | 'NEGATIVE' | 'NEUTRAL', required: Whether a higher value is better. Defaults to NEUTRAL.

## Response `200`

The created custom metric definition

- CustomMetricDefinition: A custom metric defined in the workspace
  - `category` string: Free-text group for the metric
  - `cqlExpression` string: The CQL expression behind a `CQL` metric. Null for `PUBLIC_API`.
  - `description` string: What the metric measures
  - `isDraft` boolean, required: A draft metric is hidden from Eng Intelligence
  - `key` string, required: Unique key that data points are recorded against
  - `name` string, required: Display name
  - `type` 'CQL' | 'PUBLIC_API', required: `PUBLIC_API` metrics take data points through the API. `CQL` metrics compute their values from a CQL expression and are read-only through the API.
  - `valence` 'POSITIVE' | 'NEGATIVE' | 'NEUTRAL', required: Whether a higher value is better

## Other responses

- `400`: The request body failed validation
- `409`: A custom metric with this key already exists
- `429`: The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

## Changes

- **2026-11-03** `a7b058663c95`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cortex/apis/cortex-api/changes/api/v1/eng-intel/custom-metrics/post.md)

---

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