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

# Get transcription status

> Poll a transcription job until it's completed or failed. Completed jobs carry the text and timestamped segments.



## OpenAPI

````yaml openapi.yaml GET /transcribe/status
openapi: 3.1.0
info:
  title: Importly API
  version: 1.0.0
  summary: Download media, get transcripts, and read metadata from a URL.
  description: >
    Importly turns a public media URL (YouTube, TikTok, podcasts and more) into
    a downloadable file,

    a transcript, or metadata.


    Every job is asynchronous. A `POST` returns a `jobId` right away. Then
    either poll the matching

    `/status` endpoint until `status` is `completed` or `failed`, or pass a
    `webhookUrl` and Importly

    posts the result to you when the job succeeds.


    Every response uses one envelope: `{ "success": true, "data": … }` on
    success and

    `{ "success": false, "error": "…" }` on failure. Responses carry
    `X-RateLimit-Limit`,

    `X-RateLimit-Remaining`, `X-RateLimit-Reset` (Unix time in ms) and
    `X-RateLimit-Window` headers.


    Billing is pay-as-you-go from a credit balance. New accounts get $3.00 in
    free credits, no card required.
  contact:
    name: Importly support
    email: support@importly.io
    url: https://www.importly.io/docs
servers:
  - url: https://api.importly.io
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Media
    description: Download video or audio from a URL.
  - name: Transcripts
    description: Turn a media URL into text with timestamped segments.
  - name: Metadata
    description: >-
      Read a URL's title, duration, thumbnail, formats and more without
      downloading the media.
  - name: Account
    description: Your credit balance.
  - name: Account settings
    description: >-
      Stored S3 credentials and speech-to-text provider keys. These calls carry
      secrets, so the docs playground is off for them.
  - name: Webhooks
    description: Requests Importly sends to your `webhookUrl` when a job completes.
paths:
  /transcribe/status:
    get:
      tags:
        - Transcripts
      summary: Get transcription status
      description: >
        Returns the state of a transcription job. Poll it until `status` is
        `completed` (the `result` holds the

        transcript) or `failed` (`message`, usually a `code`, and for
        `TRANSCRIPTION_PROVIDER_REQUIRED` a `quote`). Free.
      operationId: getTranscriptionStatus
      parameters:
        - $ref: '#/components/parameters/JobId'
      responses:
        '200':
          description: >-
            The job's current state. A failed job still returns 200, with
            `status` set to `failed`.
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    $ref: '#/components/schemas/TranscriptionStatus'
              examples:
                completed:
                  summary: Completed from captions
                  value:
                    success: true
                    data:
                      jobId: 95be812f-4a2c-410a-9fcb-3ca5b445cc44
                      status: completed
                      result:
                        text: >-
                          All right, so here we are, in front of the elephants

                          the cool thing about these guys is that they have
                          really...

                          really really long trunks

                          and that's cool

                          (baaaaaaaaaaahhh!!)

                          and that's pretty much all there is to say
                        source: platform_captions
                        language: en
                        duration: 19
                        data:
                          segments:
                            - start: 1.2
                              end: 3.36
                              text: >-
                                All right, so here we are, in front of the
                                elephants
                            - start: 5.318
                              end: 7.974
                              text: >-
                                the cool thing about these guys is that they
                                have really...
                            - start: 7.974
                              end: 12.616
                              text: really really long trunks
                            - start: 12.616
                              end: 14.367
                              text: and that's cool
                            - start: 14.421
                              end: 15.733
                              text: (baaaaaaaaaaahhh!!)
                            - start: 16.881
                              end: 18.881
                              text: and that's pretty much all there is to say
                        costInDollars: 0.01
                running:
                  summary: Still running
                  value:
                    success: true
                    data:
                      jobId: 95be812f-4a2c-410a-9fcb-3ca5b445cc44
                      status: running
                providerRequired:
                  summary: Failed, no captions and no provider
                  value:
                    success: true
                    data:
                      jobId: 95be812f-4a2c-410a-9fcb-3ca5b445cc44
                      status: failed
                      message: >-
                        This video has no captions. Add "provider": "importly"
                        to transcribe it with AI speech-to-text — this 12-min
                        video would cost $0.24 from your credits ($0.02/min). Or
                        bring your own key (deepgram, openai, assemblyai) at
                        $0.01/min.
                      code: TRANSCRIPTION_PROVIDER_REQUIRED
                      documentationUrl: >-
                        https://www.importly.io/docs/errors/transcription-provider-required
                      quote:
                        provider: importly
                        estimatedMinutes: 12
                        estimatedCostDollars: 0.24
        '400':
          $ref: '#/components/responses/MissingJobId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/JobNotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    JobId:
      name: id
      in: query
      required: true
      description: The `jobId` returned when you started the job.
      schema:
        type: string
        format: uuid
      example: a824760e-ece1-4415-8838-ce2a7785ea6b
  schemas:
    TranscriptionStatus:
      type: object
      required:
        - jobId
        - status
      properties:
        jobId:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/JobStatusValue'
        result:
          $ref: '#/components/schemas/TranscriptFields'
        message:
          type: string
          description: Only when `failed`. Why the job failed.
        code:
          type: string
          description: >-
            Only when `failed`, usually. A stable error code, e.g.
            `TRANSCRIPTION_PROVIDER_REQUIRED` or `MAX_COST_EXCEEDED`.
        documentationUrl:
          type: string
          format: uri
          description: >-
            Only when `failed` with a known `code`. A page explaining the error
            and how to fix it, e.g.
            `https://www.importly.io/docs/errors/media-unavailable`.
        quote:
          type: object
          description: >-
            With `TRANSCRIPTION_PROVIDER_REQUIRED`, when the duration is known.
            What built-in speech-to-text would cost for this media.
          properties:
            provider:
              type: string
              const: importly
            estimatedMinutes:
              type: integer
            estimatedCostDollars:
              type: number
    JobStatusValue:
      type: string
      enum:
        - queued
        - running
        - completed
        - failed
      description: >-
        `queued` and `running` mean keep polling; `completed` and `failed` are
        final.
    TranscriptFields:
      type: object
      required:
        - text
        - source
      properties:
        text:
          type: string
          description: The full transcript as plain text.
        source:
          type: string
          enum:
            - platform_captions
            - importly
            - assemblyai
            - deepgram
            - openai
          description: Where the transcript came from.
        language:
          type:
            - string
            - 'null'
        duration:
          type:
            - number
            - 'null'
          description: Media length in seconds.
        data:
          type: object
          description: Timestamped segments, plus any extra fields your provider returns.
          properties:
            segments:
              type: array
              items:
                $ref: '#/components/schemas/TranscriptSegment'
        costInDollars:
          type: number
          description: What the transcription cost.
        downloadCostInDollars:
          type: number
          description: Speech-to-text only. The audio download's share of the cost.
    Error:
      type: object
      required:
        - success
        - error
        - code
      properties:
        success:
          type: boolean
          const: false
        error:
          type: string
          description: What went wrong, in plain English.
        code:
          type: string
          description: >
            A stable, machine-readable error code: `UNAUTHORIZED`,
            `INSUFFICIENT_BALANCE`, `RATE_LIMITED`,

            `INVALID_URL`, `INVALID_REQUEST`, `NOT_FOUND` or `INTERNAL_ERROR`.
          examples:
            - INVALID_URL
        documentationUrl:
          type: string
          format: uri
          description: A page explaining this error and how to fix it.
          examples:
            - https://www.importly.io/docs/errors/invalid-url
    RateLimitError:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            limit:
              type: integer
              description: Requests allowed per window.
            remaining:
              type: integer
              description: Requests left in the window.
            reset:
              type: integer
              description: When the window resets, as Unix time in milliseconds.
            retryAfter:
              type: integer
              description: Seconds to wait before retrying.
            endpoint:
              type: string
              description: The rate-limit bucket the request counted against.
            concurrentLimit:
              type: integer
              description: >-
                Present instead of `limit` when too many of your jobs are
                already running.
            currentConcurrent:
              type: integer
              description: Present with `concurrentLimit`.
    TranscriptSegment:
      type: object
      properties:
        start:
          type: number
          description: Start time in seconds.
        end:
          type: number
          description: End time in seconds.
        text:
          type: string
  responses:
    MissingJobId:
      description: The `id` query parameter is missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error: Missing id
            code: INVALID_REQUEST
            documentationUrl: https://www.importly.io/docs/errors/invalid-request
    Unauthorized:
      description: The API key is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingHeader:
              summary: No Authorization header
              value:
                success: false
                error: >-
                  Missing or invalid Authorization header. Must be in format:
                  Bearer YOUR_API_KEY
                code: UNAUTHORIZED
                documentationUrl: https://www.importly.io/docs/errors/unauthorized
            invalidKey:
              summary: Unknown key
              value:
                success: false
                error: Invalid API key
                code: UNAUTHORIZED
                documentationUrl: https://www.importly.io/docs/errors/unauthorized
    JobNotFound:
      description: No job with that `id` belongs to your account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error: Import job not found
            code: NOT_FOUND
            documentationUrl: https://www.importly.io/docs/errors/not-found
    TooManyRequests:
      description: >-
        You hit the hourly rate limit for this endpoint. Wait `retryAfter`
        seconds and retry.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-RateLimit-Window:
          $ref: '#/components/headers/X-RateLimit-Window'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
          example:
            success: false
            error: 'Rate limit exceeded. Limit: 240 requests per 1 h'
            code: RATE_LIMITED
            limit: 240
            remaining: 0
            reset: 1763200000000
            retryAfter: 1800
            endpoint: /import
            documentationUrl: https://www.importly.io/docs/errors/rate-limited
    InternalError:
      description: Unexpected server error. Retry with exponential backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error: Internal server error
            code: INTERNAL_ERROR
            documentationUrl: https://www.importly.io/docs/errors/server-error
  headers:
    X-RateLimit-Limit:
      description: Requests allowed in the current window.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests left in the current window.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: When the window resets, as Unix time in milliseconds.
      schema:
        type: integer
    X-RateLimit-Window:
      description: Window length, e.g. `1 h`.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your API key from the dashboard, sent as `Authorization: Bearer <api
        key>`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.