# Custom Metrics

Use these operations to interact with [custom metrics](/improve/eng-intelligence/custom-metrics.md) in Cortex Eng Intelligence.

### Required permissions

Your API key must have the `Configure Eng Intelligence custom metrics` permission.

## Operations

## Retrieve custom metrics data points

> Lists all custom metrics data points for an entity

```json
{"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Custom Metrics"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer <token>` header, where `<token>` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"schemas":{"CustomMetricDataResponse":{"required":["data","page","total","totalPages"],"type":"object","properties":{"data":{"type":"array","description":"Data points","items":{"$ref":"#/components/schemas/CustomMetricData"}},"page":{"type":"integer","description":"Current page number, 0-indexed","format":"int32"},"total":{"type":"integer","description":"Total number of results","format":"int32"},"totalPages":{"type":"integer","description":"Total number of pages","format":"int32"}}},"CustomMetricData":{"required":["timestamp","value"],"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"value":{"type":"number","format":"double"}},"description":"Data points"},"ErrorResponse":{"required":["message","type"],"type":"object","properties":{"details":{"type":"string"},"gatewayHttpStatus":{"type":"integer","format":"int32"},"httpStatus":{"type":"integer","format":"int32"},"message":{"type":"string"},"requestId":{"type":"string"},"type":{"type":"string","enum":["INTEGRATION_MISSING","INTEGRATION_UNREGISTERED","INTEGRATION_UNSUPPORTED","INTEGRATION_GRAPHQL_ERROR","INTEGRATION_BAD_REQUEST","INTEGRATION_UNAUTHORIZED","INTEGRATION_FORBIDDEN","INTEGRATION_NOT_FOUND","INTEGRATION_UNPROCESSABLE_CONTENT","INTEGRATION_RATE_LIMITED","INTEGRATION_INTERNAL_ERROR","INTEGRATION_NOT_IMPLEMENTED","INTEGRATION_BAD_GATEWAY","INTEGRATION_UNAVAILABLE","INTEGRATION_GATEWAY_TIMEOUT","INTEGRATION_TIMED_OUT","INTEGRATION_CACHE_ERROR","INTEGRATION_UNHANDLED_HTTP_ERROR","INTEGRATION_UNHANDLED_EXCEPTION","INTEGRATION_UNEXPECTED_ERROR","ILLEGAL_ARGUMENT_ERROR","BAD_REQUEST","FORBIDDEN","NOT_FOUND","REQUEST_TIMEOUT","CONFLICT","UNHANDLED_EXCEPTION","UNCATEGORIZED","SERVICE_CREATOR","UNKNOWN_HOST","TOO_MANY_REQUESTS"]}}},"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}}},"paths":{"/api/v1/eng-intel/custom-metrics/{customMetricKey}/entity/{tagOrId}":{"get":{"description":"Lists all custom metrics data points for an entity","operationId":"getCustomMetricData","parameters":[{"description":"Key for the custom metric filter","in":"path","name":"customMetricKey","required":true,"schema":{"type":"string"}},{"description":"The tag (`x-cortex-tag`) or unique, auto-generated identifier for the entity.","in":"path","name":"tagOrId","required":true,"schema":{"type":"string","description":"Entity identifier - can be a tag or CID"}},{"description":"Start date for the filter (inclusive). Default: 6 months","in":"query","name":"startDate","required":false,"schema":{"type":"string","format":"date-time"}},{"description":"End date for the filter (inclusive)","in":"query","name":"endDate","required":false,"schema":{"type":"string","format":"date-time"}},{"description":"Number of results to return per page, between 1 and 1000. Default 250.","in":"query","name":"pageSize","required":true,"schema":{"type":"integer","format":"int32","default":250}},{"description":"Page number to return, 0-indexed. Default 0.","in":"query","name":"page","required":true,"schema":{"type":"integer","format":"int32","default":0}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomMetricDataResponse"}}},"description":"Successfully retrieved custom metrics data points"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid filters"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Retrieve custom metrics data points","tags":["Custom Metrics"]}}}}
```

## Add custom metrics data point

> Adds a single custom metric data point for entity.

```json
{"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Custom Metrics"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer <token>` header, where `<token>` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"schemas":{"CreateCustomDataRequest":{"required":["value"],"type":"object","properties":{"timestamp":{"type":"string","description":"Timestamp for the data point in ISO 8601 format. Accepts timezone offsets (e.g., '2024-08-14T11:00:00Z' or '2024-08-14T11:00:00+00:00'). Note: It can't be earlier than 2 years","format":"date-time"},"value":{"type":"number","description":"Value for the data point","format":"double"}},"description":"Data point to be added"},"ErrorResponse":{"required":["message","type"],"type":"object","properties":{"details":{"type":"string"},"gatewayHttpStatus":{"type":"integer","format":"int32"},"httpStatus":{"type":"integer","format":"int32"},"message":{"type":"string"},"requestId":{"type":"string"},"type":{"type":"string","enum":["INTEGRATION_MISSING","INTEGRATION_UNREGISTERED","INTEGRATION_UNSUPPORTED","INTEGRATION_GRAPHQL_ERROR","INTEGRATION_BAD_REQUEST","INTEGRATION_UNAUTHORIZED","INTEGRATION_FORBIDDEN","INTEGRATION_NOT_FOUND","INTEGRATION_UNPROCESSABLE_CONTENT","INTEGRATION_RATE_LIMITED","INTEGRATION_INTERNAL_ERROR","INTEGRATION_NOT_IMPLEMENTED","INTEGRATION_BAD_GATEWAY","INTEGRATION_UNAVAILABLE","INTEGRATION_GATEWAY_TIMEOUT","INTEGRATION_TIMED_OUT","INTEGRATION_CACHE_ERROR","INTEGRATION_UNHANDLED_HTTP_ERROR","INTEGRATION_UNHANDLED_EXCEPTION","INTEGRATION_UNEXPECTED_ERROR","ILLEGAL_ARGUMENT_ERROR","BAD_REQUEST","FORBIDDEN","NOT_FOUND","REQUEST_TIMEOUT","CONFLICT","UNHANDLED_EXCEPTION","UNCATEGORIZED","SERVICE_CREATOR","UNKNOWN_HOST","TOO_MANY_REQUESTS"]}}},"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}}},"paths":{"/api/v1/eng-intel/custom-metrics/{customMetricKey}/entity/{tagOrId}":{"post":{"description":"Adds a single custom metric data point for entity.","operationId":"createCustomMetricData","parameters":[{"description":"Key for the custom metric filter","in":"path","name":"customMetricKey","required":true,"schema":{"type":"string"}},{"description":"The tag (`x-cortex-tag`) or unique, auto-generated identifier for the entity.","in":"path","name":"tagOrId","required":true,"schema":{"type":"string","description":"Entity identifier - can be a tag or CID"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomDataRequest"}}},"required":true},"responses":{"200":{"description":"Successfully added data point"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid filters"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Add custom metrics data point","tags":["Custom Metrics"]}}}}
```

## Add custom metrics data points in bulk

> Adds multiple custom metric data points for entity.

```json
{"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Custom Metrics"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer <token>` header, where `<token>` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"schemas":{"CreateCustomDataBulkRequest":{"required":["series"],"type":"object","properties":{"series":{"maxLength":100,"minLength":1,"type":"array","description":"List of data points","items":{"$ref":"#/components/schemas/CreateCustomDataBulkDef"}}},"description":"Data points to be added"},"CreateCustomDataBulkDef":{"maxLength":100,"minLength":1,"required":["timestamp","value"],"type":"object","properties":{"timestamp":{"type":"string","description":"Timestamp for the data point in ISO 8601 format. Accepts timezone offsets (e.g., '2024-08-14T11:00:00Z' or '2024-08-14T11:00:00+00:00'). Note: It can't be earlier than 2 years","format":"date-time"},"value":{"type":"number","description":"Value for the data point","format":"double"}},"description":"List of data points"},"ErrorResponse":{"required":["message","type"],"type":"object","properties":{"details":{"type":"string"},"gatewayHttpStatus":{"type":"integer","format":"int32"},"httpStatus":{"type":"integer","format":"int32"},"message":{"type":"string"},"requestId":{"type":"string"},"type":{"type":"string","enum":["INTEGRATION_MISSING","INTEGRATION_UNREGISTERED","INTEGRATION_UNSUPPORTED","INTEGRATION_GRAPHQL_ERROR","INTEGRATION_BAD_REQUEST","INTEGRATION_UNAUTHORIZED","INTEGRATION_FORBIDDEN","INTEGRATION_NOT_FOUND","INTEGRATION_UNPROCESSABLE_CONTENT","INTEGRATION_RATE_LIMITED","INTEGRATION_INTERNAL_ERROR","INTEGRATION_NOT_IMPLEMENTED","INTEGRATION_BAD_GATEWAY","INTEGRATION_UNAVAILABLE","INTEGRATION_GATEWAY_TIMEOUT","INTEGRATION_TIMED_OUT","INTEGRATION_CACHE_ERROR","INTEGRATION_UNHANDLED_HTTP_ERROR","INTEGRATION_UNHANDLED_EXCEPTION","INTEGRATION_UNEXPECTED_ERROR","ILLEGAL_ARGUMENT_ERROR","BAD_REQUEST","FORBIDDEN","NOT_FOUND","REQUEST_TIMEOUT","CONFLICT","UNHANDLED_EXCEPTION","UNCATEGORIZED","SERVICE_CREATOR","UNKNOWN_HOST","TOO_MANY_REQUESTS"]}}},"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}}},"paths":{"/api/v1/eng-intel/custom-metrics/{customMetricKey}/entity/{tagOrId}/bulk":{"post":{"description":"Adds multiple custom metric data points for entity.","operationId":"createBulkCustomMetricData","parameters":[{"description":"Key for the custom metric filter","in":"path","name":"customMetricKey","required":true,"schema":{"type":"string"}},{"description":"The tag (`x-cortex-tag`) or unique, auto-generated identifier for the entity.","in":"path","name":"tagOrId","required":true,"schema":{"type":"string","description":"Entity identifier - can be a tag or CID"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomDataBulkRequest"}}},"required":true},"responses":{"200":{"description":"Successfully added data points"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid filters"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Add custom metrics data points in bulk","tags":["Custom Metrics"]}}}}
```

## Delete custom metrics data points

> Deletes custom metric data points for entity.

```json
{"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Custom Metrics"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer <token>` header, where `<token>` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"schemas":{"ErrorResponse":{"required":["message","type"],"type":"object","properties":{"details":{"type":"string"},"gatewayHttpStatus":{"type":"integer","format":"int32"},"httpStatus":{"type":"integer","format":"int32"},"message":{"type":"string"},"requestId":{"type":"string"},"type":{"type":"string","enum":["INTEGRATION_MISSING","INTEGRATION_UNREGISTERED","INTEGRATION_UNSUPPORTED","INTEGRATION_GRAPHQL_ERROR","INTEGRATION_BAD_REQUEST","INTEGRATION_UNAUTHORIZED","INTEGRATION_FORBIDDEN","INTEGRATION_NOT_FOUND","INTEGRATION_UNPROCESSABLE_CONTENT","INTEGRATION_RATE_LIMITED","INTEGRATION_INTERNAL_ERROR","INTEGRATION_NOT_IMPLEMENTED","INTEGRATION_BAD_GATEWAY","INTEGRATION_UNAVAILABLE","INTEGRATION_GATEWAY_TIMEOUT","INTEGRATION_TIMED_OUT","INTEGRATION_CACHE_ERROR","INTEGRATION_UNHANDLED_HTTP_ERROR","INTEGRATION_UNHANDLED_EXCEPTION","INTEGRATION_UNEXPECTED_ERROR","ILLEGAL_ARGUMENT_ERROR","BAD_REQUEST","FORBIDDEN","NOT_FOUND","REQUEST_TIMEOUT","CONFLICT","UNHANDLED_EXCEPTION","UNCATEGORIZED","SERVICE_CREATOR","UNKNOWN_HOST","TOO_MANY_REQUESTS"]}}},"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}}},"paths":{"/api/v1/eng-intel/custom-metrics/{customMetricKey}/entity/{tagOrId}":{"delete":{"description":"Deletes custom metric data points for entity.","operationId":"deleteByTimeRange","parameters":[{"description":"Key for the custom metric filter","in":"path","name":"customMetricKey","required":true,"schema":{"type":"string"}},{"description":"The tag (`x-cortex-tag`) or unique, auto-generated identifier for the entity.","in":"path","name":"tagOrId","required":true,"schema":{"type":"string","description":"Entity identifier - can be a tag or CID"}},{"description":"Start date for the deletion (inclusive)","in":"query","name":"startDate","required":true,"schema":{"type":"string","format":"date-time"}},{"description":"End date for the deletion (inclusive)","in":"query","name":"endDate","required":true,"schema":{"type":"string","format":"date-time"}}],"responses":{"204":{"description":"Successfully deleted data points"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid filters"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Delete custom metrics data points","tags":["Custom Metrics"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cortex.io/api/readme/custom-metrics.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.