Data Groups - Encord

“Data Grouping” (Data Groups) allows you to allocate individual files to groups so that they are more easily annotated and reviewed. This allows you to unlock multi-tile and multi-modal functionality. Basically, Data Groups are like image groups in Encord, except that Data Groups can include any data type (images, videos, audio files, text files, PDFs) AND that data groups support default and custom layouts for annotation and review.

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.

Create Data Groups

Each of the code examples does the following:

Specifies the data units to add to a Data Group.
Creates the Data Groups and specifies the layout in the Label Editor.

Each example create multiple Data Groups. To create a single data group, replace create_data_groups with create_data_group.

Adds the Data Groups to a Dataset.
Adds the Dataset to a Project.

Data Group - Grid (Default)

Grid Data Groups allow you to arrange multiple data units in a fixed, ordered grid within the Label Editor. The order of the data units in the group determines their visual arrangement in the grid.

All layouts (grid, carousel, custom) are limited to 50 data units. Attempting to create a data group with more than 50 data units results in an error.

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 call to DataGroupGrid(…) when creating the Data Group:

Example

Data Group - Grid

from uuid import UUID
from typing import List

from encord.constants.enums import DataType
from encord.objects.metadata import DataGroupMetadata
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])

# --- Retrieve and inspect Data Group label rows ---
p = user_client.get_project(PROJECT_ID)
rows = p.list_label_rows_v2(include_children=True)

for row in rows:
    if row.data_type == DataType.GROUP:
        row.initialise_labels()
        assert isinstance(row.metadata, DataGroupMetadata)
        print(row.metadata.children)

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 grid layout, you need:

A list of data unit UUIDs in the exact order they should appear in the grid.
A call to DataGroupCarousel(...) when creating the data group:

Example

Data Group - Carousel

from uuid import UUID
from typing import List

from encord.constants.enums import DataType
from encord.objects.metadata import DataGroupMetadata
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])

# --- Retrieve and inspect Data Group label rows ---
p = user_client.get_project(PROJECT_ID)
rows = p.list_label_rows_v2(include_children=True)

for row in rows:
    if row.data_type == DataType.GROUP:
        row.initialise_labels()
        assert isinstance(row.metadata, DataGroupMetadata)
        print(row.metadata.children)

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. Settings reference the same keys used in the layout.

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,
)
)

group = folder.create_data_group(
    {
        "name": "my group",
        "layout_contents": layout_contents,
        "layout": layout,
        "settings": settings,
    }
)

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
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)
rows = p.list_label_rows_v2(include_children=True)

from uuid import UUID

from encord.constants.enums import DataType
from encord.objects.metadata import DataGroupMetadata
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)
rows = p.list_label_rows_v2(include_children=True)

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.objects.metadata import DataGroupMetadata
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)
rows = p.list_label_rows_v2(include_children=True)

# Label Rows of Data Groups use DataGroupMetadata for the layout to Annotate and Review
for row in rows:
    if row.data_type == DataType.GROUP:
        row.initialise_labels()
        assert isinstance(row.metadata, DataGroupMetadata)
        print(row.metadata.children)

from uuid import UUID

from encord.constants.enums import DataType
from encord.objects.metadata import DataGroupMetadata
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)
rows = p.list_label_rows_v2(include_children=True)

# Label Rows of Data Groups use DataGroupMetadata for the layout to Annotate and Review
for row in rows:
    if row.data_type == DataType.GROUP:
        row.initialise_labels()
        assert isinstance(row.metadata, DataGroupMetadata)
        print(row.metadata.children)

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 = "/path/to/your/encord_private_key.txt"
FOLDER_ID = "00000000-0000-0000-0000-000000000000"
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}")

Get Data Group Data Units

Use the following to get the data units that comprise a Data Group.

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 uuid import UUID

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
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",
)

# Data Group
data_group_item = user_client.get_storage_item(DATA_GROUP_ID)
children = list(data_group_item.get_child_items())

# Dataset rows
dataset = user_client.get_dataset(DATASET_ID)
rows = list(dataset.list_data_rows())
rows_by_backing = {}
for r in rows:
    try:
        # Normalize to UUID for robust matching
        if r.backing_item_uuid is not None:
            rows_by_backing[UUID(str(r.backing_item_uuid))] = r
    except Exception:
        pass  # ignore malformed ids

# Print header + ALL children in the group
print(f"Data Group: {data_group_item.name} ({data_group_item.uuid})")
for it in children:
    _row = rows_by_backing.get(UUID(str(it.uuid)))
    print(f"- UUID: {it.uuid}, Name: {it.name}")
    

Get Data Group Information

Use the following script to view:

Group layout contents
Group layout
Group layout settings

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)

Multi-Layer Data Groups

Multi-Layer Data Groups allow you to apply labels across all data units in a group simultaneously. Any label added or edited in the Label Editor is automatically applied to every data unit in the group. These shared labels are exported under the root key, which contains all label information that applies to the Data Group as a whole. To create a Multi-Layer Data Group, set has_multilayer_labels=True in the group settings when creating a custom Data Group:

from encord.orm.group_layout import LayoutSettings, TileSettings

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

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 cannot add labels to it. This is useful for tiles that provide reference context — such as an instructions document or a reference camera feed — that annotators should see but not annotate. The is_read_only flag lives in settings.tile_settings in the manifest JSON, keyed by tile name. When you serialize a Data Group, Encord projects the per-tile read-only flag into settings.tile_settings automatically. Manifest JSON example

{
  "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 }
        }
      }
    }
  ]
}

SDK example

from encord.orm.group_layout import LayoutSettings, TileSettings

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

The read-only flag round-trips correctly through manifest import and export. Renaming a tile preserves its read-only flag. Deleting a read-only tile removes the flag cleanly from the manifest.

​Create Data Groups

​Data Group - Grid (Default)

​Data Group - Carousel/List

​Data Group - Custom

​Get Data Group Data Units

​Get Data Group Information

​Multi-Layer Data Groups

​Read-Only Tiles

Create Data Groups

Data Group - Grid (Default)

Data Group - Carousel/List

Data Group - Custom

Get Data Group Data Units

Get Data Group Information

Multi-Layer Data Groups

Read-Only Tiles