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

# The import object

> Import object schema for data connectors.

An import represents a single call to import files from a connected account. Each import attempts to create one asset per requested file and tracks the outcome of the import operation for each file.

Three endpoints return an import, with different fields in each response:

* [Import files](/v1.3/api-reference/data-connectors/imports/import-files) returns a confirmation of what was accepted: the `_id` and `has_failures` fields, and one item per requested file.
* [List imports](/v1.3/api-reference/data-connectors/imports/list-imports) returns each import as a summary, without the `items` array.
* [Retrieve an import](/v1.3/api-reference/data-connectors/imports/retrieve-an-import) returns the full import, including the `items` array with the current status of each file.

# Source file, item, and asset

Each file in an import moves through three stages, with a different name at each:

* **Source file**: What you select. In the [Import files](/v1.3/api-reference/data-connectors/imports/import-files) request, the `source_id` field of each entry contains the unique identifier of a file in the connected account.
* **Item**: How the import tracks the file. The `items` array has one entry per requested file, with a field named `action` for the outcome of the import operation, and a `status` field for its asset, or an `error` object if the file was rejected.
* **Asset**: What you use. Each accepted file becomes an asset with its own identifier in the `asset_id` field. Once the item reaches the `ready` status, use that value with the rest of the API.

# Import fields

An import object can include the following fields:

* `_id`: The unique identifier of the import.
* `connection_id`: The unique identifier of the connection the files were imported through.
* `provider`: The data connector provider (`google_drive`).
* `custom_id`: 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.
* `item_count`: The number of files requested in the import.
* `created_at`: The date and time, in the RFC 3339 format, when the import was created.
* `has_failures`: Whether at least one item was rejected before an asset was created. A skipped item is not a failure. Returned by [Import files](/v1.3/api-reference/data-connectors/imports/import-files).
* `items`: One entry per requested file, in request order. Returned by [Import files](/v1.3/api-reference/data-connectors/imports/import-files) and [Retrieve an import](/v1.3/api-reference/data-connectors/imports/retrieve-an-import).

An import is immutable. Each time you retrieve it, the `status` field of each item reflects the current status of its asset.

# Item actions

The `action` field indicates the outcome of the import operation for each file. [Import files](/v1.3/api-reference/data-connectors/imports/import-files) always returns it. [Retrieve an import](/v1.3/api-reference/data-connectors/imports/retrieve-an-import) omits it for imports from before this field existed, so treat an absent value as unknown. It has one of the following values:

| `action`   | Meaning                               | `asset_id`                       | `status`                         |
| ---------- | ------------------------------------- | -------------------------------- | -------------------------------- |
| `created`  | Newly imported                        | Identifier of the new asset      | `processing`                     |
| `skipped`  | Already imported through this account | Identifier of the existing asset | The current status of that asset |
| `retried`  | Re-imported after an earlier failure  | Identifier of the existing asset | `processing`                     |
| `rejected` | Could not be imported                 | None                             | None (an `error` object instead) |

## Summarize a request

To count how many files were imported, skipped, or rejected, use the `action` field, not the `status` field.

The `status` field alone cannot indicate the outcome of the import operation. A newly imported file and a skipped duplicate can both show the `processing` status: the new file because its import just started, the duplicate because an earlier import of the same file is still running. Only the `action` field distinguishes them, because it is set once and never changes, while the `status` field keeps updating as the asset is processed.

> **Tip**
>
> Group the `items` array by the `action` field to summarize a request. Do not infer the summary from the `status` field.

# Item statuses

The `status` field of an item has one of the following values:

* `processing`: The platform is fetching the file from the provider.
* `ready`: The asset is ready to use.
* `failed`: The platform could not fetch the file.

An item that was rejected before an asset was created has no value in its `status` field. Instead, it includes an `error` object with `code` and `message` fields. For the possible codes, see the [Error codes](/v1.3/api-reference/error-codes) page.