> ## Documentation Index > Fetch the complete documentation index at: https://docs.roark.ai/llms.txt > Use this file to discover all available pages before exploring further. # Generate simulation run debrief > 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. ## OpenAPI ````yaml /api-reference/openapi.documented.json post /v1/simulation/plan/job/{jobId}/debrief openapi: 3.1.0 info: title: Roark Analytics API description: >- The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform. version: 1.0.0 servers: - description: Production url: https://api.roark.ai security: - Bearer: [] tags: - name: Agent - name: Agent Endpoint - name: Call - name: Chat - name: Metric - name: Metric Policy - name: Metric Collection Job - name: Customer Flow - name: Customer Flow Edge Case - name: Simulation - name: Simulation Persona - name: Simulation Environment - name: Simulation Scenario - name: Simulation Run Plan - name: Simulation Template - name: Simulation Run Plan Job - name: Simulation Job - name: HTTP Request Definition - name: Webhook - name: Issue - name: Autoimprove - name: Agent Config - name: Knowledge Base - name: Config - name: Organization Project - name: Organization Project Member - name: Organization Project API Key - name: Organization Config - name: CLI Auth - name: Me - name: Project - name: Usage - name: Benchmark - name: Health - name: Prospect Simulation paths: /v1/simulation/plan/job/{jobId}/debrief: post: tags: - Simulation Run Plan Job summary: Generate simulation run debrief description: >- 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. operationId: postV1SimulationPlanJobByJobIdDebrief parameters: - in: path name: jobId schema: type: string format: uuid description: Simulation run plan job ID required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/GenerateSimulationRunDebriefInput' responses: '202': description: The debrief, as requested or as it already stands content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/SimulationRunDebrief' required: - data '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Validation error example: type: validation code: invalid_parameter message: The request was invalid param: email description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication error example: type: authentication code: unauthorized message: Authentication required description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Permission error example: type: forbidden code: permission_denied message: You do not have permission to access this resource description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not found error example: type: not_found code: resource_not_found message: The requested resource could not be found description: Simulation run not found '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Conflict error example: type: conflict code: resource_in_use message: The resource is in use and cannot be deleted description: The run has not finished yet '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Rate limit error example: type: rate_limit code: too_many_requests message: Rate limit exceeded description: Too Many Requests '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Server error example: type: internal code: internal_error message: Internal server error description: Internal Server Error x-codeSamples: - lang: JavaScript source: |- import Roark from '@roarkanalytics/sdk'; const client = new Roark({ bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted }); const response = await client.simulationRunPlanJob.createDebrief( '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', ); console.log(response.data); - lang: Python source: |- import os from roark_analytics import Roark client = Roark( bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"), # This is the default and can be omitted ) response = client.simulation_run_plan_job.create_debrief( job_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", ) print(response.data) components: schemas: GenerateSimulationRunDebriefInput: type: object properties: regenerate: type: boolean default: false description: >- Generate a new debrief even when a ready one exists. Without it, an existing ready or in-progress debrief is returned as-is. SimulationRunDebrief: type: object properties: debriefId: type: string format: uuid status: type: string enum: - PENDING - GENERATING - READY - FAILED description: >- PENDING and GENERATING while it is written (usually a few minutes), then READY or FAILED. errorMessage: type: - string - 'null' createdAt: type: string completedAt: type: - string - 'null' report: oneOf: - $ref: '#/components/schemas/SimulationRunDebriefReport' - type: 'null' description: Present once READY. required: - debriefId - status - errorMessage - createdAt - completedAt - report description: >- The run’s written debrief: executive summary, failure themes and recommendations. Generated automatically when a run with graded calls settles. example: debriefId: 3c2b1a09-8f7e-4d6c-9b5a-4e3d2c1b0a9f status: GENERATING errorMessage: null createdAt: '2026-10-11T14:05:12.000Z' completedAt: null report: null ErrorResponse: type: object properties: type: type: string enum: - validation - authentication - forbidden - not_found - conflict - payment_required - rate_limit - internal description: The error type category examples: - validation - authentication code: type: string description: Machine-readable error code identifier examples: - invalid_parameter - missing_required_field - unauthorized message: type: string description: Human-readable error message examples: - The request was invalid - Authentication required param: type: string description: The parameter that caused the error (if applicable) examples: - email - user_id details: description: Additional error context information required: - type - code - message SimulationRunDebriefReport: type: object properties: generatedAt: type: string verdict: type: string enum: - PASSED - THRESHOLD_FAILED verdictSummary: type: string description: One-paragraph verdict, e.g. "Not ready to promote. ..." executiveSummary: type: object properties: paragraphs: type: array items: type: string sections: type: array items: type: object properties: heading: type: - string - 'null' body: type: string required: - heading - body required: - paragraphs - sections keyFindings: type: array items: type: object properties: title: type: string body: type: string callIds: type: array items: type: string description: The calls the finding is about. required: - title - body - callIds wentWell: type: array items: type: object properties: title: type: string body: type: string callIds: type: array items: type: string description: The calls the finding is about. required: - title - body - callIds themes: type: array items: type: object properties: slug: type: string title: type: string severity: type: string enum: - HIGH - MEDIUM - LOW impact: type: - string - 'null' enum: - CRITICAL - HIGH - MEDIUM - LOW prevalence: type: - string - 'null' enum: - WIDESPREAD - RECURRING - ISOLATED lifecycle: type: - string - 'null' enum: - NEW - PERSISTENT - IMPROVING - FIXED affectedCallCount: type: integer totalCallCount: type: integer checkNames: type: array items: type: string rootCauseChannel: type: - string - 'null' enum: - PROMPT - VOICE_CONFIG - STT - SPEECH_MODEL - LLM_MODEL - INFRA - EXTERNAL analysis: type: string callIds: type: array items: type: string required: - slug - title - severity - impact - prevalence - lifecycle - affectedCallCount - totalCallCount - checkNames - rootCauseChannel - analysis - callIds description: Failure themes, clustered across the run’s failing calls. recommendations: type: array items: type: object properties: order: type: integer title: type: string body: type: string severity: type: - string - 'null' enum: - HIGH - MEDIUM - LOW channel: type: - string - 'null' enum: - PROMPT - VOICE_CONFIG - STT - SPEECH_MODEL - LLM_MODEL - INFRA - EXTERNAL currentText: type: - string - 'null' description: 'For a prompt fix: the text to replace.' suggestedText: type: - string - 'null' description: 'For a prompt fix: the replacement.' themeSlugs: type: array items: type: string required: - order - title - body - severity - channel - currentText - suggestedText - themeSlugs trend: type: - object - 'null' properties: baselineRunPlanJobId: type: string baselineRunNumber: type: - integer - 'null' rows: type: array items: type: object properties: checkName: type: string previousPassRate: type: - number - 'null' minimum: 0 maximum: 100 currentPassRate: type: - number - 'null' minimum: 0 maximum: 100 lifecycle: type: - string - 'null' enum: - NEW - PERSISTENT - IMPROVING - FIXED required: - checkName - previousPassRate - currentPassRate - lifecycle required: - baselineRunPlanJobId - baselineRunNumber - rows description: The checks against the previous run, as of generation. required: - generatedAt - verdict - verdictSummary - executiveSummary - keyFindings - wentWell - themes - recommendations - trend securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.