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

# Get Transcription

> Retrieve the full details of a single transcription, including conversation, summary, extracted fields, and evaluation breakdown.

<Info>
  For the full Transcription data model, see [Transcription](/core/transcription).
</Info>

<Note>
  The response structure varies by `status`. See [Transcription status](/core/transcription#status).
</Note>

<Note>
  `summary`, `fields`, and `conversation` are `null` if those features were not enabled in the [Configuration](/core/configuration) used for this transcription.
</Note>

<Note>
  Returns `404` if the transcription is not found.
</Note>

<Tip>
  For the evaluation `breakdown` structure and criterion types (`boolean`, `scale`, `strict`), see [Evaluator](/core/evaluator).
</Tip>


## OpenAPI

````yaml api-reference/openapi-transcriptions.json POST /get-transcription
openapi: 3.1.0
info:
  title: Heify API — Transcriptions
  description: Endpoints for submitting, retrieving, and managing Transcriptions.
  version: 1.0.0
servers:
  - url: https://api.heify.com
security:
  - apiKeyAuth: []
paths:
  /get-transcription:
    post:
      summary: Get Transcription
      description: >-
        Retrieves full details for a single transcription, including
        conversation, summary, extracted fields, and the complete evaluation
        breakdown.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetTranscriptionRequest'
            examples:
              GetTranscription:
                summary: Get a transcription by ID
                value:
                  transcription_id: e6b7d4ce-c63d-42df-86a8-c3fabe203b2a
      responses:
        '200':
          description: >-
            Transcription retrieved successfully. Response shape varies by
            `status` — see schema.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSingleTranscriptionResponse'
              examples:
                CompletedWithEvaluation:
                  summary: Completed transcription with evaluation
                  value:
                    data:
                      transcription_id: e6b7d4ce-c63d-42df-86a8-c3fabe203b2a
                      status: COMPLETED
                      configuration_id: 3b8006ad-b1a2-464b-9a6b-79dcd45c9433
                      configuration_tag: Pitch Analysis DEMO
                      name: null
                      group: null
                      duration: 542.82
                      participant_id: null
                      evaluator_id: 2abb5563-dd64-47bb-bb17-94252e168b06
                      participant_tag: null
                      evaluator_tag: pitch temporal
                      details:
                        language: en
                        num_speakers: 4
                        created_at: '2026-03-21T11:22:30.211193+00:00'
                        completed_at: '2026-03-21T11:22:59.737279+00:00'
                        conversation:
                          segments:
                            - text: >-
                                Hi, Sharks. My name is Charlie Green. I'm from
                                Los Angeles, California, and I'm here seeking
                                $300,000 for 5% equity in my company, Ramento.
                              speaker: SPEAKER_00
                            - text: So, what does it cost to do this project?
                              speaker: SPEAKER_01
                        summary: null
                        fields:
                          fields:
                            - name: requested_amount
                              value: 300000
                            - name: deal_accepted
                              value: true
                            - name: product_name
                              value: Ramento
                            - name: reported_profit
                              value: null
                        evaluation:
                          score: 52.8
                          critical_fail: false
                          status: COMPLETED
                          breakdown:
                            evaluator_id: 2abb5563-dd64-47bb-bb17-94252e168b06
                            evaluator_tag: pitch temporal
                            generated_at: '2026-03-21T11:22:59.601049+00:00'
                            language_used: es
                            final_score: 52.8
                            critical_fail_triggered: false
                            summary_feedback: >-
                              ### Visión General


                              El pitch ha obtenido una calificación de
                              52.8/100...
                            results:
                              - criteria_id: 2faa4a20-7445-4beb-a09e-2af26872dba3
                                name: Saludo Corporativo inicial
                                type: boolean
                                max_weight: 34
                                score_raw_ai: 0
                                score_obtained: 0
                                status: FAIL
                                reasoning: >-
                                  El pitch no comienza con la presentación
                                  formal requerida.
                                quote: Hi, Sharks. My name is Charlie Green...
                                feedback: >-
                                  Es fundamental iniciar el pitch con una
                                  presentación clara y formal.
                              - criteria_id: 5718a64e-43e6-4959-90a6-19946b44249c
                                name: Escucha Activa
                                type: scale
                                max_weight: 33
                                score_raw_ai: 4
                                score_obtained: 26.4
                                status: PASS
                                reasoning: El emprendedor demuestra buena escucha activa.
                                quote: >-
                                  That's exactly the way the product is designed
                                  today.
                                feedback: null
                Failed:
                  summary: Failed transcription
                  value:
                    data:
                      transcription_id: 1a2b3c4d-e5f6-7890-1234-567890abcdef
                      status: FAILED
                      details:
                        message: Audio file format not supported.
                        code: 400
                        failed_at: '2026-03-20T22:01:00+00:00'
components:
  schemas:
    GetTranscriptionRequest:
      type: object
      properties:
        transcription_id:
          type: string
          format: uuid
          description: The unique identifier of the transcription to retrieve.
      required:
        - transcription_id
    GetSingleTranscriptionResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/TranscriptionDetailObject'
    TranscriptionDetailObject:
      oneOf:
        - title: COMPLETED
          type: object
          description: A completed transcription with full details.
          properties:
            transcription_id:
              type: string
              format: uuid
            status:
              type: string
              enum:
                - COMPLETED
            configuration_id:
              type: string
              format: uuid
              nullable: true
            configuration_tag:
              type: string
              nullable: true
            duration:
              type: number
              nullable: true
              description: Duration in seconds.
            group:
              type: string
              nullable: true
              enum:
                - PENDING_REVIEW
                - UNDER_REVIEW
                - ARCHIVED
                - null
              description: Review workflow group.
            name:
              type: string
              nullable: true
            participant_id:
              type: string
              nullable: true
            evaluator_id:
              type: string
              nullable: true
            participant_tag:
              type: string
              nullable: true
            evaluator_tag:
              type: string
              nullable: true
            details:
              $ref: '#/components/schemas/TranscriptionFullSuccessDetails'
          required:
            - transcription_id
            - status
            - details
        - title: FAILED
          type: object
          description: A failed transcription.
          properties:
            transcription_id:
              type: string
              format: uuid
            status:
              type: string
              enum:
                - FAILED
            details:
              $ref: '#/components/schemas/TranscriptionErrorDetails'
          required:
            - transcription_id
            - status
            - details
        - title: IN_PROGRESS
          type: object
          description: >-
            An in-progress transcription. Same structure as COMPLETED but all
            `details` fields are `null` while processing is ongoing.
          properties:
            transcription_id:
              type: string
              format: uuid
            status:
              type: string
              enum:
                - IN_PROGRESS
            configuration_id:
              type: string
              format: uuid
              nullable: true
            configuration_tag:
              type: string
              nullable: true
            duration:
              type: number
              nullable: true
            group:
              type: string
              nullable: true
            name:
              type: string
              nullable: true
            participant_id:
              type: string
              format: uuid
              nullable: true
            evaluator_id:
              type: string
              format: uuid
              nullable: true
            participant_tag:
              type: string
              nullable: true
            evaluator_tag:
              type: string
              nullable: true
            details:
              $ref: '#/components/schemas/TranscriptionFullSuccessDetails'
          required:
            - transcription_id
            - status
            - details
    TranscriptionFullSuccessDetails:
      type: object
      description: Full details for a completed transcription.
      properties:
        language:
          type: string
          nullable: true
          description: Detected language code.
        num_speakers:
          type: number
          nullable: true
          description: Number of unique speakers identified.
        created_at:
          type: string
          format: date-time
          description: Submission timestamp (ISO 8601).
        completed_at:
          type: string
          format: date-time
          nullable: true
          description: Completion timestamp (ISO 8601).
        summary:
          $ref: '#/components/schemas/SummaryContent'
          nullable: true
          description: >-
            AI-generated summary. `null` if `summary` was not enabled in the
            configuration.
        conversation:
          $ref: '#/components/schemas/ConversationContent'
          nullable: true
          description: Speaker-separated transcript segments.
        fields:
          $ref: '#/components/schemas/FieldsContent'
          nullable: true
          description: >-
            Extracted structured data. `null` if no extraction fields were
            configured.
        evaluation:
          $ref: '#/components/schemas/EvaluationSummary'
          nullable: true
          description: QA evaluation result. `null` if no evaluator was used.
      required:
        - created_at
    TranscriptionErrorDetails:
      type: object
      description: Details for a failed transcription.
      properties:
        message:
          type: string
          description: Human-readable error description.
        code:
          type: integer
          description: Internal error code.
        failed_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when the failure occurred.
      required:
        - message
        - code
    SummaryContent:
      type: object
      properties:
        summary:
          type: string
          description: AI-generated summary text.
      required:
        - summary
    ConversationContent:
      type: object
      properties:
        segments:
          type: array
          items:
            $ref: '#/components/schemas/ConversationSegment'
      required:
        - segments
    FieldsContent:
      type: object
      properties:
        fields:
          type: array
          items:
            $ref: '#/components/schemas/ExtractedFieldItem'
      required:
        - fields
    EvaluationSummary:
      type: object
      properties:
        score:
          type: number
          nullable: true
          description: Overall quality score (0–100).
        critical_fail:
          type: boolean
          description: Whether a `strict` criterion was triggered.
        status:
          type: string
          nullable: true
          enum:
            - PENDING
            - COMPLETED
            - FAILED
        breakdown:
          $ref: '#/components/schemas/EvaluationBreakdown'
          nullable: true
          description: >-
            Full per-criterion evaluation. Only present when `status` is
            `COMPLETED`.
    ConversationSegment:
      type: object
      properties:
        text:
          type: string
          description: Transcribed text for this segment.
        speaker:
          type: string
          description: Speaker label (e.g. `SPEAKER_00`, `SPEAKER_01`).
      required:
        - text
        - speaker
    ExtractedFieldItem:
      type: object
      properties:
        name:
          type: string
          description: Field name matching the configured extraction field.
        value:
          description: >-
            Extracted value. Type matches the configured field type (`string`,
            `number`, `boolean`, `array`).
      required:
        - name
        - value
    EvaluationBreakdown:
      type: object
      description: Full evaluation breakdown generated by the evaluator.
      properties:
        evaluator_id:
          type: string
          format: uuid
          description: ID of the evaluator used.
        evaluator_tag:
          type: string
          description: Name of the evaluator.
        generated_at:
          type: string
          format: date-time
          description: Timestamp when the evaluation was generated.
        language_used:
          type: string
          description: Language used for the AI-generated feedback (e.g. `es`, `en`).
        final_score:
          type: number
          description: Final score (0–100), identical to `evaluation.score`.
        critical_fail_triggered:
          type: boolean
          description: Whether a `strict` criterion was triggered.
        summary_feedback:
          type: string
          description: >-
            AI-generated Markdown summary of the evaluation with overall
            feedback and action plan.
        results:
          type: array
          description: Per-criterion evaluation results.
          items:
            $ref: '#/components/schemas/CriterionResult'
    CriterionResult:
      type: object
      description: Evaluation result for a single criterion.
      properties:
        criteria_id:
          type: string
          format: uuid
          description: Unique ID of the criterion.
        name:
          type: string
          description: Criterion name.
        type:
          type: string
          enum:
            - boolean
            - scale
            - strict
          description: Criterion type. See [Evaluator](/core/evaluator#criterion-types).
        max_weight:
          type: number
          description: Maximum score contribution of this criterion.
        score_raw_ai:
          type: number
          description: Raw score returned by the AI model.
        score_obtained:
          type: number
          description: Final weighted score obtained.
        status:
          type: string
          enum:
            - PASS
            - FAIL
          description: '`PASS` or `FAIL`.'
        reasoning:
          type: string
          nullable: true
          description: AI explanation for the score.
        quote:
          type: string
          nullable: true
          description: Relevant quote from the transcript that informed the evaluation.
        feedback:
          type: string
          nullable: true
          description: Actionable improvement suggestion for this criterion.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````