Label branches let you keep multiple versions of a Project’s labels side-by-side. Use them to preserve a labeled state before a re-labeling pass, run an experiment without disturbing main, or hold a reviewer-only copy of labels.
You create a new label version by copying labels from an existing branch onto a new branch with project.copy_labels_to_branch(). Every Project starts with a main branch. Copying from main (or any branch) into a new branch name creates that branch and populates it with the matching label rows.
Label branches are the recommended method for Pre-labeling Agents and Exporting Labels Agents.
-
A Pre-labeling Agent writes its model predictions onto a dedicated branch (for example,
pre-labels-v1) instead of main. Annotators continue working on main undisturbed, and you can review or merge the agent’s output on its own branch with copy_labels_to_branch(..., overwrite=True) once it’s been validated.
-
An Exporting Labels Agent copies the current state of
main onto a frozen snapshot branch (for example, export-2026-05-12) before export. The export reads from that branch via list_label_rows_v2(branch_name=...), so the result is reproducible even if annotation continues on main in parallel.
source_branch and target_branch MUST be different. Passing the same name for both raises a ValueError.
By default, data units that already have a label row on target_branch are skipped. Set overwrite=True to replace existing label rows on the target branch with the source content.
All examples on this page use bundle when calling initialise_labels() or save() to reduce network round-trips. Keep bundle sizes under 1000 operations — larger bundles can degrade performance. A good starting point is BUNDLE_SIZE = 100; for videos with many labels, start at 20 and adjust. copy_labels_to_branch() does not need a bundle — it batches internally via its own batch_size parameter (default 50). The examples below are intended as quick tests and cap themselves at the first MAX_LABEL_ROWS = 10 label rows so you can validate the workflow safely. Remove that cap deliberately before running against a full Project — copying or overwriting labels on tens of thousands of rows without filtering can take a long time and is hard to undo.
Copy All Labels to a New Branch
The following example creates a new label version named pre-label-v1 by copying every label row on main into the new branch. This is the most common pattern: snapshot the current label state before making changes.
Copy all labels to a new branch
Copy Labels for Specific Data Units
To version labels for only a subset of your Project, pass the data_hashes (or label_hashes) you want to include. Everything outside that list stays untouched on the target branch.
When you need to discover the label_hashes first, fetch them with list_label_rows_v2() from the source branch. You only need to initialise label rows (with a bundle) when you intend to read their contents — for the hash-discovery step alone, the metadata returned by list_label_rows_v2() is enough.
When both data_hashes and label_hashes are specified, data_hashes is applied first and label_hashes is applied to the result.
Switch to a Branch and Read Labels
Once a branch exists, use list_label_rows_v2() with branch_name to fetch the label rows on that branch. Initialise each label row inside a create_bundle() context so all the download calls are batched into a single round-trip.
Read labels from a branch
branch_name cannot be combined with include_all_label_branches=True. Pick one: either query a single branch by name, or pull every branch as separate label row objects.
Sync or Merge Branches
There is no dedicated “merge” call. To push updates from one branch back into another, call copy_labels_to_branch() again with overwrite=True. This replaces label rows on the target branch with the latest content from the source branch.
overwrite=True is destructive. Label rows on the target branch are replaced with the source content for every matched data unit. There is no automatic conflict resolution — the source wins. Filter with data_hashes or label_hashes if you want to limit the sync.
