​

StorageFolder Objects

class StorageFolder()

Represents a storage folder within the Encord system.

​

uuid

@property
def uuid() -> UUID

Gets the unique identifier of the folder.

Returns:

• UUID - The UUID of the folder.

​

parent_uuid

@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

@property
def parent() -> Optional["StorageFolder"]

Gets the parent folder.

Returns:

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

​

name

@property
def name() -> str

Gets the name of the folder.

Returns:

• str - The name of the folder.

​

description

@property
def description() -> str

Gets the description of the folder.

Returns:

• str - The description of the folder.

​

client_metadata

@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

@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

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

def delete() -> None

Deletes the folder.

​

upload_image

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

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

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

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

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

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 (e.g., multiple views of the same object). See also :meth:.Folder.create_image_sequence and :meth:.Folder.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

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 :meth:.Folder.create_image_group and :meth:.Folder.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

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

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

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

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.

​

add_private_data_to_folder_start

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 :class:encord.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

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

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

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

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 :class:encord.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 :class:encord.StorageFolder objects.

​

find_subfolders

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 :class:encord.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 :class:encord.StorageFolder objects.

​

create_subfolder

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 :meth:encord.user_client.EncordUserClient.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 :class:encord.storage.StorageFolder for details.

​

find_items

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

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:

:class:encord.StorageFolderSummary for the exact set of information provided.

​

update

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. Any parameters that are not provided will not be 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 :class:encord.http.Bundle to use for the operation. If provided, the operation will be bundled into a single server call with other item updates using the same bundle.

Returns:

None

​

move_to_folder

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

def create_data_group(params: Union[DataGroupInput, List[UUID]]) -> UUID

Creates a data group storage item in this folder.

Arguments:

• params Union[DataGroupInput, List[UUID]] - Parameters for the data group. When a list of UUIDs is provided, the group will be created with a grid layout. For custom layouts, use DataGroupGrid, DataGroupList or DataGroupCustom.

Returns:

• UUID - The UUID of the data group storage item.

​

move_items_to_folder

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

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

def list_groups() -> Iterable[StorageFolderGroup]

List all groups that have access to this folder.

​

add_group

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

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

def refetch_data() -> None

Refetch data for the folder.

Returns:

None

​

add_data_to_folder_job_cancel

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