> This page is for version v1.3 (default). > For other versions, use one of these documentation indexes: > - v1.3 (default): https://docs.twelvelabs.io/v1.3/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.twelvelabs.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server. # Imports > Import files from a connected account with the Node.js SDK. The `Imports` class provides methods to import files from a connected account into the platform as assets and to review past imports. For the end-to-end workflow, see the [Data connectors](/v1.3/sdk-reference/node-js/data-connectors) page. # Methods ## Import files **Description**: This method imports one or more files from the connected provider account into the platform as assets. Videos can be up to 10 GB, audio up to 4 GB, and images up to 32 MB. For each newly imported file, the platform creates an asset in the `processing` status and fetches the file asynchronously. If you import a file that was already imported through this account, the platform returns the existing asset with its current status, without fetching the file again. If the earlier fetch had failed, the platform fetches the file again. The response contains one entry per requested file, in request order. Use the `action` property of each entry to identify which files were newly imported and which were already imported. **Function signature and example**: **`Function signature`** ```javascript Function signature importFiles( connectionId: string, request: TwelvelabsApi.ImportFilesRequest, requestOptions?: Imports.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const result = await client.imports.importFiles("", { items: [{ sourceId: "1AbCDef_drive_file_id_x" }], }); console.log(result.hasFailures); ``` ### Parameters | Name | Type | Required | Description | | :--------------- | :--------------------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `connectionId` | `string` | Yes | The unique identifier of the connection to import through. | | `items` | `ImportFilesRequest` `ItemsItem[]` | Yes | The files to import. Provide an array of one item for a single import, or multiple items for a batch import. A maximum of 100 items can be imported per request. The `sourceId` field of each item must be unique within a request. | | `requestOptions` | `Imports.` `RequestOptions` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | The `ImportFilesRequestItemsItem` object contains the following property: | Name | Type | Required | Description | | :--------- | :------- | :------- | :--------------------------------------------------------------------------------------------------------------------- | | `sourceId` | `string` | Yes | The identifier of the file at the provider. For Google Drive, this is the identifier Google Drive assigns to the file. | ### Return value Returns an `ImportResult` object. The `ImportResult` object contains the following properties: | Name | Type | Description | | :------------ | :------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | The unique identifier of the import created for this request. | | `hasFailures` | `boolean` | Whether at least one item was rejected before an asset was created. When `true`, inspect the `error` object of each item to identify the rejected ones. An item the platform skipped as a duplicate is not a failure. | | `items` | `ImportItem[]` | One entry per requested file, in request order, with its `action` value and the current status of its asset. | The `ImportItem` object contains the following properties: | Name | Type | Description | | :--------- | :----------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sourceId` | `string` | The identifier of the file at the provider. For Google Drive, this is the identifier Google Drive assigns to the file. | | `action` | `ImportItemAction` | The action taken for this file. Values: `created`, `skipped`, `retried`, `rejected`. The platform sets this value while processing the request, and the value does not change afterward. The [`importFiles`](#import-files) method always returns this property. The [`retrieveImport`](#retrieve-an-import) method omits it for imports from before this property existed. Treat an absent value as unknown rather than as a specific action. The `skipped` and `retried` values both mean the file was already imported through this account: for the `skipped` action, the platform returns the existing asset; for the `retried` action, the earlier fetch had failed, so the platform fetches the file again. See [The import object](/v1.3/api-reference/data-connectors/imports/the-import-object#item-actions) for the meaning of each value. | | `assetId` | `string` | The unique identifier of the asset for this file. When the `action` property is `created`, this identifies a new asset; when it is `skipped` or `retried`, this identifies the asset from the earlier import of the same file. Absent when the item was rejected before an asset was created. | | `status` | `ImportItemStatus` | The status of the asset. Values: `processing`, `ready`, `failed`. Absent when the item was rejected before an asset was created, in which case an `error` object is present. | | `error` | `ImportItemError` | Details of the rejection. Present when the item was rejected before an asset was created, in which case the `status` field is absent. | The `ImportItemError` object contains the following properties: | Name | Type | Description | | :-------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `code` | `string` | A string representing the code associated with the error. For the possible values, see the [Error codes](/v1.3/api-reference/error-codes#the-connections-endpoints) page. | | `message` | `string` | A human-readable string describing the error, intended to be suitable for display in a user interface. | ### API Reference [Import files](/v1.3/api-reference/data-connectors/imports/import-files). ## List imports **Description**: This method returns a list of the imports for the specified connection. The platform returns the imports sorted by creation date, with the newest at the top of the list. Each import in the list is a summary and does not include the per-file details. To see them, use the [`retrieveImport`](#retrieve-an-import) method. **Function signature and example**: **`Function signature`** ```javascript Function signature listImports( connectionId: string, request?: TwelvelabsApi.ListImportsRequest, requestOptions?: Imports.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const response = await client.imports.listImports("", { // page: 1, // pageLimit: 10, }); console.log(response.data); ``` ### Parameters | Name | Type | Required | Description | | :--------------- | :-------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `connectionId` | `string` | Yes | The unique identifier of the connection to list imports for. | | `page` | `number` | No | A number that identifies the page to retrieve. **Default**: `1`. | | `pageLimit` | `number` | No | The number of items to return on each page. **Default**: `10`. **Max**: `50`. | | `requestOptions` | `Imports.` `RequestOptions` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | ### Return value Returns a `ListImportsResponse` object. The `ListImportsResponse` object contains the following properties: | Name | Type | Description | | :--------- | :--------- | :--------------------------------------------------------------------------------------------------------------------------------- | | `data` | `Import[]` | An array containing the imports. | | `pageInfo` | `PageInfo` | An object that provides information about pagination. Contains the `page`, `limitPerPage`, `totalPage`, and `totalResults` fields. | The `Import` object contains the following properties: | Name | Type | Description | | :------------- | :--------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | The unique identifier of the import. | | `connectionId` | `string` | The unique identifier of the connection the files were imported through. | | `provider` | `ImportProvider` | The data connector provider. Values: `google_drive`. | | `customId` | `string` | The label you supplied when you [authorized the connection](/v1.3/api-reference/data-connectors/authorize-a-connection), copied when the import was created. Present only when you supplied one. | | `itemCount` | `number` | The number of files requested in this import. If an imported asset is later deleted, it is omitted from the `items` array returned by the [`retrieveImport`](#retrieve-an-import) method, so the `items` array can contain fewer entries than `itemCount`. | | `createdAt` | `Date` | The date and time, in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), when the import was created. | ### API Reference [List imports](/v1.3/api-reference/data-connectors/imports/list-imports). ## Retrieve an import **Description**: This method retrieves a single import. For each file, the response includes the `action` property, which indicates the outcome of the import operation, and the `status` property, which reflects the current status of the asset each time you retrieve the import. **Function signature and example**: **`Function signature`** ```javascript Function signature retrieveImport( connectionId: string, importId: string, requestOptions?: Imports.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const importDetail = await client.imports.retrieveImport( "", "", ); console.log(importDetail.items); ``` ### Parameters | Name | Type | Required | Description | | :--------------- | :-------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `connectionId` | `string` | Yes | The unique identifier of the connection to retrieve the import from. | | `importId` | `string` | Yes | The unique identifier of the import to retrieve. | | `requestOptions` | `Imports.` `RequestOptions` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | ### Return value Returns an `ImportDetail` object. The `ImportDetail` object contains all the properties of the `Import` object (see [List imports](#list-imports)), plus the following: | Name | Type | Description | | :------ | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `items` | `ImportItem[]` | One entry per requested file, in request order, with its `action` value and the current status of its asset. For the properties of each `ImportItem` object, see [Import files](#import-files). | ### API Reference [Retrieve an import](/v1.3/api-reference/data-connectors/imports/retrieve-an-import).