---
title: "Generate a failure-mode insight for one metric"
method: POST
path: "/observability/v1/metric-failure-mode-insights/generate/"
tags: ["observability"]
---

# Generate a failure-mode insight for one metric

`POST /observability/v1/metric-failure-mode-insights/generate/`

## Request

- Base URL: `https://api.cekura.ai`
- URL: `https://api.cekura.ai/observability/v1/metric-failure-mode-insights/generate/`
- Auth: one of:
  - API key in header `X-CEKURA-API-KEY`
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer

Queue a failure-mode audit of one metric's recent failing calls and return the new insight row in `pending`. Identify the metric with `metric_name` plus either `metric` (custom) or `predefined_metric`. Poll the returned row's `status` until it reaches `succeeded`. ⚠ Consumes credits per generated insight — see the pricing endpoint.

## Request body

- MetricFailureModeInsightGenerate: Request body for ``POST /metric-failure-mode-insights/generate/``.
  - `project` integer, required: Project ID to generate insights for.
  - `metric` integer, nullable: Custom Metric ID (omit for predefined metric).
  - `predefined_metric` integer, nullable: PredefinedMetric ID (omit for custom metric).
  - `metric_name` string, required: Metric display name — must match call_log.evaluation.metrics[].name.
  - `window_days` integer: Deprecated — audits now always use the last 24 hours.
  - `max_calls` integer, nullable: Upper-bound ceiling on failing calls fed to the agent. Omit to audit every failing call in the 24h window up to 500. If the window exceeds the cap a random sample is taken.

## Response `200`

- MetricFailureModeInsightGenerate: Request body for ``POST /metric-failure-mode-insights/generate/``.
  - `project` integer, required: Project ID to generate insights for.
  - `metric` integer, nullable: Custom Metric ID (omit for predefined metric).
  - `predefined_metric` integer, nullable: PredefinedMetric ID (omit for custom metric).
  - `metric_name` string, required: Metric display name — must match call_log.evaluation.metrics[].name.
  - `window_days` integer: Deprecated — audits now always use the last 24 hours.
  - `max_calls` integer, nullable: Upper-bound ceiling on failing calls fed to the agent. Omit to audit every failing call in the 24h window up to 500. If the window exceeds the cap a random sample is taken.

## Changes

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

[Operation history](https://skmtc.dev/cekura/apis/cekura-api/changes/observability/v1/metric-failure-mode-insights/generate/post.md)

---

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