> ## 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.

# Wait for a Background Job

> Check on a background job using the `progress_id` returned by the endpoint that started it. Waits up to `wait` seconds for the job to finish, then returns its current state; while `status` is `in_progress`, call again with the same id.



## OpenAPI

````yaml get /test_framework/v1/async-jobs/{job_id}/
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/async-jobs/{job_id}/:
    get:
      tags:
        - test_framework
      summary: Wait for a background job to finish
      description: >-
        Check on a background job using the `progress_id` returned by the
        endpoint that started it. Waits up to `wait` seconds for the job to
        finish, then returns its current state; while `status` is `in_progress`,
        call again with the same id.
      operationId: async-jobs-retrieve
      parameters:
        - in: path
          name: job_id
          required: true
          schema:
            type: string
          description: The `progress_id` returned by the endpoint that started the job.
        - in: query
          name: wait
          required: false
          schema:
            type: number
            minimum: 0
            maximum: 55
            default: 25
          description: Seconds to wait for the job to finish. `0` returns immediately.
      responses:
        '200':
          description: Current state of the job. Its fields depend on `job_type`.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AsyncJobEvaluatorGenerationReply'
                  - $ref: '#/components/schemas/AsyncJobInstructionGenerationReply'
                  - $ref: '#/components/schemas/AsyncJobEvaluatorImprovementReply'
                  - $ref: '#/components/schemas/AsyncJobMetricPreviewReply'
                  - $ref: '#/components/schemas/AsyncJobMetricGenerationReply'
                  - $ref: '#/components/schemas/AsyncJobMetricDescriptionReply'
                  - $ref: '#/components/schemas/AsyncJobSimplifyPromptReply'
                  - $ref: '#/components/schemas/AsyncJobEvaluatorsFromCallLogsReply'
                  - $ref: '#/components/schemas/AsyncJobAlertSummaryReply'
        '400':
          description: The job id is unknown, expired or not accessible.
      security:
        - api_key: []
        - oauth2: []
        - supabase_session: []
components:
  schemas:
    AsyncJobEvaluatorGenerationReply:
      title: Evaluator generation
      description: Started by the generate-evaluators endpoint.
      type: object
      properties:
        job_type:
          type: string
          enum:
            - generate_scenarios
        job_id:
          type: string
          description: The job id you polled.
        status:
          type: string
          enum:
            - in_progress
            - needs_clarification
            - completed
            - failed
            - cancelled
          description: >-
            `in_progress`: still running, call again with the same id.
            `needs_clarification`: waiting on your answer. `completed`,
            `failed`, `cancelled`: finished.
        agent_id:
          type: integer
        total_scenarios:
          type: integer
        completed_scenarios:
          type: integer
        failed_scenarios:
          type: integer
        scenarios_list:
          type: array
          items:
            type: object
            description: Full evaluator object, as the evaluators API returns it.
          description: Evaluators generated so far.
        errors:
          type: array
          items: {}
        warnings:
          type: array
          items: {}
        session_id:
          type:
            - integer
            - 'null'
        current_step:
          type: string
        questions:
          type: array
          items:
            type: object
          description: >-
            Only while `status` is `needs_clarification` (dashboard sessions).
            Answer via the generate-clarify-answer endpoint, then poll the same
            id.
        agent_message:
          type: string
          description: Only while `status` is `needs_clarification`.
    AsyncJobInstructionGenerationReply:
      title: Instruction generation
      description: Started by the generate-instructions or improve-instructions endpoint.
      type: object
      properties:
        job_type:
          type: string
          enum:
            - generate_instructions
        job_id:
          type: string
          description: The job id you polled.
        status:
          type: string
          enum:
            - in_progress
            - needs_clarification
            - completed
            - failed
            - cancelled
          description: >-
            `in_progress`: still running, call again with the same id.
            `needs_clarification`: waiting on your answer. `completed`,
            `failed`, `cancelled`: finished.
        agent_id:
          type: integer
        instructions:
          type:
            - string
            - 'null'
        expected_outcome_prompt:
          type:
            - string
            - 'null'
        error:
          type:
            - string
            - 'null'
          description: Why the job failed, when it did.
    AsyncJobEvaluatorImprovementReply:
      title: Evaluator improvement
      description: >-
        Started by the scenario-agent endpoint. To answer a clarification, send
        `session_id` and your reply to that endpoint again; it returns a new job
        id.
      type: object
      properties:
        job_type:
          type: string
          enum:
            - scenario_agent
        job_id:
          type: string
          description: The job id you polled.
        status:
          type: string
          enum:
            - in_progress
            - needs_clarification
            - completed
            - failed
            - cancelled
          description: >-
            `in_progress`: still running, call again with the same id.
            `needs_clarification`: waiting on your answer. `completed`,
            `failed`, `cancelled`: finished.
        session_id:
          type: integer
        mode:
          type: string
        result:
          type:
            - object
            - 'null'
          properties:
            message:
              type: string
            needs_clarification:
              type: boolean
            clarification_questions:
              type: array
              items:
                type: object
            base_extra_instructions:
              type:
                - string
                - 'null'
            extra_instructions_list:
              type: array
              items:
                type: string
            cancelled:
              type: boolean
        error:
          type:
            - string
            - 'null'
          description: Why the job failed, when it did.
    AsyncJobMetricPreviewReply:
      title: Metric preview
      description: Started by the metric preview endpoint.
      type: object
      properties:
        job_type:
          type: string
          enum:
            - metric_preview
        job_id:
          type: string
          description: The job id you polled.
        status:
          type: string
          enum:
            - in_progress
            - needs_clarification
            - completed
            - failed
            - cancelled
          description: >-
            `in_progress`: still running, call again with the same id.
            `needs_clarification`: waiting on your answer. `completed`,
            `failed`, `cancelled`: finished.
        project_id:
          type:
            - integer
            - 'null'
        agent_id:
          type:
            - integer
            - 'null'
        completed:
          type: integer
          description: Items evaluated so far.
        total:
          type: integer
        results:
          type: array
          items:
            type: object
            description: >-
              One per previewed call log (`call_log_id`, `call_id`) or run
              (`run_id`). The verdict is `result`, or `score` / `enum` for
              custom-code metrics.
            properties:
              result:
                description: Verdict for LLM-judge metrics.
              score:
                type: number
              enum:
                type: string
              explanation:
                type: string
              is_relevant:
                type: boolean
              call_log_id:
                type: integer
              call_id:
                type:
                  - string
                  - 'null'
              run_id:
                type: integer
              error:
                type:
                  - string
                  - 'null'
        error:
          type:
            - string
            - 'null'
          description: Why the job failed, when it did.
    AsyncJobMetricGenerationReply:
      title: Metric generation
      description: >-
        Started by the generate-metrics endpoint. The metrics are not saved;
        pass them to Create Metrics in Bulk.
      type: object
      properties:
        job_type:
          type: string
          enum:
            - generate_metrics
        job_id:
          type: string
          description: The job id you polled.
        status:
          type: string
          enum:
            - in_progress
            - needs_clarification
            - completed
            - failed
            - cancelled
          description: >-
            `in_progress`: still running, call again with the same id.
            `needs_clarification`: waiting on your answer. `completed`,
            `failed`, `cancelled`: finished.
        agent_id:
          type: integer
        current_step:
          type: string
        metrics:
          type: array
          items:
            type: object
        error:
          type:
            - string
            - 'null'
          description: Why the job failed, when it did.
    AsyncJobMetricDescriptionReply:
      title: Metric description
      description: Started by the start-async-metric-description endpoint.
      type: object
      properties:
        job_type:
          type: string
          enum:
            - generate_clean_description
        job_id:
          type: string
          description: The job id you polled.
        status:
          type: string
          enum:
            - in_progress
            - needs_clarification
            - completed
            - failed
            - cancelled
          description: >-
            `in_progress`: still running, call again with the same id.
            `needs_clarification`: waiting on your answer. `completed`,
            `failed`, `cancelled`: finished.
        agent_id:
          type: integer
        clean_description:
          type: string
        error:
          type:
            - string
            - 'null'
          description: Why the job failed, when it did.
    AsyncJobSimplifyPromptReply:
      title: Simplify metric prompt
      description: Started by the simplify-metric-prompt endpoint.
      type: object
      properties:
        job_type:
          type: string
          enum:
            - simplify_prompt
        job_id:
          type: string
          description: The job id you polled.
        status:
          type: string
          enum:
            - in_progress
            - needs_clarification
            - completed
            - failed
            - cancelled
          description: >-
            `in_progress`: still running, call again with the same id.
            `needs_clarification`: waiting on your answer. `completed`,
            `failed`, `cancelled`: finished.
        original_prompt:
          type: string
        metric_id:
          type:
            - integer
            - 'null'
        simplified_prompt:
          type: string
        skipped_simplification:
          type: boolean
        error:
          type:
            - string
            - 'null'
          description: Why the job failed, when it did.
    AsyncJobEvaluatorsFromCallLogsReply:
      title: Evaluators from call logs
      description: Started by the create-evaluators-from-call-logs endpoint.
      type: object
      properties:
        job_type:
          type: string
          enum:
            - create_scenarios
        job_id:
          type: string
          description: The job id you polled.
        status:
          type: string
          enum:
            - in_progress
            - needs_clarification
            - completed
            - failed
            - cancelled
          description: >-
            `in_progress`: still running, call again with the same id.
            `needs_clarification`: waiting on your answer. `completed`,
            `failed`, `cancelled`: finished.
        project_id:
          type:
            - integer
            - 'null'
        agent_id:
          type:
            - integer
            - 'null'
        total_scenarios:
          type: integer
        completed_scenarios:
          type: integer
        failed_scenarios:
          type: integer
        scenarios_list:
          type: array
          items: {}
          description: >-
            Evaluator ids while running; full evaluator objects once every call
            log is processed.
        errors:
          type: array
          items:
            type: object
            properties:
              call_log_id:
                type: integer
              error:
                type: object
    AsyncJobAlertSummaryReply:
      title: Alert summary
      description: Started by the alert summarize endpoint.
      type: object
      properties:
        job_type:
          type: string
          enum:
            - alert_review_summary
        job_id:
          type: string
          description: The job id you polled.
        status:
          type: string
          enum:
            - in_progress
            - needs_clarification
            - completed
            - failed
            - cancelled
          description: >-
            `in_progress`: still running, call again with the same id.
            `needs_clarification`: waiting on your answer. `completed`,
            `failed`, `cancelled`: finished.
        alert_id:
          type: integer
        project_id:
          type: integer
        output:
          type: object
          properties:
            headline:
              type: string
            summary:
              type: string
            common_themes:
              type: array
              items:
                type: string
        error:
          type:
            - string
            - 'null'
          description: Why the job failed, when it did.
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: X-CEKURA-API-KEY
      description: >-
        API Key Authentication. It should be included in the header of each
        request.
    oauth2:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth access token issued by Cekura for connected apps.
    supabase_session:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Cekura dashboard session token. Not a customer API credential.

````