---
title: "POST /observability/v1/agent-improvement-sessions/"
method: POST
path: "/observability/v1/agent-improvement-sessions/"
tags: ["observability"]
---

# POST /observability/v1/agent-improvement-sessions/

`POST /observability/v1/agent-improvement-sessions/`

## Request

- Base URL: `https://api.cekura.ai`
- URL: `https://api.cekura.ai/observability/v1/agent-improvement-sessions/`
- Auth: one of:
  - API key in header `X-CEKURA-API-KEY`
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer

Create + poll "Improve Agent" sessions from Insights or evaluators.

``create`` resolves the target agent from Insight call logs, simulation
runs, or selected evaluator scenarios. It validates a VAPI / ElevenLabs
provider key and opens Claude Agent SDK runs in product chat. Call-log
sessions generate evaluators in one sandbox and self-improve in another;
run and scenario sessions reuse existing evaluators directly.

``retrieve`` / ``list`` are read-only poll surfaces. Runtime checkpoints
advance the workflow and persist the status returned to the frontend.

## Request body

- AgentImprovementSession: Read view of an Improve-Agent session — what the frontend polls to track progress. `provider_key` and other secrets are never serialized. The raw `proposal` (full prompt bodies + applied diff values) stays server-side; the API exposes a trimmed `proposal_summary` instead.
  - `id` integer
  - `project` integer, nullable
  - `agent` integer, nullable
  - `agent_name` string
  - `provider` string
  - `source` 'call_log' | 'scenario' | 'run': * `call_log` - Call Log * `scenario` - Scenario * `run` - Run
  - `current_phase` string
  - `insights` unknown
  - `call_log_ids` unknown
  - `run_ids` unknown
  - `scenario_ids` unknown
  - `status` 'pending' | 'running' | 'succeeded' | 'failed' | 'no_improvement' | 'cancelled': * `pending` - Pending * `running` - Running * `succeeded` - Succeeded * `failed` - Failed * `no_improvement` - No Improvement * `cancelled` - Cancelled
  - `stage` 'setup' | 'scenario_generation' | 'reproduce' | 'force' | 'baseline_run' | 'propose' | 'apply' | 'verify_run' | 'finalize' | 'null', nullable: * `setup` - Setup * `scenario_generation` - Scenario Generation * `reproduce` - Reproduce * `force` - Force * `baseline_run` - Baseline Run * `propose` - Propose * `apply` - Apply * `verify_run` - Verify Run * `finalize` - Finalize
  - `stage_status` 'running' | 'waiting' | 'waiting_input' | 'done' | 'failed' | 'null', nullable: * `running` - Running * `waiting` - Waiting * `waiting_input` - Waiting Input * `done` - Done * `failed` - Failed
  - `stage_started_at` string, date-time, nullable
  - `stage_history` unknown
  - `baseline_result` integer, nullable
  - `baseline_source_result` integer, nullable
  - `verify_result` integer, nullable
  - `metric_delta` unknown
  - `proposal_summary` object, nullable
  - `iteration` integer
  - `iteration_history` unknown
  - `failing_scenario_ids` unknown
  - `rounds_since_improvement` integer
  - `best_iteration` integer, nullable
  - `best_score` number, double, nullable
  - `pending_question` unknown
  - `reproduction` object: Reproduction evidence, through the pipeline's own whitelist. Counts, rates and customer-facing field labels only — no configuration values, and no raw provider dot-paths.
  - `labs_metrics` object[]
  - `question_answers` unknown
  - `scenario_edit_proposals` unknown
  - `user_guidance` object[]
  - `parent_session` integer, nullable
  - `conversation_id` string, uuid, nullable
  - `message_id` string, uuid, nullable
  - `error_message` string
  - `failure_kind` string
  - `summary_json` unknown
  - `slack_notification_status` 'not_attempted' | 'sending' | 'sent' | 'skipped_no_channel' | 'failed' | 'held': * `not_attempted` - Not Attempted * `sending` - Sending * `sent` - Sent * `skipped_no_channel` - Skipped No Channel * `failed` - Failed * `held` - Held
  - `routed_to` string
  - `slack_channel_id` string
  - `slack_message_ts` string
  - `slack_message_text` string
  - `slack_error` string
  - `promoted_at` string, date-time, nullable
  - `promoted_by` integer, nullable
  - `promoted_by_email` string, nullable
  - `promotion_summary` object, nullable
  - `clone_state` object
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Response `201`

- AgentImprovementSession: Read view of an Improve-Agent session — what the frontend polls to track progress. `provider_key` and other secrets are never serialized. The raw `proposal` (full prompt bodies + applied diff values) stays server-side; the API exposes a trimmed `proposal_summary` instead.
  - `id` integer
  - `project` integer, nullable
  - `agent` integer, nullable
  - `agent_name` string
  - `provider` string
  - `source` 'call_log' | 'scenario' | 'run': * `call_log` - Call Log * `scenario` - Scenario * `run` - Run
  - `current_phase` string
  - `insights` unknown
  - `call_log_ids` unknown
  - `run_ids` unknown
  - `scenario_ids` unknown
  - `status` 'pending' | 'running' | 'succeeded' | 'failed' | 'no_improvement' | 'cancelled': * `pending` - Pending * `running` - Running * `succeeded` - Succeeded * `failed` - Failed * `no_improvement` - No Improvement * `cancelled` - Cancelled
  - `stage` 'setup' | 'scenario_generation' | 'reproduce' | 'force' | 'baseline_run' | 'propose' | 'apply' | 'verify_run' | 'finalize' | 'null', nullable: * `setup` - Setup * `scenario_generation` - Scenario Generation * `reproduce` - Reproduce * `force` - Force * `baseline_run` - Baseline Run * `propose` - Propose * `apply` - Apply * `verify_run` - Verify Run * `finalize` - Finalize
  - `stage_status` 'running' | 'waiting' | 'waiting_input' | 'done' | 'failed' | 'null', nullable: * `running` - Running * `waiting` - Waiting * `waiting_input` - Waiting Input * `done` - Done * `failed` - Failed
  - `stage_started_at` string, date-time, nullable
  - `stage_history` unknown
  - `baseline_result` integer, nullable
  - `baseline_source_result` integer, nullable
  - `verify_result` integer, nullable
  - `metric_delta` unknown
  - `proposal_summary` object, nullable
  - `iteration` integer
  - `iteration_history` unknown
  - `failing_scenario_ids` unknown
  - `rounds_since_improvement` integer
  - `best_iteration` integer, nullable
  - `best_score` number, double, nullable
  - `pending_question` unknown
  - `reproduction` object: Reproduction evidence, through the pipeline's own whitelist. Counts, rates and customer-facing field labels only — no configuration values, and no raw provider dot-paths.
  - `labs_metrics` object[]
  - `question_answers` unknown
  - `scenario_edit_proposals` unknown
  - `user_guidance` object[]
  - `parent_session` integer, nullable
  - `conversation_id` string, uuid, nullable
  - `message_id` string, uuid, nullable
  - `error_message` string
  - `failure_kind` string
  - `summary_json` unknown
  - `slack_notification_status` 'not_attempted' | 'sending' | 'sent' | 'skipped_no_channel' | 'failed' | 'held': * `not_attempted` - Not Attempted * `sending` - Sending * `sent` - Sent * `skipped_no_channel` - Skipped No Channel * `failed` - Failed * `held` - Held
  - `routed_to` string
  - `slack_channel_id` string
  - `slack_message_ts` string
  - `slack_message_text` string
  - `slack_error` string
  - `promoted_at` string, date-time, nullable
  - `promoted_by` integer, nullable
  - `promoted_by_email` string, nullable
  - `promotion_summary` object, nullable
  - `clone_state` object
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Changes

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

[Operation history](https://skmtc.dev/cekura/apis/cekura-api/changes/observability/v1/agent-improvement-sessions/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)