StorageFolder
StorageFolder Objects
Represents a storage folder within the Encord system.
uuid
Gets the unique identifier of the folder.
Returns:
UUID
- The UUID of the folder.
parent_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
Gets the parent folder.
Returns:
Optional[StorageFolder]
- The parent StorageFolder object, or None if there is no parent.
name
Gets the name of the folder.
Returns:
str
- The name of the folder.
description
Gets the description of the folder.
Returns:
str
- The description of the folder.
client_metadata
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
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
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
andFalse
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
Deletes the folder.
upload_image
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
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
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
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
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
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
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
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
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
oraudio/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
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
ortext/plain
).
upload_pdf
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
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
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:
- Scans the cloud bucket for files
- Creates new storage items for files that exist in the bucket but not in the folder
- Updates the tombstone status of items (marks as tombstone if deleted from bucket, restores if re-added)
- 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 withsync_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
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
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
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. IfNone
, 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
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. IfNone
, 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
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
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
andFalse
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 neithersearch
noritem_types
are provided.
get_summary
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
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
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, orNone
to move to the root level.
Returns:
None
move_items_to_folder
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 - IfTrue
, 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
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 - IfTrue
(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
List all groups that have access to this folder.
add_group
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
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
Refetch data for the folder.
Returns:
None
add_data_to_folder_job_cancel
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.