Upload & Register Data

Register Cloud Data

Using a JSON File (Recommended)

The following scripts initiate uploads from your cloud storage to a specified folder in Encord using a properly formatted JSON upload file. It works for all file types.

If Upload is still in progress, try again later! is returned, use the script to check the upload status to see whether the upload has finished.

Ensure that you:

Replace <private_key_path> with the path to your private key.
Replace <integration_title> with the title of the integration you want to use.
Replace <folder_name> with the folder name. The scripts assume that the specified folder name is unique.
Replace path/to/json/file.json with the path to a JSON file specifying which cloud storage files should be uploaded.
If creating a new folder, replace A folder to store my files with a meaningful description for your folder.
If creating a new folder, replace "my": "folder_metadata" with any metadata you want to add to the folder.

# Import dependencies
from encord import EncordUserClient
from encord.orm.dataset import LongPollingStatus
from encord.storage import FoldersSortBy

# Instantiate user client. Replace \<private_key_path> with the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>",
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
    )

# Specify the integration you want to use by replacing <integration_title> with the integration title
integrations = user_client.get_cloud_integrations()
integration_idx = [i.title for i in integrations].index("<integration_title>")
integration = integrations[integration_idx].id

# Find the storage folder by name
folder_name = "<folder_name>"  # Replace with your folder's name
folders = list(user_client.find_storage_folders(search=folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

# Ensure the folder was found
if folders:
    storage_folder = folders[0]

    # Initiate cloud data registration to the storage folder. Replace path/to/json/file.json with the path to your JSON file
    upload_job_id = storage_folder.add_private_data_to_folder_start(
        integration_id=integration, private_files="path/to/json/file.json", ignore_errors=True
    )

    # timeout_seconds determines how long the code waits after initiating upload before checking the upload status
    res = storage_folder.add_private_data_to_folder_get_result(upload_job_id, timeout_seconds=5)
    print(f"Execution result: {res}")

    if res.status == LongPollingStatus.PENDING:
        print("Upload is still in progress, try again later!")
    elif res.status == LongPollingStatus.DONE:
        print("Upload completed")
        if res.unit_errors:
            print("The following URLs failed to upload:")
            for e in res.unit_errors:
                print(e.object_urls)
    else:
        print(f"Upload failed: {res.errors}")
else:
    print("Folder not found")

# Import dependencies
from encord import EncordUserClient
from encord.orm.dataset import LongPollingStatus

# Instantiate user client. Replace <private_key_path> with the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>",
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
    )

# Specify the integration you want to use by replacing <integration_title> with the integration title
integrations = user_client.get_cloud_integrations()
integration_idx = [i.title for i in integrations].index("<integration_title>")
integration = integrations[integration_idx].id

# Create a storage folder
folder_name = "<folder_name>"
folder_description = "A folder to store my files"
folder_metadata = {"my": "folder_metadata"}
storage_folder = user_client.create_storage_folder(folder_name, folder_description,client_metadata=folder_metadata)

# Initiate cloud data registration to the storage folder. Replace path/to/json/file.json with the path to your JSON file
upload_job_id = storage_folder.add_private_data_to_folder_start(
integration_id=integration, private_files="path/to/json/file.json", ignore_errors=True
    )

# timeout_seconds determines how long the code waits after initiating upload until continuing and checking upload status
res = storage_folder.add_private_data_to_folder_get_result(upload_job_id, timeout_seconds=5)
print(f"Execution result: {res}")

if res.status == LongPollingStatus.PENDING:
    print("Upload is still in progress, try again later!")
elif res.status == LongPollingStatus.DONE:
    print("Upload completed")
    if res.unit_errors:
        print("The following URLs failed to upload:")
        for e in res.unit_errors:
            print(e.object_urls)
else:
    print(f"Upload failed: {res.errors}")

add_private_data_to_dataset job started with upload_job_id=c4026edb-4fw2-40a0-8f05-a1af7f465727.
SDK process can be terminated, this will not affect successful job execution.
You can follow the progress in the web app via notifications.
add_private_data_to_dataset job completed with upload_job_id=c4026edb-4fw2-40a0-8f05-a1af7f465727.

To update client metadata, include the "upsert_metadata": true flag in the upload JSON file. It can only be used in conjunction with "skip_duplicate_urls": true.

Use the following script to check the status of your private cloud registration.

If Upload is still in progress, try again later! is returned, run the script again to check the status at a later time.

Ensure that you:

Replace <upload_job_id> with the upload_job_id shown in the output of the script used to start the upload. In the example output of the script provided, the upload_job_id = c4026edb-4fw2-40a0-8f05-a1af7f465727.
Replace <private_key_path> with the path to your private key.
Replace <folder_name> with the folder name. The scripts assume that the specified folder name is unique.

# Import dependencies
from encord import EncordUserClient
from encord.orm.dataset import LongPollingStatus
from encord.orm.storage import FoldersSortBy

upload_job_id = <upload_job_id>

# Authenticate with Encord using the path to your private key. 
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>",
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
    )

# Define search parameters
folder_name_to_find = "<folder_name>"
search_result = user_client.find_storage_folders(
    search=folder_name_to_find,
    dataset_synced=None,
    order=FoldersSortBy.NAME,
    desc=False,
    page_size=1000
)

# Fetch the folder assuming it's the first one in the search result
storage_folder = next(iter(search_result), None)
if storage_folder is None:
    print(f"No folder found with name {folder_name_to_find}")

# Check upload status
res = storage_folder.add_private_data_to_folder_get_result(upload_job_id, timeout_seconds=5)
print(f"Execution result: {res}")

if res.status == LongPollingStatus.PENDING:
    print("Upload is still in progress, try again later!")
elif res.status == LongPollingStatus.DONE:
    print("Upload completed")
    if res.unit_errors:
        print("The following URLs failed to upload:")
        for e in res.unit_errors:
            print(e.object_urls)
else:
    print(f"Upload failed: {res.errors}")

Register Cloud Data Without a JSON File

Instead of using a JSON file to specify cloud files and URLs, you can use DataUploadItems. This method is recommended for cloud data registrations in the specific use cases listed below.

Increased Image Group File Registration

You can increase the speed at which Image Groups are registered to Encord by including imageMetadata for each image belonging to the image group. For this you must use the following method of importing images and creating Image Groups.

When the audioMetadata, imageMetadata, or videoMetadata flags are present in the JSON file, we directly use the supplied metadata without performing any additional validation, and do not store the file on our servers. It is crucial that the metadata you provide is accurate.

Ensure that you:

Replace <path_to_private_key> with your private key path
Enter the URLs of images you want to import and batch as an image group.
Provide the imageMetadata for your files by replacing the example values.
Enter a title for your image group.
Specify the name of the target folder to store the image group.
Replace <integration_id> with the id of the integration you want to use for the data registration.

from encord.orm.storage import DataUploadImageGroup, DataUploadImageGroupImage
from encord.orm.storage import CustomerProvidedImageMetadata
from encord import EncordUserClient
from encord.storage import DataUploadItems
from encord.orm.dataset import LongPollingStatus

# Instantiate Encord client
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<path_to_private_key>",
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Enter the URLs of images you want to add to the Image Group
private_cloud_urls = [
    "cloud/path/image1.jpg",
    "cloud/path/image2.jpg",
    "cloud/path/image3.jpg",
]

# Define the new image group using DataUploadImageGroup and DataUploadImageGroupImage
image_group = DataUploadImageGroup(
    images=[
        DataUploadImageGroupImage(
            url=private_cloud_url,
            image_metadata=CustomerProvidedImageMetadata(
                mime_type="image/jpeg",  # MIME type of the image
                file_size=100500,       # File size in bytes
                height=768,             # Image height in pixels
                width=1024,             # Image width in pixels
            ),
        )
        for private_cloud_url in private_cloud_urls
    ],
    title="Group from Frames",  # Title for the image group
)

# Specify the target folder
folder_name = "Target Folder Name"
storage_folder = next(user_client.find_storage_folders(
    search=folder_name, dataset_synced=None, page_size=1))

# Start the upload job
upload_job_id = storage_folder.add_private_data_to_folder_start(
    integration_id="<integration_id>",
    private_files=DataUploadItems(
        image_groups=[image_group]  # Add the new image group
    ),
    ignore_errors=True
)

# Monitor the upload status
res = storage_folder.add_private_data_to_folder_get_result(upload_job_id)
if res.status == LongPollingStatus.DONE:
    print("Image group registered successfully!")
else:
    print("Error registering image group.")

Create an Image Group from Existing Images

You can create Image Groups from individual images previously added to Encord. If the individual images include clientMetadata and are then grouped into an Image Group, this metadata is retained at the frame level within the Image Group. The following script combines three previously uploaded images in Encord into a single Image Group. In the following script:

Replace <private_key_path> with your private key path.
Replace the titles in the file_names list with the names of images to be grouped.
Replace <folder_name> with the title for the folder containing the files.
Provide a title for the image group.
Replace <integration_id> with the ID of the integration being used.
Add optional clientMetadata for the image group.

from encord.orm.storage import DataUploadImageGroupFromItems
from typing import List
from encord import EncordUserClient
from encord.orm.dataset import LongPollingStatus
from encord.storage import StorageItemType, FoldersSortBy, DataUploadItems

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>",
                # For US platform users use "https://api.us.encord.com"
                domain="https://api.encord.com",
            )
            

# Define a list of file names you want to search for
file_names = ["Image1.jpg", "Image2.jpg", "Image3.jpg"]

image_group_title = "My Image Group"

# Find the storage folder by name
folder_name = "<folder_name>"  # Replace with your folder's name
folders = list(user_client.find_storage_folders(search=folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

# Ensure the folder was found
if folders:
    storage_folder = folders[0]
else: 
    print ("Folder name not found")

# Specify the integration you want to use
integration_id = "<integration_id>"

# Loop through each file name in the list and search for it
for file_name in file_names:
    # Search for the specific data unit(s) using the file name
    items = storage_folder.list_items(
        search=file_name,
        is_in_dataset=None,  
        item_types=[StorageItemType.IMAGE],
        order=FoldersSortBy.NAME,
        desc=False,
        get_signed_urls=False,
        page_size=1000  # Expecting possibly multiple results
    )

    image_uuids = []
    # Retrieve the image UUIDs and add them to the list
    for item in items:
        image_uuids.append(item.uuid)

# Initialize the DataUploadImageGroupFromItems object with the necessary data
image_group = DataUploadImageGroupFromItems(
    image_items=image_uuids,           # List of UUIDs for the images to group
    title=image_group_title,            # Title for the group
    client_metadata={"client": "metadata", "description": "Group of 3 images"},
    create_video=False                 # Specify if you want a video to be generated
)

# Start the upload job for the image group
upload_job_id = storage_folder.add_private_data_to_folder_start(
    integration_id=integration_id,
    private_files= DataUploadItems(
        image_groups_from_items=[image_group]  # Add the group as an item
    ),
    ignore_errors=True
)

# Check the status of the upload
res = storage_folder.add_private_data_to_folder_get_result(upload_job_id)
if res.status == LongPollingStatus.DONE:
    print("Image group created successfully!")
else:
    print("There was an issue creating the image group.")

Local Data

Upload Local Data to an Existing Folder

The following scripts add data to a folder that already exists in Data > Files & Folders.

Each local file upload must start within 24 hours after its upload URL is issued. If an upload URL expires, rerun the upload to generate new URLs for the files. Encord-hosted Azure deployments configured with a static SAS token use the token’s configured expiry instead.

Replace <folder_name> with the name of the folder you want to add data to.
For images and videos replace User/path/to/my/file with the path to your image or video file.
For DICOM series replace User/path/to/dicom/file1 and User/path/to/dicom/file2 with the paths to the DICOM files you want to create a series from. Add as many file paths as necessary.
For image groups and image sequences, replace User/path/to/image/file1 and User/path/to/image/file2 with the paths to the image files you want to create an image group or image sequence from. Add as many file paths as necessary.

from encord import EncordUserClient
from encord.storage import FoldersSortBy

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>",
                # For US platform users use "https://api.us.encord.com"
                domain="https://api.encord.com",
            )

# Find the storage folder by name
folder_name = "<folder_name>"  # Replace with your folder's name
folders = list(user_client.find_storage_folders(search=folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

# Ensure the folder was found
if folders:
    storage_folder = folders[0]

    # Upload an image to the folder. Substitute file path
    file_path = "User/path/to/my/file"
    client_metadata = {"client": "metadata"}
    image_uuid = storage_folder.upload_image(file_path, None, client_metadata=client_metadata)
else:
    print("Folder not found")

from encord import EncordUserClient
from encord.storage import FoldersSortBy

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>",
                # For US platform users use "https://api.us.encord.com"
                domain="https://api.encord.com",
            )

# Find the storage folder by name
folder_name = "<folder_name>"  # Replace with your folder's name
folders = list(user_client.find_storage_folders(search=folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

# Ensure the folder was found
if folders:
    storage_folder = folders[0]

    # Upload a video to the folder. Substitute file path
    file_path = "User/path/to/my/video"
    client_metadata = {"client": "metadata"}
    video_uuid = storage_folder.upload_video(file_path, None, client_metadata=client_metadata)
else:
    print("Folder not found")

from encord import EncordUserClient
from encord.storage import FoldersSortBy

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>",
                # For US platform users use "https://api.us.encord.com"
                domain="https://api.encord.com",
            )

# Find the storage folder by name
folder_name = "<folder_name>"  # Replace with your folder's name
folders = list(user_client.find_storage_folders(search=folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

# Ensure the folder was found
if folders:
    storage_folder = folders[0]

    # Create an image group and upload it to the folder. Substitute file paths
    file_title = "<file_title>"
    file_paths = ["User/path/to/image/file1", "User/path/to/image/file2"]  # List of paths to image files
    client_metadata = {"client": "metadata"}
    group_uuid = storage_folder.create_image_group(
        file_paths,  
        file_title,
        client_metadata=client_metadata,
    )
else:
    print("Folder not found")

from encord import EncordUserClient
from encord.storage import FoldersSortBy

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>",
                # For US platform users use "https://api.us.encord.com"
                domain="https://api.encord.com",
            )

# Find the storage folder by name
folder_name = "<folder_name>"  # Replace with your folder's name
folders = list(user_client.find_storage_folders(search=folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

# Ensure the folder was found
if folders:
    storage_folder = folders[0]

    # Substitute file path to pdf
    file_path = "User/path/to/my/file.pdf"
    client_metadata = {"client": "metadata"}
    image_uuid = storage_folder.upload_pdf(file_path, None, client_metadata=client_metadata)
else:
    print("Folder not found")

from encord import EncordUserClient
from encord.storage import FoldersSortBy

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>",
                # For US platform users use "https://api.us.encord.com"
                domain="https://api.encord.com",
            )

# Find the storage folder by name
folder_name = "<folder_name>"  # Replace with your folder's name
folders = list(user_client.find_storage_folders(search=folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

# Ensure the folder was found
if folders:
    storage_folder = folders[0]

    # Substitute file path to audio
    file_path = "User/path/to/my/file.mp3"
    client_metadata = {"client": "metadata"}
    image_uuid = storage_folder.upload_audio(file_path, None, client_metadata=client_metadata)
else:
    print("Folder not found")

from encord import EncordUserClient
from encord.storage import FoldersSortBy

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>",
                # For US platform users use "https://api.us.encord.com"
                domain="https://api.encord.com",
            )

# Find the storage folder by name
folder_name = "<folder_name>"  # Replace with your folder's name
folders = list(user_client.find_storage_folders(search=folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

# Ensure the folder was found
if folders:
    storage_folder = folders[0]

    # Create an image sequence and upload it to the folder. Substitute file paths
    file_title = "<file_title>"
    file_paths = ["User/path/to/image/file1", "User/path/to/image/file2"]  # List of paths to image files
    client_metadata = {"client": "metadata"}
    sequence_uuid = storage_folder.create_image_sequence(
        file_paths,  
        file_title,
        client_metadata=client_metadata,
    )
else:
    print("Folder not found")

from encord import EncordUserClient
from encord.storage import FoldersSortBy

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>",
                # For US platform users use "https://api.us.encord.com"
                domain="https://api.encord.com",
            )

# Find the storage folder by name
folder_name = "<folder_name>"  # Replace with your folder's name
folders = list(user_client.find_storage_folders(search=folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

# Ensure the folder was found
if folders:
    storage_folder = folders[0]

    # Create a DICOM series and upload it to the folder. Substitute file paths
    file_title = "<file_title>"
    file_paths = ["User/path/to/dicom/file1", "User/path/to/dicom/file2"]  # List of paths to DICOM files
    client_metadata = {"client": "metadata"}
    series_uuid = storage_folder.create_dicom_series(
        file_paths,
        file_title,
        client_metadata=client_metadata,
    )
else:
    print("Folder not found")

from encord import EncordUserClient
from encord.storage import FoldersSortBy

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>",
                # For US platform users use "https://api.us.encord.com"
                domain="https://api.encord.com",
            )

# Find the storage folder by name
folder_name = "<folder_name>"  # Replace with your folder's name
folders = list(user_client.find_storage_folders(search=folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

# Ensure the folder was found
if folders:
    storage_folder = folders[0]

    # Upload NIfTI files to the folder. Substitute file path.
    file_title = "<file_title>"
    file_path = "User/path/to/nifti/file1"  # Path to NIfTI files
    client_metadata = {"client": "metadata"}
    series_uuid = storage_folder.upload_nifti(
        file_path,
        file_title,
        client_metadata=client_metadata,
    )
else:
    print("Folder not found")

from encord import EncordUserClient
from encord.storage import FoldersSortBy

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>",
                # For US platform users use "https://api.us.encord.com"
                domain="https://api.encord.com",
            )

# Find the storage folder by name
folder_name = "<folder_name>"  # Replace with your folder's name
folders = list(user_client.find_storage_folders(search=folder_name, dataset_synced=None, order=FoldersSortBy.NAME, desc=False, page_size=1000))

# Ensure the folder was found
if folders:
    storage_folder = folders[0]

    # Substitute file path to the text file
    file_path = "User/path/to/my/file.txt"
    client_metadata = {"client": "metadata"}
    text_uuid = storage_folder.upload_text(file_path, None, client_metadata=client_metadata)
else:
    print("Folder not found")

Upload Local Data to a New Folder

The following script creates a new folder in Data > Files & Folders and uploads image, video, DICOM, image group, or image sequence files to the newly created folder. A new folder is created each time the script is run. In the following scripts, ensure that you:

Replace <private_key_path> with the path to your private key.
Replace <folder_name> with the name you want to give your folder. The scripts assume that the specified folder name is unique.
Replace A folder to store my files with a meaningful description for your folder.
Replace my: folder_metadata with any metadata you want to add to the folder. Remove the line if you do not want to add any metadata to the folder.
For images and videos replace User/path/to/my/file with the path to your image or video file.
For DICOM series replace User/path/to/dicom/file1 and User/path/to/dicom/file2 with the paths to the DICOM files you want to create a series from. Add as many file paths as necessary.
For image groups and image sequences, replace User/path/to/image/file1 and User/path/to/image/file2 with the paths to the image files you want to create an image group or image sequence from. Add as many file paths as necessary.

from encord import EncordUserClient

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>",
                # For US platform users use "https://api.us.encord.com"
                domain="https://api.encord.com",
            )

# Create a storage folder
folder_name = "<folder_name>"
folder_description = "A folder to store my files"
folder_metadata = {"my": "folder_metadata"}
storage_folder = user_client.create_storage_folder(folder_name, folder_description,client_metadata=folder_metadata)

# Upload an image to the folder. Substitute file path
file_path = "User/path/to/my/file"
client_metadata = {"client": "metadata"}
image_uuid = storage_folder.upload_image(file_path, None, client_metadata=client_metadata)

from encord import EncordUserClient

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>",
                # For US platform users use "https://api.us.encord.com"
                domain="https://api.encord.com",
            )

# Create a storage folder
folder_name = "<folder_name>"
folder_description = "A folder to store my files"
folder_metadata = {"my": "folder_metadata"}
storage_folder = user_client.create_storage_folder(folder_name, folder_description,client_metadata=folder_metadata)

# Upload a video to the folder. Substitute file path
file_path = "User/path/to/my/file"
client_metadata = {"client": "metadata"}
video_uuid = storage_folder.upload_video(file_path, None, client_metadata=client_metadata)

from encord import EncordUserClient

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>",
                # For US platform users use "https://api.us.encord.com"
                domain="https://api.encord.com",
            )

# Create a storage folder
folder_name = "<folder_name>"
folder_description = "A folder to store my files"
folder_metadata = {"my": "folder_metadata"}
storage_folder = user_client.create_storage_folder(folder_name, folder_description,client_metadata=folder_metadata)

# Create an image group and upload it to the folder. Substitute file paths
file_title = "<file_title>"
file_paths = ["User/path/to/image/file1", "User/path/to/image/file2"] # List of paths to image files
client_metadata = {"client": "metadata"}
group_uuid = storage_folder.create_image_group(
        file_paths,  
        file_title,
        client_metadata=client_metadata,
    )

from encord import EncordUserClient

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>",
                # For US platform users use "https://api.us.encord.com"
                domain="https://api.encord.com",
            )

# Create a storage folder
folder_name = "<folder_name>"
folder_description = "A folder to store my files"
folder_metadata = {"my": "folder_metadata"}
storage_folder = user_client.create_storage_folder(folder_name, folder_description,client_metadata=folder_metadata)

# Create an image sequence and upload it to the folder. Substitute file paths
file_title = "<file_title>"
file_paths = ["User/path/to/image/file1", "User/path/to/image/file2"]
client_metadata = {"client": "metadata"}
sequence_uuid = storage_folder.create_image_group(
        file_paths,  # List of paths to image files
        file_title,
        client_metadata=client_metadata,
    )

from encord import EncordUserClient

# Instantiate Encord client by substituting the path to your private key
user_client = EncordUserClient.create_with_ssh_private_key(
                ssh_private_key_path="<private_key_path>",
                # For US platform users use "https://api.us.encord.com"
                domain="https://api.encord.com",
            )

# Create a storage folder
folder_name = "<folder_name>"
folder_description = "A folder to store my files"
folder_metadata = {"my": "folder_metadata"}
storage_folder = user_client.create_storage_folder(folder_name, folder_description,client_metadata=folder_metadata)

# Create a DICOM series and upload it to the folder. Substitute file paths
file_title = "<file_title>"
file_paths = ["User/path/to/dicom/file1", "User/path/to/dicom/file2"] # List of paths to DICOM files.
client_metadata = {"client": "metadata"}
series_uuid = storage_folder.create_dicom_series(
    file_paths,
    file_title,
    client_metadata=client_metadata,
)

List Data Units in a Folder

Listing the files in a folder can be used to verify that all data unit were successfully uploaded.

Replace <private_key_path> with the path to your private key.
Replace <folder_name> with the name you want to give your folder. The scripts assume that the specified folder name is unique.

from encord import EncordUserClient
from encord.orm.storage import StorageItemType, FoldersSortBy

# Authentication
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>",
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Find the storage folder by name
folder_name = "<folder_name>"  # Replace with your folder's name
folders = list(user_client.find_storage_folders(search=folder_name, page_size=1000))

# Ensure the folder was found
if folders:
    storage_folder = folders[0]

    # List all data units
    items = list(storage_folder.list_items())

    # Output the retrieved data units
    for item in items:
        print(f"UUID: {item.uuid}, Name: {item.name}, Type: {item.item_type}")
else:
    print("Folder not found.")

from encord import EncordUserClient
from encord.orm.storage import StorageItemType, FoldersSortBy

# Authentication
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>",
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Find the storage folder by name
folder_name = "<folder_name>"  # Replace with your folder's name
folders = list(user_client.find_storage_folders(search=folder_name, page_size=1000))

# Ensure the folder was found
if folders:
    storage_folder = folders[0]

    # List images
    images = list(storage_folder.list_items(item_types=[StorageItemType.IMAGE]))

    # Output the retrieved images
    for image in images:
        print(f"UUID: {image.uuid}, Name: {image.name}")
else:
    print("Folder not found.")

from encord import EncordUserClient
from encord.orm.storage import StorageItemType, FoldersSortBy

# Authentication
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>",
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Find the storage folder by name
folder_name = "<folder_name>"  # Replace with your folder's name
folders = list(user_client.find_storage_folders(search=folder_name, page_size=1000))

# Ensure the folder was found
if folders:
    storage_folder = folders[0]

    # List videos
    videos = list(storage_folder.list_items(item_types=[StorageItemType.VIDEO]))

    # Output the retrieved videos
    for video in videos:
        print(f"UUID: {video.uuid}, Name: {video.name}")
else:
    print("Folder not found.")

from encord import EncordUserClient
from encord.orm.storage import StorageItemType, FoldersSortBy

# Authentication
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>",
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Find the storage folder by name
folder_name = "<folder_name>"  # Replace with your folder's name
folders = list(user_client.find_storage_folders(search=folder_name, page_size=1000))

# Ensure the folder was found
if folders:
    storage_folder = folders[0]

    # List image groups
    image_groups = list(storage_folder.list_items(item_types=[StorageItemType.IMAGE_GROUP]))

    # Output the retrieved image groups
    for group in image_groups:
        print(f"UUID: {group.uuid}, Name: {group.name}")
else:
    print("Folder not found.")

from encord import EncordUserClient
from encord.orm.storage import StorageItemType, FoldersSortBy

# Authentication
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>",
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Find the storage folder by name
folder_name = "<folder_name>"  # Replace with your folder's name
folders = list(user_client.find_storage_folders(search=folder_name, page_size=1000))

# Ensure the folder was found
if folders:
    storage_folder = folders[0]

    # List image sequences
    image_sequences = list(storage_folder.list_items(item_types=[StorageItemType.IMAGE_SEQUENCE]))

    # Output the retrieved image sequences
    for sequence in image_sequences:
        print(f"UUID: {sequence.uuid}, Name: {sequence.name}")
else:
    print("Folder not found.")

from encord import EncordUserClient
from encord.orm.storage import StorageItemType, FoldersSortBy

# Authentication
user_client = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path="<private_key_path>",
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Find the storage folder by name
folder_name = "<folder_name>"  # Replace with your folder's name
folders = list(user_client.find_storage_folders(search=folder_name, page_size=1000))

# Ensure the folder was found
if folders:
    storage_folder = folders[0]

    # List DICOM series
    dicom_series = list(storage_folder.list_items(item_types=[StorageItemType.DICOM_SERIES]))

    # Output the retrieved DICOM series
    for dicom in dicom_series:
        print(f"UUID: {dicom.uuid}, Name: {dicom.name}")
else:
    print("Folder not found.")

Get Started

General

Data

Ontologies

Projects

Labels

DICOM

Upload & Register Data

Register Cloud Data

Using a JSON File (Recommended)

Register Cloud Data Without a JSON File

Increased Image Group File Registration

Create an Image Group from Existing Images

Local Data

Upload Local Data to an Existing Folder

Upload Local Data to a New Folder

List Data Units in a Folder

​Register Cloud Data

​Using a JSON File (Recommended)

​Register Cloud Data Without a JSON File

​Increased Image Group File Registration

​Create an Image Group from Existing Images

​Local Data

​Upload Local Data to an Existing Folder

​Upload Local Data to a New Folder

​List Data Units in a Folder

Register Cloud Data

Using a JSON File (Recommended)

Register Cloud Data Without a JSON File

Increased Image Group File Registration

Create an Image Group from Existing Images

Local Data

Upload Local Data to an Existing Folder

Upload Local Data to a New Folder

List Data Units in a Folder