---
title: "Get file import"
method: GET
path: "/v1/files/imports/{fileImportId}"
tags: ["Files"]
---

# Get file import

`GET /v1/files/imports/{fileImportId}`

## Request

- Base URL: `https://api.videogen.io`
- URL: `https://api.videogen.io/v1/files/imports/{fileImportId}`
- Auth: HTTP bearer

Returns the current status of a file import started via `POST /v1/files/import-url`, and, once `status` is `succeeded`, the imported file. Poll this endpoint until `status` is `succeeded`, `failed`, or `cancelled`.

## Path parameters

- `fileImportId` string, required

## Response `200`

File import status.

- FileUrlImport
  - `fileImportId` string, required: Opaque file import id (e.g. `vg_fimp_...`) matching the original request.
  - `status` 'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled', required: Base lifecycle status for asynchronous jobs. `pending` and `running` are in-progress; `succeeded`, `failed`, and `cancelled` are terminal. Workflows and tools additionally support `awaiting_approval` through their specific status schemas.
  - `progressPercentage` number, required: Completion progress for the current attempt (0-100). Always `100` when `status` is `succeeded`.
  - `attemptIndex` integer, required: Zero-based index of the current or most recent import attempt.
  - `fileId` string, nullable, required: Id of the imported video file (e.g. `vg_file_...`). Always present as a field; `null` until `status` is `succeeded`.
  - `file` FileInfo, required: Metadata for a generated file. Obtain ids from tool results or `GET /v1/files`.
    - `fileId` string, required: File id (e.g. `vg_file_...`).
    - `type` 'IMAGE' | 'VIDEO' | 'AUDIO' | 'PDF' | 'SLIDESHOW' | 'TEXT' | 'LOTTIE': File type. `TEXT` covers plain-text and editor-interchange documents; `LOTTIE` is a JSON animation.
    - `scope` 'GLOBAL' | 'PROJECT' | 'EXPORT' | 'TEMPORARY' | 'ENTITY', required: File scope. - `GLOBAL`: user-uploaded or standalone generated files that persist indefinitely. - `PROJECT`: project-specific files (e.g. text-to-speech clips in a generated project). - `EXPORT`: project exports. - `TEMPORARY`: short-lived files guaranteed to be available for 24 hours, after which they may be archived at any time. Not analyzed (no description, transcript, or embedding). - `ENTITY`: files attached to a reusable entity (e.g. a voice sample for an actor), shared across your team.
    - `displayName` string: Display name for the file. For an uploaded file, analysis may replace the original filename with a short name based on the content.
    - `description` string, nullable
    - `durationSeconds` number, nullable: Duration in seconds for video and audio files. Null for images.
    - `transcript` Transcript: A transcript of an audio file, as timed words in order.
      - `languageCode` string, nullable: Optional BCP-47 language code of the spoken audio (e.g. `en`, `es`). Used to tag the transcript's language; omit if unknown.
      - `words` TranscriptWord[], required: The transcript words, sorted by `startSeconds` and non-overlapping. Must contain at least one word.
        - `startSeconds` number, required: Start time of the word in seconds from the beginning of the audio.
        - `endSeconds` number, required: End time of the word in seconds from the beginning of the audio. Must be greater than `startSeconds`.
        - `word` string, required: The spoken word, used verbatim for narration timing and captions.
    - `transcriptText` string, nullable: Plain transcript text for video and audio files, when available. Null for images or when no transcript has been generated.
    - `downloadUrl` string, uri, nullable: Private signed URL for the highest-quality downloadable rendition, provided at the top level for convenience. Valid for 7 days from when it was signed. `null` when the rendition is still processing or the URL has not been signed yet. See `downloadUrlExpiresAt` for the exact expiry and `downloadSource` for the full rendition metadata; call `POST /v1/files/{fileId}/hydrate` to refresh it.
    - `downloadUrlExpiresAt` integer, nullable: Seconds since epoch (Unix timestamp) when `downloadUrl` expires. `null` when `downloadUrl` is null.
    - `thumbnailUrl` string, uri, nullable: Private signed URL for the thumbnail rendition, provided at the top level for convenience. Valid for 7 days from when it was signed. `null` for file types that have no thumbnail (e.g. audio) or when it has not been signed yet. See `thumbnailSource` for the full rendition metadata.
    - `thumbnailUrlExpiresAt` integer, nullable: Seconds since epoch (Unix timestamp) when `thumbnailUrl` expires. `null` when `thumbnailUrl` is null.
    - `thumbnailSource` FileSource: A rendition source for a file (e.g. thumbnail, preview, download). Contains a signed URL and metadata.
      - `status` 'pending' | 'ready' | 'failed' | 'skipped', required: `pending`: asset is still processing or has not been hydrated yet. `ready`: signed URL is available. `failed`: rendition generation failed. `skipped`: rendition does not apply to this file type (e.g. thumbnail for audio).
      - `url` string, nullable: Signed URL. Present when status is `ready` and file has been recently hydrated. If missing, call the hydrate endpoint.
      - `expiresAt` integer, nullable: Seconds since epoch (Unix timestamp) when the signed URL expires.
      - `width` integer, nullable: Rendition width in pixels, when known.
      - `height` integer, nullable: Rendition height in pixels, when known.
      - `fileBytes` integer, nullable: File size in bytes, when known.
    - `previewSource` FileSource: A rendition source for a file (e.g. thumbnail, preview, download). Contains a signed URL and metadata.
      - `status` 'pending' | 'ready' | 'failed' | 'skipped', required: `pending`: asset is still processing or has not been hydrated yet. `ready`: signed URL is available. `failed`: rendition generation failed. `skipped`: rendition does not apply to this file type (e.g. thumbnail for audio).
      - `url` string, nullable: Signed URL. Present when status is `ready` and file has been recently hydrated. If missing, call the hydrate endpoint.
      - `expiresAt` integer, nullable: Seconds since epoch (Unix timestamp) when the signed URL expires.
      - `width` integer, nullable: Rendition width in pixels, when known.
      - `height` integer, nullable: Rendition height in pixels, when known.
      - `fileBytes` integer, nullable: File size in bytes, when known.
    - `downloadSource` FileSource: A rendition source for a file (e.g. thumbnail, preview, download). Contains a signed URL and metadata.
      - `status` 'pending' | 'ready' | 'failed' | 'skipped', required: `pending`: asset is still processing or has not been hydrated yet. `ready`: signed URL is available. `failed`: rendition generation failed. `skipped`: rendition does not apply to this file type (e.g. thumbnail for audio).
      - `url` string, nullable: Signed URL. Present when status is `ready` and file has been recently hydrated. If missing, call the hydrate endpoint.
      - `expiresAt` integer, nullable: Seconds since epoch (Unix timestamp) when the signed URL expires.
      - `width` integer, nullable: Rendition width in pixels, when known.
      - `height` integer, nullable: Rendition height in pixels, when known.
      - `fileBytes` integer, nullable: File size in bytes, when known.
    - `hlsSource` FileSource: A rendition source for a file (e.g. thumbnail, preview, download). Contains a signed URL and metadata.
      - `status` 'pending' | 'ready' | 'failed' | 'skipped', required: `pending`: asset is still processing or has not been hydrated yet. `ready`: signed URL is available. `failed`: rendition generation failed. `skipped`: rendition does not apply to this file type (e.g. thumbnail for audio).
      - `url` string, nullable: Signed URL. Present when status is `ready` and file has been recently hydrated. If missing, call the hydrate endpoint.
      - `expiresAt` integer, nullable: Seconds since epoch (Unix timestamp) when the signed URL expires.
      - `width` integer, nullable: Rendition width in pixels, when known.
      - `height` integer, nullable: Rendition height in pixels, when known.
      - `fileBytes` integer, nullable: File size in bytes, when known.
    - `isPublicPreviewEnabled` boolean: Whether public preview is enabled for this file. When true, `staticPublicPreviewSource` is populated for all file types. For video and audio, `publicHlsUrl` and `publicPlaybackId` are also populated once embed streaming is ready.
    - `staticPublicPreviewSource` FileSource: A rendition source for a file (e.g. thumbnail, preview, download). Contains a signed URL and metadata.
      - `status` 'pending' | 'ready' | 'failed' | 'skipped', required: `pending`: asset is still processing or has not been hydrated yet. `ready`: signed URL is available. `failed`: rendition generation failed. `skipped`: rendition does not apply to this file type (e.g. thumbnail for audio).
      - `url` string, nullable: Signed URL. Present when status is `ready` and file has been recently hydrated. If missing, call the hydrate endpoint.
      - `expiresAt` integer, nullable: Seconds since epoch (Unix timestamp) when the signed URL expires.
      - `width` integer, nullable: Rendition width in pixels, when known.
      - `height` integer, nullable: Rendition height in pixels, when known.
      - `fileBytes` integer, nullable: File size in bytes, when known.
    - `publicHlsUrl` string, nullable: Public HLS streaming URL for video and audio. Only present when `isPublicPreviewEnabled` is true and embed streaming is ready. Prefer `publicPlaybackId` with `@videogen/player` for embeds.
    - `publicPlaybackId` string, nullable: Encoded public playback id (e.g. `vg_play_...`) for video and audio embeds. Pass this to `@videogen/player` or `@videogen/player-react`. Only present when `isPublicPreviewEnabled` is true and embed streaming is ready. For a permanent direct file URL (any type), use `staticPublicPreviewSource` instead.
    - `sourceToolType` string: Tool type that generated this file (e.g. `GENERATE_IMAGE`, `TEXT_TO_SPEECH`). Only present when the file was created by a tool execution.
    - `sourceToolExecutionId` string: Execution id of the tool call that generated this file (e.g. `vg_tool_...`). Only present when the file was created by a tool execution.
    - `fileAnalysisMetadata` FileAnalysisMetadata: Background analysis state for a file. Background analysis populates `description`, `transcript`, `durationSeconds`, and the search embedding after a file is uploaded or generated; this object lets you render a progress indicator while it runs (and skip rendering once it's done).
      - `analysisLoadingState` 'UNATTEMPTED' | 'LOADING' | 'FULFILLED' | 'REJECTED', required: Coarse-grained analysis state. - `UNATTEMPTED`: analysis has not started yet. - `LOADING`: analysis is in progress. - `FULFILLED`: analysis completed successfully. `description`, `transcript`, and `durationSeconds` are now populated where applicable for the file's type. - `REJECTED`: analysis failed permanently and will not be retried.
      - `analysisProgressPercentage` number, required: Progress in `[0, 100]`. Always `100` when `analysisLoadingState` is `FULFILLED`. Otherwise the most recent in-flight progress reported by the analysis task (or `0` if no progress has been reported yet).
      - `analysisAttemptIndex` integer: Zero-based index of the current analysis task attempt. Only present while analysis is still loading (`UNATTEMPTED` or `LOADING`); omitted once analysis reaches a terminal state.
  - `error` ApiError, required: Standard error body returned with every non-2xx response (the `default` response of every operation). The HTTP status code conveys the error class; this body carries the details: - `400` invalid request, `401` missing or invalid API key, `403` not permitted (e.g. plan or add-on required, see `requirement`), `404` not found, `409` conflict, `429` rate limited or out of credits, `5xx` server error. Common `code` values include `invalid_request`, `invalid_api_key`, `not_authorized`, `not_found`, `insufficient_credits`, and `rate_limited`. Always branch on `code` (and `requirement.type` when present) rather than parsing `message`.
    - `message` string, required: Human-readable error description. For display and logging only; do not branch on its exact text.
    - `code` string, nullable: Machine-readable error code in snake_case (e.g. `invalid_api_key`, `insufficient_credits`). `null` when no specific code applies.
    - `requirement` ErrorRequirement: What is needed to resolve an error, when it can be fixed by fulfilling a specific requirement (e.g. purchasing an add-on or upgrading the plan).
      - `type` string, required: Machine-readable requirement type in snake_case (e.g. `purchase_add_on`, `upgrade_plan`).
      - `details` object: Key-value pairs with requirement-specific context (e.g. the add-on id to purchase).
    - `internalErrorCode` string, nullable: Opaque internal error code for debugging. Include this when contacting support. `null` when not applicable.

## Other responses

- `default`: Error

## Changes

- **2026-10-15** `2976ed641a0c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/videogen/apis/videogen-api/changes/v1/files/imports/:fileImportId/get.md)

---

[API](https://skmtc.dev/videogen/apis/videogen-api.md) - [All operations](https://skmtc.dev/videogen/apis/videogen-api/llms.txt) - [OpenAPI document](https://skmtc.dev/videogen/apis/videogen-api/revisions/25148ccd4132?raw)