> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cekura.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Improve Agent Prompt from a Run (async)

> Async version of `runs/improve_prompt/`: launch a background job that proposes prompt improvements based on a single run's transcript and metric outcomes. Returns a `progress_id` — poll `improve_prompt_progress/`.



## OpenAPI

````yaml post /test_framework/v1/runs/improve_prompt_bg/
openapi: 3.1.0
info:
  title: Cekura API
  version: v1
  description: >-
    Complete API documentation for the Cekura platform. This API provides
    endpoints for testing, observing, and evaluating AI voice agents — including
    managing agents, running evaluators, defining metrics, and analyzing call
    quality.
servers:
  - url: https://api.cekura.ai
security: []
paths:
  /test_framework/v1/runs/improve_prompt_bg/:
    post:
      tags:
        - test_framework
      description: Runs improve prompt bg
      operationId: runs-improve-prompt-bg-create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Run'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Run'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Run'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Run'
          description: ''
      security:
        - api_key: []
components:
  schemas:
    Run:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        provider_call_id:
          type: string
          readOnly: true
          description: |

            Call ID from the Assistant provider
            Example: `call_abc123`
        trace_id:
          type: string
          description: >-
            OpenTelemetry trace ID (32-char hex). Set when OTel tracing is
            enabled.
          maxLength: 32
        scenario:
          type:
            - integer
            - 'null'
          readOnly: true
        scenario_name:
          type: string
          readOnly: true
          default: Scenario Deleted
        personality:
          type:
            - integer
            - 'null'
          readOnly: true
          description: Personality this run belongs to
        personality_name:
          type: string
          readOnly: true
          description: Name of the personality this run belongs to
        agent:
          type: integer
          readOnly: true
          description: ID of the agent associated with this run
        result_id:
          type: integer
          readOnly: true
        result_name:
          type: string
          readOnly: true
          description: Name of the result this run belongs to
        expected_outcome_prompt:
          type: string
          readOnly: true
        expected_outcome:
          allOf:
            - $ref: '#/components/schemas/ExpectedOutcome'
          readOnly: true
        evaluation:
          allOf:
            - $ref: '#/components/schemas/Evaluation'
          readOnly: true
          description: Run Evaluation
        rubric:
          oneOf:
            - {}
            - type: 'null'
          readOnly: true
          description: |

            Detailed rubric evaluation data
            Example:
            ```json
            [
                {
                    "metric_id": 100,
                    "metric_name": "Call Quality",
                    "value": 5,
                    "explanation": ["The response was accurate"],
                    "passed": true,
                    "conditions": "score gte 5",
                    "expected_conditions": {"operator": "and", "conditions": [{"field": "score", "op": "gte", "value": 5}]}
                }
            ]
            ```
        transcript:
          type: string
          readOnly: true
          description: >
            Full text transcript of the call.

            Example: 

            ```text

            [00:01] Testing Agent: Hello. 

            [00:02] Main Agent: Hello, how can I help you today?

            [00:03] Testing Agent: Well, I mean, sure. What time exactly are we
            talking about here

            [00:04] Main Agent: 6 PM.

            [00:05] Testing Agent: Great. I'll book that for you. Just a sec.

            [00:06] Main Agent: Okay.

            ```
        transcript_object:
          type: array
          items:
            $ref: '#/components/schemas/RunListTranscriptObject'
          readOnly: true
          description: Transcript object
        duration:
          type: string
          readOnly: true
          description: Duration of the run in MM:SS format
        voice_recording_url:
          type: string
          readOnly: true
          description: URL to access the voice recording of this run
        email_id:
          type:
            - string
            - 'null'
          format: email
          readOnly: true
        status:
          enum:
            - running
            - completed
            - failed
            - pending
            - in_progress
            - evaluating
            - in_queue
            - timeout
            - cancelled
            - scaling_up
          type: string
          description: |-
            * `running` - Running
            * `completed` - Completed
            * `failed` - Failed
            * `pending` - Pending
            * `in_progress` - In Progress
            * `evaluating` - Evaluating
            * `in_queue` - In Queue
            * `timeout` - Timeout
            * `cancelled` - Cancelled
            * `scaling_up` - Scaling Up
          x-spec-enum-id: 623e22fc1eb17833
          readOnly: true
        evaluation_status:
          enum:
            - success
            - failure
            - reviewed_success
            - reviewed_failure
          type: string
          description: |-
            * `success` - Success
            * `failure` - Failure
            * `reviewed_success` - Reviewed Success
            * `reviewed_failure` - Reviewed Failure
          x-spec-enum-id: a5dfbbcee6f2a6ce
        metadata:
          readOnly: true
        success:
          type: boolean
          description: >-
            Whether this run passed its quality evaluation. false means either
            the call failed to connect or an evaluation check did not pass.
            Check `error_message` for connection failures and `evaluation` for
            check results.
        is_reviewed:
          type: boolean
          description: |-
            Whether the call has been reviewed.
            Example: `true` or `false`
        feedback:
          type: string
        timestamp:
          type: string
          format: date-time
          readOnly: true
        executed_at:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
        outbound_number:
          type: string
          readOnly: true
          description: Phone number used to make the outbound call for this run
        inbound_number:
          type: string
          readOnly: true
          description: Phone number used to receive the inbound call for this run
        critical_categories:
          type: array
          items:
            $ref: '#/components/schemas/RunListCriticalCategories'
          readOnly: true
          description: >-
            List of critical evaluation categories and their results for this
            run
        error_message:
          type: string
        scenario_instructions:
          type: string
        run_as_text:
          type: boolean
          readOnly: true
        test_profile_data:
          oneOf:
            - $ref: '#/components/schemas/TestProfileData'
            - type: 'null'
          description: Test Profile
          readOnly: true
        generated_mock_tool_entries:
          type: array
          items:
            type: object
            additionalProperties: {}
          readOnly: true
          description: >-
            Expected mock tool calls for this run's evaluator. Each entry has
            shape {tool_id, tool_name, new_entry: {input, output}}.
        provider_call_details:
          readOnly: true
          description: |

            Details of the call from the provider
        agent_number:
          type:
            - string
            - 'null'
          readOnly: true
          description: Phone number of the agent (only for voice inbound calls)
        testing_channel_index:
          type:
            - integer
            - 'null'
          readOnly: true
          description: The channel index of the testing agent in the audio recording
        run_type:
          type:
            - string
            - 'null'
          readOnly: true
          description: Run Execution Type
    ExpectedOutcome:
      type: object
      properties:
        score:
          type: number
          format: double
          description: Score of the expected outcome
        explanation:
          type: array
          items:
            type: string
            description: Explanation of the expected outcome
        outcome_alignments:
          type: array
          items:
            $ref: '#/components/schemas/OutcomeAlignment'
      required:
        - explanation
        - outcome_alignments
        - score
    Evaluation:
      type: object
      properties:
        metrics:
          type: array
          items:
            $ref: '#/components/schemas/CallLogListSerializerMetricsWithExplanation'
      required:
        - metrics
    RunListTranscriptObject:
      type: object
      properties:
        role:
          type: string
          description: Role of the message
        content:
          type: string
          description: Content of the message
        timestamp:
          type: number
          format: double
          description: Timestamp of the message
      required:
        - content
        - role
        - timestamp
    RunListCriticalCategories:
      type: object
      properties:
        category_id:
          type: integer
          description: Category ID
        category:
          type: string
          description: Category name
        deviation:
          type: number
          format: double
          description: Deviation
        wrongly_marked:
          type: boolean
          description: Whether the category was wrongly marked
        feedback:
          type: string
          description: Feedback
        priority:
          enum:
            - critical
            - non-critical
            - not_a_bug
          type: string
          x-spec-enum-id: 6b5f38576e0a1903
          description: |-
            Priority

            * `critical` - Critical
            * `non-critical` - Non Critical
            * `not_a_bug` - Not A Bug
      required:
        - category
        - category_id
        - deviation
        - feedback
        - priority
        - wrongly_marked
    TestProfileData:
      type: object
      properties:
        id:
          type: integer
          description: Test Profile ID
        name:
          type: string
          description: Test Profile name
        information:
          type: object
          additionalProperties: {}
          description: |

            Information of the test profile
            Example:
            ```json
            {
                "user_name": "John Doe",
                "user_email": "john.doe@example.com",
            }
            ```
      required:
        - id
        - information
        - name
    OutcomeAlignment:
      type: object
      properties:
        outcome:
          type: string
          description: Outcome of the expected outcome
        prompt_part:
          type: string
          description: Prompt part of the expected outcome
        aligned:
          type: boolean
          description: Whether the outcome aligns with the prompt part
      required:
        - aligned
        - outcome
        - prompt_part
    CallLogListSerializerMetricsWithExplanation:
      type: object
      properties:
        id:
          type: integer
          description: Metric ID
        name:
          type: string
          description: Metric name
        type:
          type: string
          description: Metric type
        score:
          type: number
          format: double
          description: Evaluated metric score, Present if metrictype is not enum
        enum:
          type: string
          description: Metric enum, Present if type is enum
        value:
          type: string
          description: Evaluated metric value, Present if metric type is enum
        explanation:
          type: array
          items:
            type: string
            description: Explanation of the metric
        extra:
          type: object
          additionalProperties: {}
          description: Evaluated metric extra data
      required:
        - enum
        - explanation
        - extra
        - id
        - name
        - score
        - type
        - value
  securitySchemes:
    api_key:
      type: apiKey
      name: X-CEKURA-API-KEY
      in: header
      description: >-
        API Key Authentication. It should be included in the header of each
        request.

````