---
title: "Generate simulation run debrief"
method: POST
path: "/v1/simulation/plan/job/{jobId}/debrief"
tags: ["Simulation Run Plan Job"]
---

# Generate simulation run debrief

`POST /v1/simulation/plan/job/{jobId}/debrief`

## Request

- Base URL: `https://api.roark.ai`
- URL: `https://api.roark.ai/v1/simulation/plan/job/{jobId}/debrief`
- Auth: HTTP bearer

Request the written debrief for a settled run: executive summary, failure themes and recommendations.
Runs with graded calls get one automatically, so this is for regenerating one (`regenerate: true`)
or retrying one that failed.

Returns immediately. Generation takes a few minutes: poll GET
/v1/simulation/plan/job/{jobId}/results until `debrief.status` is READY or FAILED.
Without `regenerate`, a debrief that is ready or already being written is returned as-is.

## Path parameters

- `jobId` string, uuid, required: Simulation run plan job ID

## Request body

- GenerateSimulationRunDebriefInput
  - `regenerate` boolean: Generate a new debrief even when a ready one exists. Without it, an existing ready or in-progress debrief is returned as-is.

## Response `202`

The debrief, as requested or as it already stands

- object
  - `data` SimulationRunDebrief, required: The run’s written debrief: executive summary, failure themes and recommendations. Generated automatically when a run with graded calls settles.
    - `debriefId` string, uuid, required
    - `status` 'PENDING' | 'GENERATING' | 'READY' | 'FAILED', required: PENDING and GENERATING while it is written (usually a few minutes), then READY or FAILED.
    - `errorMessage` string, nullable, required
    - `createdAt` string, required
    - `completedAt` string, nullable, required
    - `report` SimulationRunDebriefReport, required
      - `generatedAt` string, required
      - `verdict` 'PASSED' | 'THRESHOLD_FAILED', required
      - `verdictSummary` string, required: One-paragraph verdict, e.g. "Not ready to promote. ..."
      - `executiveSummary` object, required
        - `paragraphs` string[], required
        - `sections` object[], required
          - `heading` string, nullable, required
          - `body` string, required
      - `keyFindings` object[], required
        - `title` string, required
        - `body` string, required
        - `callIds` string[], required: The calls the finding is about.
      - `wentWell` object[], required
        - `title` string, required
        - `body` string, required
        - `callIds` string[], required: The calls the finding is about.
      - `themes` object[], required: Failure themes, clustered across the run’s failing calls.
        - `slug` string, required
        - `title` string, required
        - `severity` 'HIGH' | 'MEDIUM' | 'LOW', required
        - `impact` 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW', nullable, required
        - `prevalence` 'WIDESPREAD' | 'RECURRING' | 'ISOLATED', nullable, required
        - `lifecycle` 'NEW' | 'PERSISTENT' | 'IMPROVING' | 'FIXED', nullable, required
        - `affectedCallCount` integer, required
        - `totalCallCount` integer, required
        - `checkNames` string[], required
        - `rootCauseChannel` 'PROMPT' | 'VOICE_CONFIG' | 'STT' | 'SPEECH_MODEL' | 'LLM_MODEL' | 'INFRA' | 'EXTERNAL', nullable, required
        - `analysis` string, required
        - `callIds` string[], required
      - `recommendations` object[], required
        - `order` integer, required
        - `title` string, required
        - `body` string, required
        - `severity` 'HIGH' | 'MEDIUM' | 'LOW', nullable, required
        - `channel` 'PROMPT' | 'VOICE_CONFIG' | 'STT' | 'SPEECH_MODEL' | 'LLM_MODEL' | 'INFRA' | 'EXTERNAL', nullable, required
        - `currentText` string, nullable, required: For a prompt fix: the text to replace.
        - `suggestedText` string, nullable, required: For a prompt fix: the replacement.
        - `themeSlugs` string[], required
      - `trend` object, nullable, required: The checks against the previous run, as of generation.
        - `baselineRunPlanJobId` string, required
        - `baselineRunNumber` integer, nullable, required
        - `rows` object[], required
          - `checkName` string, required
          - `previousPassRate` number, nullable, required
          - `currentPassRate` number, nullable, required
          - `lifecycle` 'NEW' | 'PERSISTENT' | 'IMPROVING' | 'FIXED', nullable, required

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Simulation run not found
- `409`: The run has not finished yet
- `429`: Too Many Requests
- `500`: Internal Server Error

## Changes

> 187 revisions in range; 1 not diffed.

- **2026-10-11** `776a680ac9a5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/simulation/plan/job/:jobId/debrief/post.md)

---

[API](https://skmtc.dev/roarkhq/apis/roark-analytics-api.md) - [All operations](https://skmtc.dev/roarkhq/apis/roark-analytics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roarkhq/apis/roark-analytics-api/revisions/1a91a5c90e44?raw)