Data Groups

Data Groups let you put individual files into groups so that they are easier to annotate and review together. They unlock multi-tile and multimodal labeling. Data Groups are similar to image groups, but they can hold any data type (images, videos, audio files, text files, PDFs and DICOM series), and they support grid, carousel and custom layouts in the Label Editor.

You can use Data Groups in non-Consensus Projects and Consensus Projects with Review & Refine nodes. Determine Consensus nodes are not yet supported.

For an end-to-end example of how you can use Data Groups, go here.
For instructions on exporting labels go here.
To label Data Groups, including adding a classification to a whole Data Group, see Data Groups & Label Spaces.

Deprecated (SDK v0.1.195): Working on a Data Group’s child label rows directly — by passing include_children=True to list_label_rows_v2(), or by reading DataGroupMetadata.children — is deprecated. Work on the Data Group parent instead, and access each child through its Label Space with LabelRowV2.get_spaces(). See Data Groups & Label Spaces for the full workflow. The examples on this page use the parent-based approach.

Time series files in a Data Group share the group’s timeline. To keep a time series synchronized with a video in the same group, index the CSV by video frame (a frame column) instead of by time (for example time_ms). See Align Time Series with Video.

Create Data Groups

Each code example in this section does the following:

Specifies the files (data units) to add to each Data Group.
Creates the Data Groups and sets their layout in the Label Editor.
Adds the Data Groups to a Dataset.
Adds the Dataset to a Project.

Some examples create several Data Groups in one call with create_data_groups. To create a single Data Group, use create_data_group instead. It takes one group and returns one UUID.

Rules for Creating Data Groups

Encord checks the following when you create a Data Group. If a check fails, the call raises an error.

You need Admin access to the folder you create the Data Groups in, and access to every file you add.
You can’t create Data Groups in a cloud-synced folder. Create them in a different folder.
Grid and carousel Data Groups need between 2 and 50 files. Custom layouts can show up to 50 tiles.
Each file can appear only once in a Data Group.
A Data Group can’t contain another Data Group, an image group, a scene, or a single DICOM file. To group DICOM data, add DICOM series.
If you don’t give a name, Encord names the Data Group data-group- followed by 8 random characters.
create_data_groups can create up to 1,500 Data Groups per call. It sends all the groups in one request. If any group fails a check, none of the groups are created.
In the SDK, only custom Data Groups (DataGroupCustom) accept settings such as read-only tiles, a fixed layout, or multi-layer labels. DataGroupGrid and DataGroupCarousel have no settings field. If you pass settings to them, the SDK ignores it without raising an error, and the Data Group is created without those settings.

To use settings with a carousel layout, create a DataGroupCustom with a single DataUnitCarouselTile as the layout. This matches the layout Encord builds for DataGroupCarousel:

from uuid import UUID

from encord.orm.group_layout import DataUnitCarouselTile, LayoutSettings, TileSettings
from encord.orm.storage import DataGroupCustom

group = folder.create_data_group(
    DataGroupCustom(
        name="carousel-with-settings",
        layout_contents={
            "reference": UUID("00000000-0000-0000-0000-000000000000"),  # Replace with File ID
            "frame-1": UUID("11111111-1111-1111-1111-111111111111"),  # Replace with File ID
            "frame-2": UUID("22222222-2222-2222-2222-222222222222"),  # Replace with File ID
        },
        layout=DataUnitCarouselTile(
            keys=["reference", "frame-1", "frame-2"],
            carousel_position="left",
            carousel_size=20,
        ),
        settings=LayoutSettings(tile_settings={"reference": TileSettings(is_read_only=True)}),
    )
)

For a grid layout, build the grid yourself with LayoutGrid and DataUnitTile, as shown in Data Group - Custom.

You can’t change a Data Group’s files, layout or settings after you create it. To make a change, create a new Data Group. See Change the Layout or Settings of a Data Group.

Data Group - Grid (Default)

Grid Data Groups allow you to arrange multiple data units in a fixed, ordered grid within the Label Editor. Encord arranges the data units in a near-square grid, in the order you list them. You don’t choose the number of rows or columns. 3 data unit Data Group Grid

12 data unit Data Group Grid

Requirements To display data units in a grid layout, you need:

A list of data unit UUIDs in the exact order they should appear in the grid.
A DataGroupGrid(...) for each Data Group you create.

Example

Data Group - Grid

from uuid import UUID

from encord.constants.enums import DataType
from encord.orm.storage import DataGroupGrid, StorageItemType
from encord.user_client import EncordUserClient

# --- Configuration ---
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your access key
FOLDER_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Folder ID
DATASET_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Dataset ID
PROJECT_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Project ID

# --- Connect to Encord ---
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

folder = user_client.get_storage_folder(FOLDER_ID)

created_group_uuids = folder.create_data_groups(
    [
        DataGroupGrid(
            name="group-grid-001",
            layout_contents=[
                UUID("00000000-0000-0000-0000-000000000000"),
                UUID("11111111-1111-1111-1111-111111111111"),
                UUID("22222222-2222-2222-2222-222222222222"),
                UUID("33333333-3333-3333-3333-333333333333"),
            ],
            client_metadata={"key": "value"},
        ),
        DataGroupGrid(
            name="group-grid-002",
            layout_contents=[
                UUID("44444444-4444-4444-4444-444444444444"),
                UUID("55555555-5555-5555-5555-555555555555"),
                UUID("66666666-6666-6666-6666-666666666666"),
                UUID("77777777-7777-7777-7777-777777777777"),
            ],
            client_metadata={"key": "value"},
        ),
        DataGroupGrid(
            name="group-grid-003",
            layout_contents=[
                UUID("88888888-8888-8888-8888-888888888888"),
                UUID("99999999-9999-9999-9999-999999999999"),
                UUID("12312312-3123-1231-2312-312312312312"),
                UUID("45645645-6456-4564-5645-645645645645"),
            ],
            client_metadata={"key": "value"},
        ),
    ]
)

print("✅ Created groups:", created_group_uuids)


# --- Add all the Data Groups in a folder to a Dataset ---
group_items = folder.list_items(item_types=[StorageItemType.GROUP])
d = user_client.get_dataset(DATASET_ID)
d.link_items([item.uuid for item in group_items])

# --- Add the Dataset to a Project ---
p = user_client.get_project(PROJECT_ID)
p.add_datasets([DATASET_ID])

# --- Retrieve and inspect Data Group label rows ---
rows = p.list_label_rows_v2()

# Inspect each Data Group's children through its Label Spaces
for row in rows:
    if row.data_type == DataType.GROUP:
        row.initialise_labels()
        for space in row.get_spaces():
            print(
                f"space_id: {space.space_id}, "
                f"file_name: {space.metadata.file_name}, "
                f"layout_key: {space.metadata.layout_key}"
            )

Data Group - Carousel/List

The order of data units in a Data Group determines how they are arranged in the Label Editor. In the carousel/list layout, a scrollable panel on the left shows all data units in the Data Group, while the currently selected data unit appears in the main editor view.

Requirements To display data units in a carousel layout, you need:

A list of data unit UUIDs in the exact order they should appear in the carousel.
A DataGroupCarousel(...) for each Data Group you create.

You can also pass a plain list of UUIDs to create_data_group or create_data_groups. Each list creates a carousel Data Group.

Example

Data Group - Carousel

from uuid import UUID

from encord.constants.enums import DataType
from encord.orm.storage import DataGroupCarousel, StorageItemType
from encord.user_client import EncordUserClient

# --- Configuration ---
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your access key
FOLDER_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Folder ID
DATASET_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Dataset ID
PROJECT_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Project ID

# --- Connect to Encord ---
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

folder = user_client.get_storage_folder(FOLDER_ID)

created_group_uuids = folder.create_data_groups(
    [
        DataGroupCarousel(
            name="group-carousel-001",
            layout_contents=[
                UUID("00000000-0000-0000-0000-000000000000"), # Replace with File ID 
                UUID("11111111-1111-1111-1111-111111111111"), # Replace with File ID 
                UUID("22222222-2222-2222-2222-222222222222"), # Replace with File ID 
                UUID("33333333-3333-3333-3333-333333333333"), # Replace with File ID 
            ],
            client_metadata={"key": "value"},
        ),
        DataGroupCarousel(
            name="group-carousel-002",
            layout_contents=[
                UUID("44444444-4444-4444-4444-444444444444"), # Replace with File ID 
                UUID("55555555-5555-5555-5555-555555555555"), # Replace with File ID 
                UUID("66666666-6666-6666-6666-666666666666"), # Replace with File ID 
                UUID("77777777-7777-7777-7777-777777777777"), # Replace with File ID 
            ],
            client_metadata={"key": "value"},
        ),
        DataGroupCarousel(
            name="group-carousel-003",
            layout_contents=[
                UUID("88888888-8888-8888-8888-888888888888"), # Replace with File ID 
                UUID("99999999-9999-9999-9999-999999999999"), # Replace with File ID 
                UUID("12312312-3123-1231-2312-312312312312"), # Replace with File ID 
                UUID("45645645-6456-4564-5645-645645645645"), # Replace with File ID 
            ],
            client_metadata={"key": "value"},
        ),
    ]
)

print("✅ Created carousel groups:", created_group_uuids)

# --- Add all the Data Groups in a folder to a Dataset ---
group_items = folder.list_items(item_types=[StorageItemType.GROUP])
d = user_client.get_dataset(DATASET_ID)
d.link_items([item.uuid for item in group_items])

# --- Add the Dataset to a Project ---
p = user_client.get_project(PROJECT_ID)
p.add_datasets([DATASET_ID])

# --- Retrieve and inspect Data Group label rows ---
rows = p.list_label_rows_v2()

# Inspect each Data Group's children through its Label Spaces
for row in rows:
    if row.data_type == DataType.GROUP:
        row.initialise_labels()
        for space in row.get_spaces():
            print(
                f"space_id: {space.space_id}, "
                f"file_name: {space.metadata.file_name}, "
                f"layout_key: {space.metadata.layout_key}"
            )

Data Group - Custom

Custom Data Groups give you full control over how multiple data units are arranged in the Label Editor. Unlike grid or carousel layouts (which use ordered lists of UUIDs), custom layouts use keys:

Map keys to data unit UUIDs.
Build a layout tree that references those keys and defines:
- Split direction (“row” or “column”)
- Space split (“splitPercentage”)
- Where each tile (data unit) appears in the Label Editor

Custom Data Groups can be configured using plain Python dictionaries or ORMs.

Using Python dictionaries — a lightweight, flexible approach
Using ORMs — a more structured approach with stronger typing and validation

Both approaches are functionally equivalent. Choose the one that best fits your workflow.

Custom Data Groups Details

To create a custom data group, you must define a layout, layout contents, and (optionally) settings. These components work together to control how data units are displayed and behave.1. Define the layout structureThe layout defines how the Label Editor is split and which data units appear in each section. Layouts are expressed as a tree of containers and data unit tiles.

from encord.orm.group_layout import DataUnitTile, LayoutGrid

layout = LayoutGrid(
    direction="row",
    first=DataUnitTile(key="instructions"),
    second=DataUnitTile(key="image"),
    split_percentage=30,
)

layout = {
    "direction": "row",
    "first": {"type": "data_unit", "key": "instructions"},
    "second": {"type": "data_unit", "key": "image"},
    "splitPercentage": 30,
}

2. Provide layout contentslayout_contents maps each layout key to a data unit UUID. Every key referenced in the layout must be defined here.

from uuid import UUID

layout_contents = {
    "instructions": UUID("00000000-0000-0000-0000-000000000000"),
    "image": UUID("11111111-1111-1111-1111-111111111111"),
}

from uuid import UUID

layout_contents = {
    "instructions": UUID("00000000-0000-0000-0000-000000000000"),
    "image": UUID("11111111-1111-1111-1111-111111111111"),
}

3. (Optional) Configure tile settingsTile settings let you control behavior such as making a tile read-only (is_read_only) or showing a title in the tile’s toolbar (title). Settings reference the same keys used in the layout. LayoutSettings also has fixed_layout, which stops annotators from adding, removing or changing panes, and has_multilayer_labels (see Multi-Layer Data Groups).

from encord.orm.group_layout import LayoutSettings, TileSettings

settings = LayoutSettings(
    tile_settings={
        "instructions": TileSettings(is_read_only=True)
    }
)

settings = {
    "tile_settings": {
        "instructions": {"is_read_only": True}
    }
}

4. Create the Data GroupFinally, create the Data Group by passing the layout, layout contents, and settings.

from encord.orm.storage import DataGroupCustom

group = folder.create_data_group(
    DataGroupCustom(
        name="my group",
        layout_contents=layout_contents,
        layout=layout,
        settings=settings,
    )
)

from encord.orm.storage import DataGroupCustom

# DataGroupCustom accepts the layout and settings as plain dictionaries
group = folder.create_data_group(
    DataGroupCustom(
        name="my group",
        layout_contents=layout_contents,
        layout=layout,
        settings=settings,
    )
)

Layout rulesEncord rejects a custom Data Group that breaks any of these rules:

split_percentage (splitPercentage in dictionaries) must be between 5 and 95.
For a DataUnitCarouselTile, carousel_size must be between 10 and 70, and carousel_position must be "left", "right", "top" or "bottom".
Every key in layout_contents must appear in the layout, and no key can appear twice. The only exception is keys listed in timeline.
Keys in tile_settings must be keys in layout_contents, and at least one tile must not be read-only.
timeline is an optional list of keys for audio and time series files. These files appear in the timeline instead of as tiles. Only audio and time series files can go in the timeline. If every key is in timeline, you can leave out layout.

Custom Data Group Examples

Example: 2-panel split
Example: Instructions + 2×2 grid layout
Example Carousel-style in a Grid-style

A simple layout: left panel (instructions) and right panel (image). Simple Custom Layout

from uuid import UUID

from encord.orm.storage import DataGroupCustom, StorageItemType
from encord.user_client import EncordUserClient
from encord.orm.group_layout import (
    DataUnitTile,
    LayoutGrid,
    LayoutSettings,
    TileSettings,
)

# --- Configuration ---
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your access key
FOLDER_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Folder ID
DATASET_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Dataset ID
PROJECT_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Project ID

# --- Connect to Encord ---
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

folder = user_client.get_storage_folder(FOLDER_ID)

layout = LayoutGrid(
    direction="row",
    first=DataUnitTile(key="instructions"),
    second=DataUnitTile(key="image"),
    split_percentage=30,  # 30% for "instructions", 70% for "image"
)


layout_contents = {
    "instructions": UUID("00000000-0000-0000-0000-000000000000"),  # File ID
    "image": UUID("11111111-1111-1111-1111-111111111111"),        # File ID
}

settings = LayoutSettings(
    tile_settings={
        "instructions": TileSettings(is_read_only=True)
    }
)

group = folder.create_data_group(
    DataGroupCustom(
        name="example-custom-group",
        layout=layout,
        layout_contents=layout_contents,
        client_metadata={"key": "value"},
        settings=settings,
    )
)

# Add all the data groups in a folder to a Dataset
group_items = folder.list_items(item_types=[StorageItemType.GROUP])
d = user_client.get_dataset(DATASET_ID)
d.link_items([item.uuid for item in group_items])

# Add the Dataset with the Data Groups to a Project
p = user_client.get_project(PROJECT_ID)
p.add_datasets([DATASET_ID])
rows = p.list_label_rows_v2()

from uuid import UUID

from encord.constants.enums import DataType
from encord.orm.storage import DataGroupCustom, StorageItemType
from encord.user_client import EncordUserClient

# --- Configuration ---
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your access key
FOLDER_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Folder ID
DATASET_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Dataset ID
PROJECT_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Project ID

# --- Connect to Encord ---
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

folder = user_client.get_storage_folder(FOLDER_ID)

layout = {
    "direction": "row",
    "first": {"type": "data_unit", "key": "instructions"},
    "second": {"type": "data_unit", "key": "image"},
    "splitPercentage": 30,  # 30% for "instructions", 70% for "image"
}

layout_contents = {
    "instructions": UUID("00000000-0000-0000-0000-000000000000"), # Replace with File ID 
    "image": UUID("11111111-1111-1111-1111-111111111111"), # Replace with File ID 
}

settings = {
    "tile_settings": {
        "instructions": {"is_read_only": True},
    }
}

group = folder.create_data_group(
    DataGroupCustom(
        name="example-custom-group",
        layout=layout,
        layout_contents=layout_contents,
        client_metadata={"key": "value"},
        settings=settings,
    )
)

# Add all the data groups in a folder to a Dataset
group_items = folder.list_items(item_types=[StorageItemType.GROUP])
d = user_client.get_dataset(DATASET_ID)
d.link_items([item.uuid for item in group_items])

# Add the Dataset with the Data Groups to a Project
p = user_client.get_project(PROJECT_ID)
p.add_datasets([DATASET_ID])
rows = p.list_label_rows_v2()

This example:

Uses a column layout overall.
Shows “instructions” (a text data unit) at the top (20% height, read-only).
Underneath “instructions”, a 2×2 grid of videos:
- Row 1: “top-left” | “top-right”
- Row 2: “bottom-left” | “bottom-right”

from uuid import UUID

from encord.constants.enums import DataType
from encord.orm.storage import DataGroupCustom, StorageItemType
from encord.user_client import EncordUserClient
from encord.orm.group_layout import (
    DataUnitTile,
    LayoutGrid,
    LayoutSettings,
    TileSettings,
)

# --- Configuration ---
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your access key
FOLDER_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Folder ID
DATASET_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Dataset ID
PROJECT_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Project ID

# --- Connect to Encord ---
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

folder = user_client.get_storage_folder(FOLDER_ID)

# --- Reusable layout and settings ---
layout = LayoutGrid(
    direction="column",
    first=DataUnitTile(key="instructions"),
    second=LayoutGrid(
        direction="column",
        first=LayoutGrid(
            direction="row",
            first=DataUnitTile(key="top-left"),
            second=DataUnitTile(key="top-right"),
            split_percentage=50,
        ),
        second=LayoutGrid(
            direction="row",
            first=DataUnitTile(key="bottom-left"),
            second=DataUnitTile(key="bottom-right"),
            split_percentage=50,
        ),
        split_percentage=50,
    ),
    split_percentage=20,
)

settings = LayoutSettings(
    tile_settings={
        "instructions": TileSettings(is_read_only=True)
    }
)

# --- Group definitions (name + UUIDs) ---
groups = [
    {
        "name": "group-001",
        "uuids": {
            "instructions": UUID("00000000-0000-0000-0000-000000000000"), # Replace with File ID. This data unit appears at the top of the Label Editor.
            "top-left": UUID("11111111-1111-1111-1111-111111111111"), # Replace with File ID. This data unit appears under the "instructions" data unit at the top left of the Label Editor.
            "top-right": UUID("22222222-2222-2222-2222-222222222222"), # Replace with File ID. This data unit appears under the "instructions" data unit at the top right of the Label Editor.
            "bottom-left": UUID("33333333-3333-3333-3333-333333333333"), # Replace with File ID. This data unit appears under the top left data unit in the Label Editor.
            "bottom-right": UUID("44444444-4444-4444-4444-444444444444"), # Replace with File ID. This data unit appears under the top right data unit in the Label Editor.
        },
    },
    {
        "name": "group-002",
        "uuids": {
            "instructions": UUID("55555555-5555-5555-5555-555555555555"), # Replace with File ID. This data unit appears at the top of the Label Editor.
            "top-left": UUID("66666666-6666-6666-6666-666666666666"), # Replace with File ID. This data unit appears under the "instructions" data unit at the top left of the Label Editor.
            "top-right": UUID("77777777-7777-7777-7777-777777777777"), # Replace with File ID. This data unit appears under the "instructions" data unit at the top right of the Label Editor.
            "bottom-left": UUID("88888888-8888-8888-8888-888888888888"), # Replace with File ID. This data unit appears under the top left data unit in the Label Editor.
            "bottom-right": UUID("99999999-9999-9999-9999-999999999999"), # Replace with File ID. This data unit appears under the top right data unit in the Label Editor.
        },
    },
    {
        "name": "group-003",
        "uuids": {
            "instructions": UUID("12312312-3123-1231-2312-312312312312"), # Replace with File ID. This data unit appears at the top of the Label Editor.
            "top-left": UUID("23232323-2323-2323-2323-232323232323"), # Replace with File ID. This data unit appears under the "instructions" data unit at the top left of the Label Editor.
            "top-right": UUID("31313131-3131-3131-3131-313131313131"), # Replace with File ID. This data unit appears under the "instructions" data unit at the top right of the Label Editor.
            "bottom-left": UUID("45645645-6456-4564-5645-645645645645"), # Replace with File ID. This data unit appears under the top left data unit in the Label Editor.
            "bottom-right": UUID("56565656-6565-5656-6565-656565656565"), # Replace with File ID. This data unit appears under the top right data unit in the Label Editor.
        },
    },
    # More groups...
]

# Create the Data Groups

for g in groups:
    group = folder.create_data_group(
        DataGroupCustom(
            name=g["name"],
            layout=layout,
            layout_contents=g["uuids"],
            settings=settings,
        )
    )
    print(f"✅ Created group '{g['name']}' with UUID {group}")

# Add all the data groups in a folder to a Dataset
group_items = folder.list_items(item_types=[StorageItemType.GROUP])
d = user_client.get_dataset(DATASET_ID)
d.link_items([item.uuid for item in group_items])

# Add the Dataset with the Data Groups to a Project
p = user_client.get_project(PROJECT_ID)
p.add_datasets([DATASET_ID])
rows = p.list_label_rows_v2()

# Data Group labels are accessed through the parent row's Label Spaces
for row in rows:
    if row.data_type == DataType.GROUP:
        row.initialise_labels()
        for space in row.get_spaces():
            print(
                f"space_id: {space.space_id}, "
                f"file_name: {space.metadata.file_name}, "
                f"layout_key: {space.metadata.layout_key}"
            )

from uuid import UUID

from encord.constants.enums import DataType
from encord.orm.storage import DataGroupCustom, StorageItemType
from encord.user_client import EncordUserClient

# --- Configuration ---
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your access key
FOLDER_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Folder ID
DATASET_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Dataset ID
PROJECT_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Project ID

# --- Connect to Encord ---
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

folder = user_client.get_storage_folder(FOLDER_ID)

# --- Reusable layout and settings ---
layout = {
    "direction": "column",
    "first": {"type": "data_unit", "key": "instructions"},
    "second": {
        "direction": "column",
        "first": {
            "direction": "row",
            "first": {"type": "data_unit", "key": "top-left"},
            "second": {"type": "data_unit", "key": "top-right"},
            "splitPercentage": 50,
        },
        "second": {
            "direction": "row",
            "first": {"type": "data_unit", "key": "bottom-left"},
            "second": {"type": "data_unit", "key": "bottom-right"},
            "splitPercentage": 50,
        },
        "splitPercentage": 50,
    },
    "splitPercentage": 20,
}
settings = {"tile_settings": {"instructions": {"is_read_only": True}}}

# --- Group definitions (name + UUIDs) ---
groups = [
    {
        "name": "group-001",
        "uuids": {
            "instructions": UUID("00000000-0000-0000-0000-000000000000"), # Replace with File ID. This data unit appears at the top of the Label Editor.
            "top-left": UUID("11111111-1111-1111-1111-111111111111"), # Replace with File ID. This data unit appears under the "instructions" data unit at the top left of the Label Editor.
            "top-right": UUID("22222222-2222-2222-2222-222222222222"), # Replace with File ID. This data unit appears under the "instructions" data unit at the top right of the Label Editor.
            "bottom-left": UUID("33333333-3333-3333-3333-333333333333"), # Replace with File ID. This data unit appears under the top left data unit in the Label Editor.
            "bottom-right": UUID("44444444-4444-4444-4444-444444444444"), # Replace with File ID. This data unit appears under the top right data unit in the Label Editor.
        },
    },
    {
        "name": "group-002",
        "uuids": {
            "instructions": UUID("55555555-5555-5555-5555-555555555555"), # Replace with File ID. This data unit appears at the top of the Label Editor.
            "top-left": UUID("66666666-6666-6666-6666-666666666666"), # Replace with File ID. This data unit appears under the "instructions" data unit at the top left of the Label Editor.
            "top-right": UUID("77777777-7777-7777-7777-777777777777"), # Replace with File ID. This data unit appears under the "instructions" data unit at the top right of the Label Editor.
            "bottom-left": UUID("88888888-8888-8888-8888-888888888888"), # Replace with File ID. This data unit appears under the top left data unit in the Label Editor.
            "bottom-right": UUID("99999999-9999-9999-9999-999999999999"), # Replace with File ID. This data unit appears under the top right data unit in the Label Editor.
        },
    },
    {
        "name": "group-003",
        "uuids": {
            "instructions": UUID("12312312-3123-1231-2312-312312312312"), # Replace with File ID. This data unit appears at the top of the Label Editor.
            "top-left": UUID("23232323-2323-2323-2323-232323232323"), # Replace with File ID. This data unit appears under the "instructions" data unit at the top left of the Label Editor.
            "top-right": UUID("31313131-3131-3131-3131-313131313131"), # Replace with File ID. This data unit appears under the "instructions" data unit at the top right of the Label Editor.
            "bottom-left": UUID("45645645-6456-4564-5645-645645645645"), # Replace with File ID. This data unit appears under the top left data unit in the Label Editor.
            "bottom-right": UUID("56565656-6565-5656-6565-656565656565"), # Replace with File ID. This data unit appears under the top right data unit in the Label Editor.
        },
    },
    # More groups...
]

# Create the Data Groups

for g in groups:
    group = folder.create_data_group(
        DataGroupCustom(
            name=g["name"],
            layout=layout,
            layout_contents=g["uuids"],
            settings=settings,
        )
    )
    print(f"✅ Created group '{g['name']}' with UUID {group}")

# Add all the data groups in a folder to a Dataset
group_items = folder.list_items(item_types=[StorageItemType.GROUP])
d = user_client.get_dataset(DATASET_ID)
d.link_items([item.uuid for item in group_items])

# Add the Dataset with the Data Groups to a Project
p = user_client.get_project(PROJECT_ID)
p.add_datasets([DATASET_ID])
rows = p.list_label_rows_v2()

# Data Group labels are accessed through the parent row's Label Spaces
for row in rows:
    if row.data_type == DataType.GROUP:
        row.initialise_labels()
        for space in row.get_spaces():
            print(
                f"space_id: {space.space_id}, "
                f"file_name: {space.metadata.file_name}, "
                f"layout_key: {space.metadata.layout_key}"
            )

This example inserts a carousel-style Data Group inside a grid-style Data Group.

from uuid import UUID

from encord.user_client import EncordUserClient
from encord.orm.storage import DataGroupCustom
from encord.orm.group_layout import (
    LayoutGrid,
    LayoutSettings,
    DataUnitTile,
    DataUnitCarouselTile,
)

# User Input

SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your access key
FOLDER_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Folder ID
GROUP_NAME = "carousel-inside-grid"

# --- Connect to Encord ---
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

folder = user_client.get_storage_folder(FOLDER_ID)

# Replace these with real file UUIDs
LAYOUT_CONTENTS = {
    "g1": UUID("11111111-1111-1111-1111-111111111111"),
    "g2": UUID("22222222-2222-2222-2222-222222222222"),
    "g3": UUID("33333333-3333-3333-3333-333333333333"),
    "g4": UUID("44444444-4444-4444-4444-444444444444"),
    "g5": UUID("55555555-5555-5555-5555-555555555555"),
    "g6": UUID("66666666-6666-6666-6666-666666666666"),
    "g7": UUID("77777777-7777-7777-7777-777777777777"),
    "g8": UUID("88888888-8888-8888-8888-888888888888"),
    "g9": UUID("99999999-9999-9999-9999-999999999999"),
    "c1": UUID("aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"),
    "c2": UUID("bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb"),
    "c3": UUID("cccccccc-cccc-cccc-cccc-cccccccccccc"),
    "c4": UUID("dddddddd-dddd-dddd-dddd-dddddddddddd"),
}

# 3x3 grid on the left
row_1 = LayoutGrid(
    direction="row",
    first=DataUnitTile(key="g1"),
    second=LayoutGrid(
        direction="row",
        first=DataUnitTile(key="g2"),
        second=DataUnitTile(key="g3"),
        split_percentage=50,
    ),
    split_percentage=33,
)

row_2 = LayoutGrid(
    direction="row",
    first=DataUnitTile(key="g4"),
    second=LayoutGrid(
        direction="row",
        first=DataUnitTile(key="g5"),
        second=DataUnitTile(key="g6"),
        split_percentage=50,
    ),
    split_percentage=33,
)

row_3 = LayoutGrid(
    direction="row",
    first=DataUnitTile(key="g7"),
    second=LayoutGrid(
        direction="row",
        first=DataUnitTile(key="g8"),
        second=DataUnitTile(key="g9"),
        split_percentage=50,
    ),
    split_percentage=33,
)

grid_3x3 = LayoutGrid(
    direction="column",
    first=row_1,
    second=LayoutGrid(
        direction="column",
        first=row_2,
        second=row_3,
        split_percentage=50,
    ),
    split_percentage=33,
)

# Carousel on the right
carousel_panel = DataUnitCarouselTile(
    keys=["c1", "c2", "c3", "c4"],
    carousel_position="right",
    carousel_size=25,
)

# Final layout
layout = LayoutGrid(
    direction="row",
    first=grid_3x3,
    second=carousel_panel,
    split_percentage=78,
)

settings = LayoutSettings(fixed_layout=True)

group_uuid = folder.create_data_group(
    DataGroupCustom(
        name=GROUP_NAME,
        layout=layout,
        layout_contents=LAYOUT_CONTENTS,
        settings=settings,
    )
)

print(f"Created data group: {group_uuid}")

Data Groups for DICOM Studies

To annotate DICOM data at the study level, create one Data Group per study that contains every series in that study. You can then classify the entire Data Group to apply labels to the whole study. The following example lists the DICOM series in a folder, groups them by their Study Instance UID (dicom_study_uid), and creates a carousel Data Group for each study. Studies with more than 50 series are split across multiple Data Groups, because Data Groups are limited to 50 data units.

Data Groups for DICOM Studies

from collections import defaultdict
from typing import Dict, List

from encord.orm.storage import DataGroupCarousel, StorageItemType
from encord.storage import StorageItem
from encord.user_client import EncordUserClient

# --- Configuration ---
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your access key
FOLDER_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the ID of the Folder containing your DICOM series
DATASET_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Dataset ID
PROJECT_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Project ID
MAX_GROUP_SIZE = 50  # Data Groups are limited to 50 data units

# --- Connect to Encord ---
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

folder = user_client.get_storage_folder(FOLDER_ID)

# --- Group the DICOM series in the folder by Study Instance UID ---
series_by_study: Dict[str, List[StorageItem]] = defaultdict(list)
for item in folder.list_items(item_types=[StorageItemType.DICOM_SERIES]):
    if item.dicom_study_uid:
        series_by_study[item.dicom_study_uid].append(item)

# --- Define one Data Group per study ---
data_groups = []
for study_uid, series in series_by_study.items():
    series.sort(key=lambda s: s.name)
    for start in range(0, len(series), MAX_GROUP_SIZE):
        chunk = series[start : start + MAX_GROUP_SIZE]
        suffix = f"-part-{start // MAX_GROUP_SIZE + 1}" if len(series) > MAX_GROUP_SIZE else ""
        data_groups.append(
            DataGroupCarousel(
                name=f"study-{study_uid}{suffix}",
                layout_contents=[s.uuid for s in chunk],
                client_metadata={"dicom_study_uid": study_uid},
            )
        )

created_group_uuids = folder.create_data_groups(data_groups)
print(f"✅ Created {len(created_group_uuids)} Data Groups for {len(series_by_study)} studies")

# --- Add all the Data Groups in the folder to a Dataset ---
group_items = folder.list_items(item_types=[StorageItemType.GROUP])
dataset = user_client.get_dataset(DATASET_ID)
dataset.link_items([item.uuid for item in group_items])

# --- Add the Dataset to a Project ---
project = user_client.get_project(PROJECT_ID)
project.add_datasets([DATASET_ID])

Data Groups are created in the same folder as the DICOM series. Running the script again creates duplicate Data Groups, so run it once per set of series.

Get Data Group Data Units

Use StorageItem.get_child_items() to list the data units in a Data Group. The first example starts from a Data Group’s file ID. The second example lists the data units of every Data Group in a Dataset. To see which tile each data unit is in, use the layout contents shown in Get Data Group Information.

from encord import EncordUserClient

SSH_PATH="/Users/chris-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key
DATA_GROUP_ID="00000000-0000-0000-0000-000000000000" # Replace with the file ID for the Data Group

# Initialize the SDK client
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

# Fetch the Data Group as a storage item
data_group_item = user_client.get_storage_item(DATA_GROUP_ID)

print(f"Data Group: {data_group_item.name} ({data_group_item.uuid})")

for item in data_group_item.get_child_items():
    print(f"- UUID: {item.uuid}, Name: {item.name}")

from encord import EncordUserClient
from encord.constants.enums import DataType

SSH_PATH="/Users/chris-encord/ssh-private-key.txt" # Replace with the file path to your SSH private key
DATASET_ID="00000000-0000-0000-0000-000000000000" # Replace with the ID for the Dataset

# Initialize the SDK client
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

dataset = user_client.get_dataset(DATASET_ID)

# Get every Data Group in the Dataset
for row in dataset.list_data_rows(data_types=[DataType.GROUP]):
    # Each data row points to the Data Group's storage item
    data_group_item = user_client.get_storage_item(row.backing_item_uuid)

    print(f"Data Group: {data_group_item.name} ({data_group_item.uuid})")
    for item in data_group_item.get_child_items():
        print(f"- UUID: {item.uuid}, Name: {item.name}")

Get Data Group Information

Use StorageItem.get_summary() to view a Data Group’s setup. The data_group field of the summary holds:

layout_contents: Each layout key and the data unit it points to.
layout: The layout tree. Grid and carousel Data Groups also return the layout Encord generated for them.
layout_settings: Tile settings (such as read-only tiles), fixed_layout, and has_multilayer_labels.
timeline: Keys of the audio and time series files shown in the timeline.

data_group is None when the storage item is not a Data Group.

Data Group Summary

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

# --- Configuration ---
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your access key
FOLDER_ID = "b95caa81-931a-4da9-b784-64037699f9fc"  # Replace with the Folder ID

# --- Connect to Encord ---
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

folder = user_client.get_storage_folder(FOLDER_ID)

# Get Data Group Info
first_group = list(folder.list_items(item_types=[StorageItemType.GROUP]))[0]
summary = first_group.get_summary()
assert summary.data_group is not None
print(summary.data_group.layout_contents)
print(summary.data_group.layout)
print(summary.data_group.layout_settings)

Change the Layout or Settings of a Data Group

You can’t change a Data Group’s files, layout or settings after you create it. This includes read-only tiles and multi-layer labels. To make a change, create a new Data Group with the same data units and the new layout or settings. The following script reads an existing Data Group and creates a copy with one more read-only tile. Change new_settings to make other changes, such as has_multilayer_labels=True.

The new Data Group is a separate storage item with its own label rows. Labels on the old Data Group are not copied. Add the new Data Group to your Dataset with link_items before you annotate it.

Recreate a Data Group with New Settings

from encord.orm.group_layout import LayoutSettings, TileSettings
from encord.orm.storage import DataGroupCustom
from encord.user_client import EncordUserClient

# --- Configuration ---
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your access key
DATA_GROUP_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the file ID of the existing Data Group
READ_ONLY_KEY = "camera_left"  # Replace with the layout key of the tile to make read-only

# --- Connect to Encord ---
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

old_item = user_client.get_storage_item(DATA_GROUP_ID)
old_group = old_item.get_summary().data_group
assert old_group is not None, "This storage item is not a Data Group"

# Start from the existing settings and change what you need
old_settings = old_group.layout_settings
tile_settings = dict(old_settings.tile_settings or {})
tile_settings[READ_ONLY_KEY] = TileSettings(is_read_only=True)

new_settings = LayoutSettings(
    fixed_layout=old_settings.fixed_layout,
    tile_settings=tile_settings,
    has_multilayer_labels=old_settings.has_multilayer_labels,
)

# Create the new Data Group in the same folder, with the same data units and layout
folder = user_client.get_storage_folder(old_item.parent_folder_uuid)
new_group_uuid = folder.create_data_group(
    DataGroupCustom(
        name=f"{old_item.name}-v2",
        layout_contents={key: child.uuid for key, child in old_group.layout_contents.items()},
        layout=old_group.layout,
        timeline=old_group.timeline,
        settings=new_settings,
        client_metadata=old_item.client_metadata,
    )
)

print(f"✅ Created Data Group {new_group_uuid} from {old_item.uuid}")

Multi-Layer Data Groups

Multi-Layer Data Groups let you label all images in a Data Group at once. Labels are stored on a single shared layer (the root Label Space) that covers every image in the group, so any label you add or edit (in the Label Editor or through the SDK) applies to all of them. On export, these shared labels appear under spaces["root"]["labels"], and the top-level labels object is empty.

Multi-Layer Data Groups support images only. Videos and other data types are not supported. All images in the group must have the same aspect ratio (width divided by height). Creating the group fails if it contains other data types or images with different aspect ratios.

To create a Multi-Layer Data Group with the SDK, create a custom Data Group and set has_multilayer_labels=True in its LayoutSettings. In the UI, turn on Multilayer labels when you create Auto Data Groups. You can’t turn on multi-layer labels for an existing Data Group. Create a new Data Group instead, as shown in Change the Layout or Settings of a Data Group.

Create a Multi-Layer Data Group

from uuid import UUID

from encord.orm.group_layout import DataUnitTile, LayoutGrid, LayoutSettings
from encord.orm.storage import DataGroupCustom
from encord.user_client import EncordUserClient

# --- Configuration ---
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your access key
FOLDER_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the Folder ID

# --- Connect to Encord ---
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

folder = user_client.get_storage_folder(FOLDER_ID)

# Two images of the same scene with the same aspect ratio, shown side by side
layout = LayoutGrid(
    direction="row",
    first=DataUnitTile(key="rgb"),
    second=DataUnitTile(key="infrared"),
    split_percentage=50,
)

group_uuid = folder.create_data_group(
    DataGroupCustom(
        name="multilayer-group-001",
        layout=layout,
        layout_contents={
            "rgb": UUID("00000000-0000-0000-0000-000000000000"),  # Replace with the File ID of an image
            "infrared": UUID("11111111-1111-1111-1111-111111111111"),  # Replace with the File ID of an image
        },
        settings=LayoutSettings(has_multilayer_labels=True),
    )
)

print(f"✅ Created Multi-Layer Data Group: {group_uuid}")

To add labels to a Multi-Layer Data Group, see Data Groups & Label Spaces.

Check if a Data Group is Multi-Layer

Read has_multilayer_labels from the Data Group’s layout settings. If you start from a label row, use label_row.get_storage_item() to get the Data Group’s storage item.

Check if a Data Group is Multi-Layer

from encord.user_client import EncordUserClient

# --- Configuration ---
SSH_PATH = "/Users/chris-encord/ssh-private-key.txt"  # Replace with the file path to your access key
DATA_GROUP_ID = "00000000-0000-0000-0000-000000000000"  # Replace with the file ID of the Data Group

# --- Connect to Encord ---
user_client: EncordUserClient = EncordUserClient.create_with_ssh_private_key(
    ssh_private_key_path=SSH_PATH,
    # For US platform users use "https://api.us.encord.com"
    domain="https://api.encord.com",
)

data_group_item = user_client.get_storage_item(DATA_GROUP_ID)
data_group = data_group_item.get_summary().data_group

if data_group is None:
    print(f"{data_group_item.name} is not a Data Group")
else:
    is_multilayer = bool(data_group.layout_settings.has_multilayer_labels)
    print(f"{data_group_item.name} is multi-layer: {is_multilayer}")

Read-Only Tiles

You can mark individual tiles in a Data Group as read-only. Annotators can view a read-only tile in the Label Editor but can’t add labels to it. This is useful for tiles that give context, such as an instructions document or a reference camera feed.

In the SDK, set TileSettings(is_read_only=True) for the tile when you create a custom Data Group.
The keys in tile_settings must be keys in layout_contents.
At least one tile must stay editable. Encord rejects a Data Group where every tile is read-only.
You can’t change which tiles are read-only after you create the Data Group. See Change the Layout or Settings of a Data Group.

SDK example

from encord.orm.group_layout import LayoutSettings, TileSettings

settings = LayoutSettings(
    tile_settings={
        "instructions": TileSettings(is_read_only=True)
    }
)

Manifest JSON example Auto Data Groups use a manifest JSON file to define groups. In a manifest, set is_read_only in settings.tile_settings, keyed by member name:

{
  "version": "1.0",
  "data_groups": [
    {
      "id": "group-1",
      "name": "Group 1",
      "layout_type": "default-grid",
      "members": {
        "camera_left": { "simple_pattern": "left/*.png" },
        "camera_right": { "simple_pattern": "right/*.png" }
      },
      "settings": {
        "tile_settings": {
          "camera_left": { "is_read_only": true }
        }
      }
    }
  ]
}

Get Started

General

Data

Ontologies

Projects

Labels

DICOM

Create Data Groups

Rules for Creating Data Groups

Data Group - Grid (Default)

Data Group - Carousel/List

Data Group - Custom

Data Groups for DICOM Studies

Get Data Group Data Units

Get Data Group Information

Change the Layout or Settings of a Data Group

Multi-Layer Data Groups

Check if a Data Group is Multi-Layer

Read-Only Tiles

​Create Data Groups

​Rules for Creating Data Groups

​Data Group - Grid (Default)

​Data Group - Carousel/List

​Data Group - Custom

​Data Groups for DICOM Studies

​Get Data Group Data Units

​Get Data Group Information

​Change the Layout or Settings of a Data Group

​Multi-Layer Data Groups

​Check if a Data Group is Multi-Layer

​Read-Only Tiles

Create Data Groups

Rules for Creating Data Groups

Data Group - Grid (Default)

Data Group - Carousel/List

Data Group - Custom

Data Groups for DICOM Studies

Get Data Group Data Units

Get Data Group Information

Change the Layout or Settings of a Data Group

Multi-Layer Data Groups

Check if a Data Group is Multi-Layer

Read-Only Tiles