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

# Storage

## StorageFolder Objects

```python theme={"dark"}
class StorageFolder()
```

Represents a storage folder within the Encord system.

#### uuid

```python theme={"dark"}
@property
def uuid() -> UUID
```

Gets the unique identifier of the folder.

**Returns**:

* `UUID` - The UUID of the folder.

#### parent\_uuid

```python theme={"dark"}
@property
def parent_uuid() -> Optional[UUID]
```

Gets the unique identifier of the parent folder.

**Returns**:

* `Optional[UUID]` - The UUID of the parent folder, or None if there is no parent.

#### parent

```python theme={"dark"}
@property
def parent() -> Optional["StorageFolder"]
```

Gets the parent folder.

**Returns**:

* `Optional[StorageFolder]` - The parent StorageFolder object, or None if there is no parent.

#### name

```python theme={"dark"}
@property
def name() -> str
```

Gets the name of the folder.

**Returns**:

* `str` - The name of the folder.

#### description

```python theme={"dark"}
@property
def description() -> str
```

Gets the description of the folder.

**Returns**:

* `str` - The description of the folder.

#### client\_metadata

```python theme={"dark"}
@property
def client_metadata() -> Optional[Dict[str, Any]]
```

Gets the client metadata of the folder.

**Returns**:

Optional\[Dict\[str, Any]]: The client metadata as a dictionary, or None if there is no metadata.

#### path\_to\_root

```python theme={"dark"}
@property
def path_to_root() -> List[PathElement]
```

Gets the path elements from the current folder to the root.

**Returns**:

* `List[PathElement]` - A list of PathElement objects representing the path to the root.

#### list\_items

```python theme={"dark"}
def list_items(*,
               search: Optional[str] = None,
               is_in_dataset: Optional[bool] = None,
               item_types: Optional[List[StorageItemType]] = None,
               order: FoldersSortBy = FoldersSortBy.NAME,
               get_signed_urls: bool = False,
               include_client_metadata: bool = True,
               resolve_client_metadata_locally: bool = False,
               desc: bool = False,
               page_size: int = 100) -> Iterable["StorageItem"]
```

Lists items in the folder.

**Arguments**:

* `search` *Optional\[str]* - Search string to filter items by name.
* `is_in_dataset` *Optional\[bool]* - Filter items by whether they are linked to any dataset.
  `True` and `False` select only linked and only unlinked items, respectively.
  `None` includes all items regardless of their dataset links.
* `item_types` *Optional\[List\[StorageItemType]]* - Filter items by type.
* `order` *FoldersSortBy* - Sort order. Defaults to FoldersSortBy.NAME.
* `get_signed_urls` *bool* - Whether to get signed URLs for the items. Defaults to False.
* `include_client_metadata` *bool* - Optionally include client metadata into the result of this query.
  Defaults to True.
* `resolve_client_metadata_locally` *bool* - Has no effect unless `include_client_metadata` is set.
  When true, the SDK downloads the metadata client-side instead of the server embedding it directly
  in the response. Use this to prevent server timeouts for projects with large client metadata.
* `desc` *bool* - Sort in descending order. Defaults to False.
* `page_size` *int* - Number of items to return per page.  Default if not specified is 100. Maximum value is 1000.

**Returns**:

* `Iterable[StorageItem]` - Iterable of items in the folder.

#### delete

```python theme={"dark"}
def delete() -> None
```

Deletes the folder.

#### upload\_image

```python theme={"dark"}
def upload_image(
    file_path: Union[Path, str],
    title: Optional[str] = None,
    client_metadata: Optional[Dict[str, Any]] = None,
    cloud_upload_settings: CloudUploadSettings = CloudUploadSettings()
) -> UUID
```

Uploads an image to a folder in Encord storage.

**Arguments**:

* `file_path` *Union\[Path, str]* - Path to the image file (e.g., '/home/user/data/image.png').
* `title` *Optional\[str]* - The image title. If unspecified, this will be the file name.
* `client_metadata` *Optional\[Dict\[str, Any]]* - Optional arbitrary metadata to be associated with the image.
  Should be a dictionary that is JSON-serializable.
* `cloud_upload_settings` *CloudUploadSettings* - Settings for uploading data into the cloud. Change this object
  to overwrite the default values.

**Returns**:

* `UUID` - The UUID of the newly created image item.

**Raises**:

* `AuthorizationError` - If the user is not authorized to access the folder.
* `EncordException` - If the image could not be uploaded, e.g., due to being in an unsupported format.

#### upload\_video

```python theme={"dark"}
def upload_video(
    file_path: Union[Path, str],
    title: Optional[str] = None,
    client_metadata: Optional[Dict[str, Any]] = None,
    video_metadata: Optional[CustomerProvidedVideoMetadata] = None,
    cloud_upload_settings: CloudUploadSettings = CloudUploadSettings()
) -> UUID
```

Uploads a video to a folder in Encord storage.

**Arguments**:

* `file_path` *Union\[Path, str]* - Path to the video file (e.g., '/home/user/data/video.mp4').
* `title` *Optional\[str]* - The video title. If unspecified, this will be the file name. This title should include an extension.
  For example, "encord\_video.mp4".
* `client_metadata` *Optional\[Dict\[str, Any]]* - Optional arbitrary metadata to be associated with the video.
  Should be a dictionary that is JSON-serializable.
* `video_metadata` *Optional\[CustomerProvidedVideoMetadata]* - Optional media metadata for a video file; if provided,
  Encord service will skip frame synchronization checks and
  will use the values specified here to render the video
  in the label editor.
* `cloud_upload_settings` *CloudUploadSettings* - Settings for uploading data into the cloud. Change this object to
  overwrite the default values.

**Returns**:

* `UUID` - The UUID of the newly created video item.

**Raises**:

* `AuthorizationError` - If the user is not authorized to access the folder.
* `EncordException` - If the video could not be uploaded, e.g., due to being in an unsupported format.

#### re\_encode\_videos

```python theme={"dark"}
def re_encode_videos(storage_items: List[UUID], process_title: str,
                     force_full_reencoding: bool) -> UUID
```

Re-encodes the specified video items.

**Arguments**:

* `storage_items` *List\[UUID]* - List of UUIDs representing the video items to be re-encoded.
* `process_title` *str* - Title for the re-encoding process.
* `force_full_reencoding` *bool* - Flag to force full re-encoding.

**Returns**:

* `UUID` - The UUID of the re-encoding process.

#### get\_re\_encoding\_status

```python theme={"dark"}
def get_re_encoding_status(process_hash: UUID) -> ReencodeVideoItemsResponse
```

Retrieves the status of a re-encoding process.

**Arguments**:

* `process_hash` *UUID* - The UUID of the re-encoding process.

**Returns**:

* `ReencodeVideoItemsResponse` - Response object containing the status of the re-encoding process.

#### create\_dicom\_series

```python theme={"dark"}
def create_dicom_series(
    file_paths: Sequence[Union[str, Path]],
    title: Optional[str] = None,
    client_metadata: Optional[Dict[str, Any]] = None,
    cloud_upload_settings: CloudUploadSettings = CloudUploadSettings()
) -> UUID
```

Uploads a DICOM series to a folder in Encord storage.

**Arguments**:

* `file_paths` *Sequence\[Union\[str, Path]]* - A list of paths to DICOM files, e.g.,
  \['/home/user/data/DICOM\_1.dcm', '/home/user/data/DICOM\_2.dcm'].
* `title` *Optional\[str]* - The title of the DICOM series. If unspecified, this will be randomly generated.
  This title should NOT include an extension. For example, "encord\_image\_group".
* `client_metadata` *Optional\[Dict\[str, Any]]* - Optional arbitrary metadata to be associated with the DICOM series.
  Should be a dictionary that is JSON-serializable.
* `cloud_upload_settings` *CloudUploadSettings* - Settings for uploading data into the cloud. Change this object
  to overwrite the default values.

**Returns**:

* `UUID` - The UUID of the newly created DICOM series item.

**Raises**:

* `AuthorizationError` - If the user is not authorized to access the folder.
* `EncordException` - If the series could not be uploaded, e.g., due to being in an unsupported format.

#### create\_image\_group

```python theme={"dark"}
def create_image_group(
    file_paths: Collection[Union[Path, str]],
    title: Optional[str] = None,
    client_metadata: Optional[Dict[str, Any]] = None,
    cloud_upload_settings: CloudUploadSettings = CloudUploadSettings()
) -> UUID
```

Creates an image group in Encord storage. Choose this type of image upload for non-sequential images that are
logically connected (for example, multiple views of the same object). See also [create\_image\_sequence()](/sdk-documentation/sdk-references/storage#create_image_sequence)
and [upload\_image()](/sdk-documentation/sdk-references/storage#upload_image).

**Arguments**:

* `file_paths` *Collection\[Union\[Path, str]]* - A list of paths to images, e.g.,
  \['/home/user/data/img1.png', '/home/user/data/img2.png'].
* `title` *Optional\[str]* - The title of the image group. If unspecified, this will be randomly generated.
  This title should NOT include an extension. For example, "encord\_image\_group".
* `client_metadata` *Optional\[Dict\[str, Any]]* - Optional arbitrary metadata to be associated with the image group.
  Should be a dictionary that is JSON-serializable.
* `cloud_upload_settings` *CloudUploadSettings* - Settings for uploading data into the cloud. Change this object
  to overwrite the default values.

**Returns**:

* `UUID` - The UUID of the newly created image group item.

**Raises**:

* `AuthorizationError` - If the user is not authorized to access the folder.
* `EncordException` - If the images could not be uploaded, e.g., due to being in an unsupported format.

#### create\_image\_sequence

```python theme={"dark"}
def create_image_sequence(
    file_paths: Collection[Union[Path, str]],
    title: Optional[str] = None,
    client_metadata: Optional[Dict[str, Any]] = None,
    cloud_upload_settings: CloudUploadSettings = CloudUploadSettings()
) -> UUID
```

Creates an image sequence in Encord storage. Choose this type of image upload for sequential images (a timelapse
or similar). A compressed video will be created from the images.

See also [create\_image\_group()](/sdk-documentation/sdk-references/storage#create_image_group) and [upload\_image()](/sdk-documentation/sdk-references/storage#upload_image).

**Arguments**:

* `file_paths` *Collection\[Union\[Path, str]]* - A list of paths to images, e.g.,
  \['/home/user/data/img1.png', '/home/user/data/img2.png'].
* `title` *Optional\[str]* - The title of the image sequence. If unspecified, this will be randomly generated.
  This title should NOT include an extension. For example, "front camera 2024-04-01".
* `client_metadata` *Optional\[Dict\[str, Any]]* - Optional arbitrary metadata to be associated with the image sequence.
  Should be a dictionary that is JSON-serializable.
* `cloud_upload_settings` *CloudUploadSettings* - Settings for uploading data into the cloud. Change this object
  to overwrite the default values.

**Returns**:

* `UUID` - The UUID of the newly created image sequence item.

**Raises**:

* `AuthorizationError` - If the user is not authorized to access the folder.
* `EncordException` - If the images could not be uploaded, e.g., due to being in an unsupported format.

#### upload\_nifti

```python theme={"dark"}
def upload_nifti(
    file_path: Union[Path, str],
    title: Optional[str] = None,
    client_metadata: Optional[Dict[str, Any]] = None,
    cloud_upload_settings: CloudUploadSettings = CloudUploadSettings()
) -> UUID
```

Uploads a NIfTI file to an Encord Storage Folder.

**Arguments**:

file\_path (Union\[Path, str]):
Path to the local NIfTI file (e.g., '/home/user/data/brain\_scan.nii.gz').

title (Optional\[str]):
Title of the NIfTI item in Encord. If not provided, the filename is used.
Must include the '.nii' or '.nii.gz' extension.

client\_metadata (Optional\[Dict\[str, Any]]):
Custom metadata to associate with the NIfTI file. Must be JSON-serializable.

cloud\_upload\_settings (CloudUploadSettings):
Configuration for how the file is uploaded to the cloud. Use this to override default behavior.

**Returns**:

* `UUID` - UUID of the uploaded NIfTI item.

**Raises**:

* `AuthorizationError` - If the user lacks permission to access the target folder.
* `EncordException` - If the file cannot be uploaded (for example due to format or metadata issues).

#### upload\_audio

```python theme={"dark"}
def upload_audio(
    file_path: Union[Path, str],
    title: Optional[str] = None,
    client_metadata: Optional[Dict[str, Any]] = None,
    audio_metadata: Optional[CustomerProvidedAudioMetadata] = None,
    cloud_upload_settings: CloudUploadSettings = CloudUploadSettings()
) -> UUID
```

Uploads an audio file to an Encord Storage Folder.

**Arguments**:

file\_path (Union\[Path, str]):
Path to the local audio file (e.g., '/home/user/data/audio.mp3').

title (Optional\[str]):
Title of the audio file in Encord. If not provided, the filename is used.
The title must include a valid audio file extension (e.g., "encord\_audio.mp3").

client\_metadata (Optional\[Dict\[str, Any]]):
Custom metadata to associate with the audio. Must be JSON-serializable.

audio\_metadata (Optional\[CustomerProvidedAudioMetadata]):
Optional media metadata describing the audio file. If provided, the Encord skips scanning the file to extract media metadata.

cloud\_upload\_settings (CloudUploadSettings):
Configuration for cloud upload behavior. Override default settings using this parameter.

**Returns**:

* `UUID` - UUID of the uploaded audio item.

**Raises**:

* `AuthorizationError` - If the user is not authorized to access the destination folder.
* `EncordException` - If the upload fails (for example due to an unsupported audio format).

  #### audio\_metadata

  audio\_metadata for audio files; if provided, frame synchronization checks are skipped.

  * duration: float - Audio duration in seconds.
  * file\_size: int - Size of the audio file in bytes.
  * mime\_type: str - MIME type of the audio file (for example: `audio/mpeg` or `audio/wav`).
  * sample\_rate: int - Sample rate (int) in Hz.
  * bit\_depth: int - Size of each sample (int) in bits.
  * codec: str - Codec (for example: mp3, pcm).
  * num\_channels: int - Number of channels.

#### upload\_text

```python theme={"dark"}
def upload_text(
    file_path: Union[Path, str],
    title: Optional[str] = None,
    client_metadata: Optional[Dict[str, Any]] = None,
    text_metadata: Optional[orm_storage.CustomerProvidedTextMetadata] = None,
    cloud_upload_settings: CloudUploadSettings = CloudUploadSettings()
) -> UUID
```

Upload a text file to a Folder in Encord storage.

**Arguments**:

* `file_path` - File path of the text file. For example: '/home/user/data/report.txt'
* `title` - The item title. If unspecified, the file name is used as the title.
* `client_metadata` - Optional custom metadata to be associated with the text file. Should be a dictionary that is JSON-serializable.
* `text_metadata` - Optional media metadata for a text file. The Encord platform uses the specified values instead of scanning the files.
* `cloud_upload_settings` - Settings for uploading data into the cloud. Change this object to overwrite the default values.

**Returns**:

UUID of the newly created text item.

**Raises**:

* `AuthorizationError` - If the user is not authorized to access the folder.
* `EncordException` - If the audio could not be uploaded. For example, due to being in an unsupported format.

  #### text\_metadata

  text\_metadata for text files. The Encord platform uses the specified values instead of scanning the files.

  * file\_size: int - Size of the text file in bytes.
  * mime\_type: str - MIME type of the text file (for example: `application/json` or `text/plain`).

#### upload\_pdf

```python theme={"dark"}
def upload_pdf(
    file_path: Union[Path, str],
    title: Optional[str] = None,
    client_metadata: Optional[Dict[str, Any]] = None,
    pdf_metadata: Optional[orm_storage.CustomerProvidedPdfMetadata] = None,
    cloud_upload_settings: CloudUploadSettings = CloudUploadSettings()
) -> UUID
```

Upload a PDF file to a Folder in Encord storage.

**Arguments**:

* `file_path` - File path of the PDF file. For example: '/home/user/data/report.pdf'
* `title` - The item title. If unspecified, the file name is used as the title.
* `client_metadata` - Optional custom metadata to be associated with the PDF file. Should be a dictionary that is JSON-serializable.
* `pdf_metadata` - Optional media metadata for a PDF file. The Encord platform uses the specified values instead of scanning the files.
* `cloud_upload_settings` - Settings for uploading data into the cloud. Change this object to overwrite the default values.

**Returns**:

UUID of the newly created PDF item.

**Raises**:

* `AuthorizationError` - If the user is not authorized to access the folder.
* `EncordException` - If the document could not be uploaded. For example, due to being in an unsupported format.

  #### pdf\_metadata

  pdf\_metadata for PDF files. The Encord platform uses the specified values instead of scanning the files.

  * file\_size: int - Size of the PDF file in bytes.
  * num\_pages: int - Number of pages in the PDF file.

#### upload\_scene

```python theme={"dark"}
def upload_scene(scene: SceneBuilder,
                 title: str,
                 integration_id: str,
                 client_metadata: Optional[Dict[str, Any]] = None) -> UUID
```

Upload a scene to a folder in Encord storage.

**Arguments**:

* `scene` - Scene builder containing the streams and events to upload.
* `title` - The scene item title.
* `integration_id` - UUID of the cloud storage integration that can access the scene asset URIs.
* `client_metadata` - Optional custom metadata to associate with the scene item.

**Returns**:

UUID of the newly created scene item.

**Raises**:

* `EncordException` - If the scene could not be registered.

#### add\_private\_data\_to\_folder\_start

```python theme={"dark"}
def add_private_data_to_folder_start(integration_id: str,
                                     private_files: Union[str, Dict, Path,
                                                          TextIO,
                                                          DataUploadItems],
                                     ignore_errors: bool = False) -> UUID
```

Starts the process of adding private data to a folder in Encord storage.

**Arguments**:

* `integration_id` *str* - The integration ID for the folder.
  private\_files (Union\[str, Dict, Path, TextIO, DataUploadItems]):
  The specification of private files to be added. Can be either a JSON in Encord upload format
  (see the relevant documentation), or an [DataUploadItems](/sdk-documentation/sdk-references/orm.storage#datauploaditems) object.
* `ignore_errors` *bool* - If True, errors will be ignored during the upload process.

**Returns**:

* `UUID` - The UUID of the upload job.

#### sync\_private\_data\_with\_cloud\_synced\_folder\_start

```python theme={"dark"}
def sync_private_data_with_cloud_synced_folder_start() -> UUID
```

Start synchronization of a cloud-synced folder with its remote cloud storage bucket.

This method triggers a synchronization job that scans the cloud storage bucket linked
to this folder and updates the Encord storage folder to match. The synchronization is
performed asynchronously in the background, and this method returns immediately with
a job UUID that can be used to track the progress.

The synchronization process:

1. Scans the cloud bucket for files
2. Creates new storage items for files that exist in the bucket but not in the folder
3. Updates the tombstone status of items (marks as tombstone if deleted from bucket,
   restores if re-added)
4. Updates items if they have the same path but different content (different checksum)

**Returns**:

* `UUID` - The unique identifier for the sync job that can be used with
  `sync_private_data_with_cloud_synced_folder_get_result` to poll for results.

**Raises**:

* `InvalidArgumentsError` - If the folder is not a cloud-synced folder, or if there are
  permission issues with the cloud storage bucket.

**Notes**:

This method can only be used with folders created with cloud\_synced\_folder\_params.
The SDK process can be terminated after starting the job - the synchronization
will continue running on the server.

#### sync\_private\_data\_with\_cloud\_synced\_folder\_get\_result

```python theme={"dark"}
def sync_private_data_with_cloud_synced_folder_get_result(
    sync_job_uuid: UUID,
    timeout_seconds: int = 7 * 24 * 60 * 60
) -> orm_storage.SyncPrivateDataWithCloudSyncedFolderGetResultResponse
```

Poll for the results of a cloud-synced folder synchronization job.

This method polls for the status of a synchronization job started with
`sync_private_data_with_cloud_synced_folder_start()`. It uses long polling to efficiently
wait for job completion without constantly making API requests. The method returns once
the job completes or the timeout is reached.

**Arguments**:

* `sync_job_uuid` *UUID* - The UUID of the synchronization job to poll for results.
* `timeout_seconds` *int* - Maximum time in seconds to wait for the job to complete.
  Default is 7 days (604800 seconds).

**Returns**:

* `SyncPrivateDataWithCloudSyncedFolderGetResultResponse` - An object containing the results of
  the synchronization job.

**Raises**:

* `InvalidArgumentsError` - If the synchronization job UUID does not exist or is not associated
  with this folder.

**Notes**:

This method will log progress information as it polls for results. For very large
buckets, the synchronization process can take a significant amount of time.

#### add\_private\_data\_to\_folder\_get\_result

```python theme={"dark"}
def add_private_data_to_folder_get_result(
        upload_job_id: UUID,
        timeout_seconds: int = 7 * 24 * 60 * 60) -> UploadLongPollingState
```

Retrieves the result of adding private data to a folder in Encord storage.

**Arguments**:

* `upload_job_id` *UUID* - The UUID of the upload job.
* `timeout_seconds` *int* - The timeout in seconds for the upload job.

**Returns**:

* `UploadLongPollingState` - The state of the upload job.

#### list\_subfolders

```python theme={"dark"}
def list_subfolders(*,
                    search: Optional[str] = None,
                    dataset_synced: Optional[bool] = None,
                    order: FoldersSortBy = FoldersSortBy.NAME,
                    desc: bool = False,
                    page_size: int = 100) -> Iterable["StorageFolder"]
```

Lists subfolders of the current folder.

**Arguments**:

* `search` *Optional\[str]* - Search string to filter folders by name.
* `dataset_synced` *Optional\[bool]* - Include or exclude folders that are mirrored by a dataset. If `None`,
  no filtering is applied.
* `order` *FoldersSortBy* - Sort order for the folders. See [FoldersSortBy](/sdk-documentation/sdk-references/orm.storage#folderssortby) for available options.
* `desc` *bool* - If True, sort in descending order.
* `page_size` *int* - Number of folders to return per page.  Default if not specified is 100. Maximum value is 1000.

**Returns**:

* `Iterable[StorageFolder]` - An iterable of [StorageFolder](/sdk-documentation/sdk-references/storage#storagefolder) objects.

#### find\_subfolders

```python theme={"dark"}
def find_subfolders(search: Optional[str] = None,
                    dataset_synced: Optional[bool] = None,
                    order: FoldersSortBy = FoldersSortBy.NAME,
                    desc: bool = False,
                    page_size: int = 100) -> Iterable["StorageFolder"]
```

Recursively searches for storage folders, starting from this folder.

**Arguments**:

* `search` *Optional\[str]* - Search string to filter folders by name.
* `dataset_synced` *Optional\[bool]* - Include or exclude folders that are mirrored by a dataset. If `None`,
  no filtering is applied.
* `order` *FoldersSortBy* - Sort order for the folders. See [FoldersSortBy](/sdk-documentation/sdk-references/orm.storage#folderssortby) for available options.
* `desc` *bool* - If True, sort in descending order.
* `page_size` *int* - Number of folders to return per page.  Default if not specified is 100. Maximum value is 1000.

**Returns**:

* `Iterable[StorageFolder]` - An iterable of [StorageFolder](/sdk-documentation/sdk-references/storage#storagefolder) objects.

#### create\_subfolder

```python theme={"dark"}
def create_subfolder(
        name: str,
        description: Optional[str] = None,
        client_metadata: Optional[Dict[str, Any]] = None) -> "StorageFolder"
```

Create a new subfolder of this folder. See also [create\_storage\_folder()](/sdk-documentation/sdk-references/user_client#create_storage_folder).

**Arguments**:

* `name` - The name of the folder.
* `description` - The description of the folder.
* `client_metadata` - Optional arbitrary metadata to be associated with the folder. Should be a dictionary
  that is JSON-serializable.

**Returns**:

The created storage folder. See [StorageFolder](/sdk-documentation/sdk-references/storage#storagefolder) for details.

#### find\_items

```python theme={"dark"}
def find_items(search: Optional[str] = None,
               is_in_dataset: Optional[bool] = None,
               item_types: Optional[List[StorageItemType]] = None,
               order: FoldersSortBy = FoldersSortBy.NAME,
               desc: bool = False,
               get_signed_urls: bool = False,
               page_size: int = 100) -> Iterable["StorageItem"]
```

Recursively search for storage items, starting from this folder.

Warning: This method is slow. We recommend using `storage_folder.list_items` instead.

**Arguments**:

* `search` *Optional\[str]* - Search string to filter items by name.
* `is_in_dataset` *Optional\[bool]* - Filter items by whether they are linked to any dataset. `True` and `False` select
  only linked and only unlinked items, respectively. `None` includes all items regardless of their
  dataset links.
* `item_types` *Optional\[List\[StorageItemType]]* - Filter items by type.
* `order` *FoldersSortBy* - Sort order.
* `desc` *bool* - Sort in descending order.
* `get_signed_urls` *bool* - If True, return signed URLs for the items.
* `page_size` *int* - Number of items to return per page.  Default if not specified is 100. Maximum value is 1000.

**Returns**:

* `Iterable[StorageItem]` - An iterable of items in the folder and its subfolders.

**Raises**:

* `ValueError` - If neither `search` nor `item_types` are provided.

#### get\_summary

```python theme={"dark"}
def get_summary() -> StorageFolderSummary
```

Get a summary of the folder (total size, number of items, etc).

**Returns**:

* `StorageFolderSummary` - A summary of the folder.

**See Also**:

[StorageFolderSummary](/sdk-documentation/sdk-references/orm.storage#storagefoldersummary) for the exact set of information provided.

#### update

```python theme={"dark"}
def update(name: Optional[str] = None,
           description: Optional[str] = None,
           client_metadata: Optional[Dict[str, Any]] = None,
           bundle: Optional[Bundle] = None) -> None
```

Update the folder's modifiable properties. Parameters that are not provided  are not updated.

**Arguments**:

* `name` *Optional\[str]* - New folder name.
* `description` *Optional\[str]* - New folder description.
* `client_metadata` *Optional\[Dict\[str, Any]]* - New client metadata.
* `bundle` *Optional\[Bundle]* - Optional [Bundle](/sdk-documentation/sdk-references/http.bundle#bundle) to use for the operation. If provided, the operation is bundled into a single server call with other item updates using the same bundle.

**Returns**:

None

#### move\_to\_folder

```python theme={"dark"}
def move_to_folder(
        target_folder: Optional[Union["StorageFolder", UUID]]) -> None
```

Move the folder to another folder (specify folder object or UUID), or to the root level if `target_folder` is None.

**Arguments**:

* `target_folder` *Optional\[Union\[StorageFolder, UUID]]* - The target folder to move to, or `None` to move to the root level.

**Returns**:

None

#### create\_data\_group

```python theme={"dark"}
def create_data_group(params: Union[DataGroupInput, List[UUID]]) -> UUID
```

Creates a data group storage item in this folder.

**Arguments**:

* `params` - Parameters for the data group. Can be:
  * DataGroupInput (DataGroupGrid, DataGroupCarousel, DataGroupCustom): Layout with optional client\_metadata
  * List\[UUID]: List of item UUIDs (creates a carousel layout)

**Returns**:

* `UUID` - The UUID of the data group storage item.

#### create\_data\_groups

```python theme={"dark"}
def create_data_groups(
        params: List[Union[DataGroupInput, List[UUID]]]) -> List[UUID]
```

Creates multiple data group storage items in this folder.

**Arguments**:

* `params` - List of parameters for each data group. Each item can be:
  * DataGroupInput (DataGroupGrid, DataGroupCarousel, DataGroupCustom): Layout with optional client\_metadata
  * List\[UUID]: List of item UUIDs (creates a carousel layout)

**Returns**:

* `List[UUID]` - List of UUIDs of the created data group storage items

#### move\_items\_to\_folder

```python theme={"dark"}
def move_items_to_folder(target_folder: Union["StorageFolder", UUID],
                         items_to_move: Sequence[Union[UUID, "StorageItem"]],
                         allow_mirror_dataset_changes: bool = False) -> None
```

Move items (list of `StorageItem` objects or UUIDs) to another folder (specify folder object or UUID).

**Arguments**:

* `target_folder` *Union\[StorageFolder, UUID]* - Target folder to move items to.
* `items_to_move` *Sequence\[Union\[UUID, StorageItem]]* - List of items to move. All the items should be immediate children
  of the current folder.
* `allow_mirror_dataset_changes` *bool* - If `True`, allow moving items that are linked to a mirror dataset. By default,
  moving such items is prohibited, as it would result in data units being removed from a dataset,
  potentially deleting related annotations and other data.

**Returns**:

None

#### delete\_storage\_items

```python theme={"dark"}
def delete_storage_items(item_uuids: List[UUID],
                         remove_unused_frames: bool = True) -> None
```

Delete storage items by their UUIDs.

**Arguments**:

* `item_uuids` *List\[UUID]* - List of UUIDs of items to delete. All the items should be immediate children
  of the current folder.
* `remove_unused_frames` *bool* - If `True` (default), remove individual images or DICOM files from image groups or
  DICOM series that are not used in any other item.

**Returns**:

None

#### list\_groups

```python theme={"dark"}
def list_groups() -> Iterable[StorageFolderGroup]
```

List all groups that have access to this folder.

#### add\_group

```python theme={"dark"}
def add_group(group_hash: Union[List[UUID], UUID], user_role: StorageUserRole)
```

Allow access to this folder for members of a group.

**Arguments**:

* `group_hash` - Group hash, or a list of group hashes to be added.
* `user_role` - User role that the group will be given.

**Returns**:

None

#### remove\_group

```python theme={"dark"}
def remove_group(group_hash: Union[List[UUID], UUID])
```

Revoke access to the folder from the members of a group.

**Arguments**:

* `group_hash` - Group hash, or a list of group hashes to be removed.

**Returns**:

None

#### refetch\_data

```python theme={"dark"}
def refetch_data() -> None
```

Refetch data for the folder.

**Returns**:

None

#### add\_data\_to\_folder\_job\_cancel

```python theme={"dark"}
def add_data_to_folder_job_cancel(
        upload_job_id: UUID) -> orm_storage.AddDataToFolderJobCancelResponse
```

Cancels a data upload in progress job, associated with this folder.

**Arguments**:

* `upload_job_id` *UUID* - The unique identifier for the upload job.

**Returns**:

* `AddDataToFolderJobCancelResponse` - A response indicating the result of the canceled job.

## StorageItemInaccessible Objects

```python theme={"dark"}
class StorageItemInaccessible()
```

#### uuid

```python theme={"dark"}
@property
def uuid() -> UUID
```

UUID: The unique identifier of the storage item.

## StorageItem Objects

```python theme={"dark"}
class StorageItem()
```

#### uuid

```python theme={"dark"}
@property
def uuid() -> UUID
```

UUID: The unique identifier of the storage item.

#### parent\_folder\_uuid

```python theme={"dark"}
@property
def parent_folder_uuid() -> UUID
```

UUID: The UUID of the parent folder.

#### parent\_folder

```python theme={"dark"}
def parent_folder() -> StorageFolder
```

Retrieve the parent folder of the storage item.

**Returns**:

* `StorageFolder` - The parent folder.

#### item\_type

```python theme={"dark"}
@property
def item_type() -> StorageItemType
```

StorageItemType: The type of the storage item.

#### name

```python theme={"dark"}
@property
def name() -> str
```

str: The name of the storage item.

#### description

```python theme={"dark"}
@property
@deprecated(version="0.1.177")
def description() -> str
```

str: This is always an empty string; descriptions on individual items are not supported.

#### client\_metadata

```python theme={"dark"}
@property
def client_metadata() -> Optional[Dict[str, Any]]
```

Optional\[Dict\[str, Any]]: The client metadata of the storage item.

#### created\_at

```python theme={"dark"}
@property
def created_at() -> datetime
```

datetime: The creation time of the storage item.

#### last\_edited\_at

```python theme={"dark"}
@property
def last_edited_at() -> datetime
```

datetime: The last edited time of the storage item.

#### backed\_data\_units\_count

```python theme={"dark"}
@property
def backed_data_units_count() -> int
```

int: The number of backed data units.

#### storage\_location

```python theme={"dark"}
@property
def storage_location() -> StorageLocationName
```

StorageLocationName: The storage location name.

#### integration\_hash

```python theme={"dark"}
@property
def integration_hash() -> Optional[UUID]
```

Optional\[UUID]: The integration hash.

#### url

```python theme={"dark"}
@property
def url() -> Optional[str]
```

Optional\[str]: The URL of the storage item.

#### file\_size

```python theme={"dark"}
@property
def file_size() -> Optional[int]
```

Optional\[int]: The file size of the storage item.

#### mime\_type

```python theme={"dark"}
@property
def mime_type() -> Optional[str]
```

Optional\[str]: The MIME type of the storage item.

#### duration

```python theme={"dark"}
@property
def duration() -> Optional[float]
```

Optional\[float]: The duration of the storage item.

#### fps

```python theme={"dark"}
@property
def fps() -> Optional[float]
```

Optional\[float]: The frames per second of the storage item.

#### height

```python theme={"dark"}
@property
def height() -> Optional[int]
```

Optional\[int]: The height of the storage item.

#### width

```python theme={"dark"}
@property
def width() -> Optional[int]
```

Optional\[int]: The width of the storage item.

#### dicom\_instance\_uid

```python theme={"dark"}
@property
def dicom_instance_uid() -> Optional[str]
```

Optional\[str]: The DICOM instance UID of the storage item.

#### dicom\_study\_uid

```python theme={"dark"}
@property
def dicom_study_uid() -> Optional[str]
```

Optional\[str]: The DICOM study UID of the storage item.

#### dicom\_series\_uid

```python theme={"dark"}
@property
def dicom_series_uid() -> Optional[str]
```

Optional\[str]: The DICOM series UID of the storage item.

#### frame\_count

```python theme={"dark"}
@property
def frame_count() -> Optional[int]
```

Optional\[int]: The frame count of the storage item.

#### audio\_sample\_rate

```python theme={"dark"}
@property
def audio_sample_rate() -> Optional[int]
```

Optional\[int]: The number of samples taken per second (in Hz).

#### audio\_bit\_depth

```python theme={"dark"}
@property
def audio_bit_depth() -> Optional[int]
```

Optional\[int]: The number of bits used to record each audio sample.

#### audio\_codec

```python theme={"dark"}
@property
def audio_codec() -> Optional[str]
```

Optional\[int]: The codec of the audio file (e.g., mp3 or flac).

#### audio\_num\_channels

```python theme={"dark"}
@property
def audio_num_channels() -> Optional[int]
```

Optional\[int]: The number of channels.

#### get\_signed\_url

```python theme={"dark"}
def get_signed_url(refetch: bool = False) -> Optional[str]
```

Get a signed URL for downloading the item.

Returns `None` for composite items that have no single file URL:

* For scenes, use [SceneReader](/sdk-documentation/sdk-references/beta.scene.reader#scenereader) to get signed URLs for all constituent files.
* For image groups and DICOM series, use [get\_child\_items()](/sdk-documentation/sdk-references/storage#get_child_items) to get signed URLs for individual frames.

**Arguments**:

* `refetch` - If `True`, forces fetching a new signed URL even if one is cached.

**Returns**:

* `Optional[str]` - Signed URL for downloading the item, or `None` for composite items.

#### get\_summary

```python theme={"dark"}
def get_summary() -> StorageItemSummary
```

Retrieve a summary of the item, including linked datasets and other information.

**Returns**:

* `StorageItemSummary` - Object containing summary information about the item.

#### get\_child\_items

```python theme={"dark"}
def get_child_items(get_signed_urls: bool = False) -> Iterable["StorageItem"]
```

Get child items of the item, such as frames of an image group or files of DICOM series.

**Arguments**:

* `get_signed_urls` - If `True`, include signed URLs for child items.

**Returns**:

* `Iterable[StorageItem]` - List of child items accessible to the user.

#### update

```python theme={"dark"}
def update(name: Optional[str] = None,
           description: Optional[str] = None,
           client_metadata: Optional[Dict[str, Any]] = None,
           bundle: Optional[Bundle] = None) -> None
```

Update modifiable properties of the item.

**Arguments**:

* `name` - New item name.
* `description` - New item description.
* `client_metadata` - New client metadata.
* `bundle` - Optional [Bundle](/sdk-documentation/sdk-references/http.bundle#bundle) to use for the operation. If provided, the operation

**Returns**:

None

**Notes**:

If no parameters are provided, the function does nothing.

If `bundle` is provided, the operation is bundled into a single server call with other item updates
using the same bundle.

#### delete

```python theme={"dark"}
def delete(remove_unused_frames=True) -> None
```

Delete the item from the storage.

**Arguments**:

* `remove_unused_frames` - If `True` (default), remove individual images or DICOM files not used elsewhere.

**Returns**:

None

#### move\_to\_folder

```python theme={"dark"}
def move_to_folder(target_folder: Union[StorageFolder, UUID],
                   allow_mirror_dataset_changes: bool = False) -> None
```

Move the item to another folder.

**Arguments**:

* `target_folder` - Target folder to move the item to. Can be a `StorageFolder` object or a UUID.
* `allow_mirror_dataset_changes` - If `True`, allows moving items linked to a mirror dataset.
  Default is `False`, which prohibits such moves to prevent data loss.

**Returns**:

None

**Notes**:

This method updates the item's parent folder and refetches item data after the move.

#### refetch\_data

```python theme={"dark"}
def refetch_data(get_signed_url: bool = False) -> None
```

Refetches data for the item, updating its attributes.

**Arguments**:

* `get_signed_url` - If `True`, refetches the signed URL for downloading the item.

**Returns**:

None