> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encord.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Label set

Label sets capture the labels of a project branch into frozen versions.

A label set names a project branch as its source and, optionally, a selection of that branch's labels. Creating a version
captures every selected label at its current revision into a new version. A version never changes once it
is READY, so it can be exported again later or compared with another version.

Entry points are on [EncordUserClient](https://docs.encord.com/sdk-documentation/sdk-references/user_client.md#encorduserclient-objects): `create_label_set`, `get_label_set`
and `list_label_sets`.

## LabelSet Objects

```python theme={"dark"}
class LabelSet()
```

A label set: a project branch, which of its labels to capture, and the versions created from them.

Obtain one with [get\_label\_set()](https://docs.encord.com/sdk-documentation/sdk-references/user_client.md#get_label_set),
[list\_label\_sets()](https://docs.encord.com/sdk-documentation/sdk-references/user_client.md#list_label_sets) or
[create\_label\_set()](https://docs.encord.com/sdk-documentation/sdk-references/user_client.md#create_label_set).

#### id

```python theme={"dark"}
@property
def id() -> UUID
```

Get the unique identifier of the label set.

**Returns**:

* `UUID` - The label set ID.

#### name

```python theme={"dark"}
@property
def name() -> str
```

Get the name of the label set.

**Returns**:

* `str` - The name.

#### description

```python theme={"dark"}
@property
def description() -> str
```

Get the description of the label set.

**Returns**:

* `str` - The description, empty when none was given.

#### origin

```python theme={"dark"}
@property
def origin() -> LabelSetOrigin
```

Get where the set's labels come from.

**Returns**:

* `LabelSetOrigin` - `WORKFLOW` for labels made in the project, `IMPORT` for labels written to the branch
  from outside, such as model predictions.

#### sources

```python theme={"dark"}
@property
def sources() -> List[StoredSource]
```

Get the project branches that feed the set, each with its selection.

A listed source carries its ID, project and branch. To read its selection, call [refetch\_data()](https://docs.encord.com/sdk-documentation/sdk-references/label_set.md#refetch_data)
on the label set and read `sources` again.

**Returns**:

* `List[StoredSource]` - One [StoredProjectSource](https://docs.encord.com/sdk-documentation/sdk-references/orm.label_set.md#storedprojectsource-objects) today: the project, the branch a
  version captures, and its `label_selection` ([AllSelection](https://docs.encord.com/sdk-documentation/sdk-references/orm.label_set.md#allselection-objects) when a
  version captures every label on the branch). An [UnknownSource](https://docs.encord.com/sdk-documentation/sdk-references/orm.label_set.md#unknownsource-objects) is a kind
  of source this SDK version does not recognize.

**Example**:

```python theme={"dark"}
source = label_set.sources[0]
if isinstance(source, StoredProjectSource):
    print(source.project_id, source.branch_name, source.label_selection)
```

#### created\_by\_email

```python theme={"dark"}
@property
def created_by_email() -> str
```

Get the email of the user who created the set.

**Returns**:

* `str` - The creator's email.

#### created\_at

```python theme={"dark"}
@property
def created_at() -> datetime
```

Get when the set was created.

**Returns**:

* `datetime` - The creation time.

#### refetch\_data

```python theme={"dark"}
def refetch_data() -> None
```

Read the label set again from the platform, including each source's selection.

#### update

```python theme={"dark"}
def update(*,
           name: Optional[str] = None,
           description: Optional[str] = None) -> None
```

Change the name or the description. An argument left as `None` is unchanged.

**Arguments**:

* `name` - The new name.
* `description` - The new description. Pass `""` to clear it.

**Raises**:

* [`AuthorisationError`](https://docs.encord.com/sdk-documentation/sdk-references/exceptions#authorisationerror-objects) - You cannot manage the set.

#### set\_label\_selection

```python theme={"dark"}
def set_label_selection(source_id: Union[str, UUID],
                        selection: LabelSelection) -> None
```

Replace which labels a version captures from one source.

**Example**:

```python theme={"dark"}
complete = project.workflow.get_stage(name="Complete")
source = label_set.sources[0]
if isinstance(source, StoredProjectSource):
    label_set.set_label_selection(source.id, WorkflowStageSelection(workflow_stage_ids=[complete.uuid]))
    label_set.set_label_selection(source.id, AllSelection())  # back to every label on the branch
```

**Arguments**:

* `source_id` - The source under this label set. Available on listed sources too.
* `selection` - A [WorkflowStageSelection](https://docs.encord.com/sdk-documentation/sdk-references/orm.label_set.md#workflowstageselection-objects) (on the `main` branch only), or
  [AllSelection](https://docs.encord.com/sdk-documentation/sdk-references/orm.label_set.md#allselection-objects) so that the next version captures every label on the
  branch.

**Raises**:

* [`AuthorisationError`](https://docs.encord.com/sdk-documentation/sdk-references/exceptions#authorisationerror-objects) - You cannot manage the set.
* [`ResourceNotFoundError`](https://docs.encord.com/sdk-documentation/sdk-references/exceptions#resourcenotfounderror-objects) - The source does not belong to this label set.
* [`EncordException`](https://docs.encord.com/sdk-documentation/sdk-references/exceptions#encordexception-objects) - A stage selection was given for a branch other than `main`.
* `ValueError` - `source_id` is a badly formed UUID.

#### list\_versions

```python theme={"dark"}
def list_versions(*,
                  page_size: Optional[int] = None
                  ) -> Iterator[LabelSetVersion]
```

List the versions of the set, newest first.

**Arguments**:

* `page_size` - Number of versions per page. Default 100, maximum 100.

**Returns**:

* `Iterator[LabelSetVersion]` - The versions.

#### get\_version

```python theme={"dark"}
def get_version(version_id: Union[str, UUID]) -> LabelSetVersion
```

Get one version of the set.

**Arguments**:

* `version_id` - The version.

**Returns**:

* `LabelSetVersion` - The version.

**Raises**:

* `ValueError` - `version_id` is a badly formed UUID.
* [`ResourceNotFoundError`](https://docs.encord.com/sdk-documentation/sdk-references/exceptions#resourcenotfounderror-objects) - The version does not exist under this set, or you
  cannot read it.

#### create\_version\_job

```python theme={"dark"}
def create_version_job(name: Optional[str] = None) -> UUID
```

Queue a new version of the set's current selection, and return without waiting.

Read the job with [get\_version\_job()](https://docs.encord.com/sdk-documentation/sdk-references/label_set.md#get_version_job); once it is done, the version is available through
[get\_version()](https://docs.encord.com/sdk-documentation/sdk-references/label_set.md#get_version).

**Example**:

```python theme={"dark"}
job_id = label_set.create_version_job("v1")
job = label_set.get_version_job(job_id, timeout_seconds=600)
if isinstance(job, VersionJobDone):
    version = label_set.get_version(job.version_id)
```

**Arguments**:

* `name` - A label for the version, shown with its number. `None` means the number alone.

**Returns**:

* `UUID` - The job.

**Raises**:

* [`AuthorisationError`](https://docs.encord.com/sdk-documentation/sdk-references/exceptions#authorisationerror-objects) - You cannot manage the set.

#### get\_version\_job

```python theme={"dark"}
def get_version_job(job_id: Union[str, UUID],
                    *,
                    timeout_seconds: float = 0) -> VersionJob
```

Get the state of a version job, waiting up to `timeout_seconds` for it to finish.

**Arguments**:

* `job_id` - The job, as returned by [create\_version\_job()](https://docs.encord.com/sdk-documentation/sdk-references/label_set.md#create_version_job).
* `timeout_seconds` - How long to wait while the job is pending, polling with backoff. `0` reads the state
  once and returns it. The job is never cancelled; a pending result after the wait means it is still
  running and can be read again.

**Returns**:

* `VersionJob` - One of [LabelSetJobPending](https://docs.encord.com/sdk-documentation/sdk-references/orm.label_set.md#labelsetjobpending-objects),
  [VersionJobDone](https://docs.encord.com/sdk-documentation/sdk-references/orm.label_set.md#versionjobdone-objects) with the version it created,
  [VersionJobFailed](https://docs.encord.com/sdk-documentation/sdk-references/orm.label_set.md#versionjobfailed-objects) with the reason (no version was created), or
  [LabelSetJobUnknown](https://docs.encord.com/sdk-documentation/sdk-references/orm.label_set.md#labelsetjobunknown-objects) for a state this SDK version does not recognize.

**Raises**:

* `ValueError` - `job_id` is a badly formed UUID.
* [`ResourceNotFoundError`](https://docs.encord.com/sdk-documentation/sdk-references/exceptions#resourcenotfounderror-objects) - The job does not exist under this set, or you cannot
  read it.
* [`EncordException`](https://docs.encord.com/sdk-documentation/sdk-references/exceptions#encordexception-objects) - The platform returned a job state this SDK cannot read.

## LabelSetVersion Objects

```python theme={"dark"}
class LabelSetVersion()
```

A version of a label set: a frozen record of the labels captured when it was created.

Obtain one with [get\_version()](https://docs.encord.com/sdk-documentation/sdk-references/label_set.md#get_version) or [list\_versions()](https://docs.encord.com/sdk-documentation/sdk-references/label_set.md#list_versions). A new version is queued with
[create\_version\_job()](https://docs.encord.com/sdk-documentation/sdk-references/label_set.md#create_version_job).

#### id

```python theme={"dark"}
@property
def id() -> UUID
```

Get the unique identifier of the version.

**Returns**:

* `UUID` - The version ID.

#### label\_set\_id

```python theme={"dark"}
@property
def label_set_id() -> UUID
```

Get the label set the version belongs to.

**Returns**:

* `UUID` - The label set ID.

#### sources

```python theme={"dark"}
@property
def sources() -> List[StoredCapturedSource]
```

Get what the version captured.

**Returns**:

* `List[StoredCapturedSource]` - One [CapturedSource](https://docs.encord.com/sdk-documentation/sdk-references/orm.label_set.md#capturedsource-objects) today: the project branch
  the version captured, with the ontology and revision its labels were made against when it was created. An
  [UnknownSource](https://docs.encord.com/sdk-documentation/sdk-references/orm.label_set.md#unknownsource-objects) is a kind of source this SDK version does not recognize.

**Example**:

```python theme={"dark"}
source = version.sources[0]
if isinstance(source, CapturedSource):
    print(source.ontology_id, source.ontology_version_id)
```

#### version\_number

```python theme={"dark"}
@property
def version_number() -> int
```

Get the position of the version in its set, from 1.

**Returns**:

* `int` - The version number.

#### name

```python theme={"dark"}
@property
def name() -> str
```

Get the name of the version.

**Returns**:

* `str` - The name.

#### status

```python theme={"dark"}
@property
def status() -> LabelSetVersionStatus
```

Get the lifecycle of the version.

**Returns**:

* `LabelSetVersionStatus` - `BUILDING`, `READY` or `FAILED`.

#### created\_by\_email

```python theme={"dark"}
@property
def created_by_email() -> str
```

Get the email of the user who created the version.

**Returns**:

* `str` - The creator's email.

#### capture\_started\_at

```python theme={"dark"}
@property
def capture_started_at() -> datetime
```

Get when the capture started.

**Returns**:

* `datetime` - The start time.

#### capture\_finished\_at

```python theme={"dark"}
@property
def capture_finished_at() -> Optional[datetime]
```

Get when the capture finished.

**Returns**:

* `Optional[datetime]` - The finish time, or `None` while the version is building.

#### label\_count

```python theme={"dark"}
@property
def label_count() -> Optional[int]
```

Get how many labels the version holds.

**Returns**:

* `Optional[int]` - The count, or `None` until the version is READY.

#### refetch\_data

```python theme={"dark"}
def refetch_data() -> None
```

Read the version again from the platform.

#### get\_ontology

```python theme={"dark"}
def get_ontology() -> OntologyStructure
```

Get the ontology the version's labels were made against, as it was when the version was created.

Compare this rather than the ids on [sources](https://docs.encord.com/sdk-documentation/sdk-references/label_set.md#sources-2): editing a shared class changes the definition without
a new revision, so two versions can share a revision id and still differ.

**Returns**:

* `OntologyStructure` - The frozen ontology.

#### list\_members

```python theme={"dark"}
def list_members(*,
                 page_size: Optional[int] = None
                 ) -> Iterator[LabelSetVersionMember]
```

List the labels the version holds, each at the revision captured, in label ID order.

**Arguments**:

* `page_size` - Number of labels per page. Default 100, maximum 100.

**Returns**:

* `Iterator[LabelSetVersionMember]` - The labels, with the storage item each one was on.

#### create\_export\_job

```python theme={"dark"}
def create_export_job(format: ExportFormat = ExportFormat.JSON) -> UUID
```

Queue an export of the labels the version holds, and return without waiting.

Read the job with [get\_export\_job()](https://docs.encord.com/sdk-documentation/sdk-references/label_set.md#get_export_job); once it is done, it carries a link to the archive.

**Example**:

```python theme={"dark"}
job_id = version.create_export_job(ExportFormat.COCO)
job = version.get_export_job(job_id, timeout_seconds=600)
if isinstance(job, VersionExportJobDone):
    archive = requests.get(job.signed_url).content
```

**Arguments**:

* `format` - Format of the export.

**Returns**:

* `UUID` - The job.

**Raises**:

* [`AuthorisationError`](https://docs.encord.com/sdk-documentation/sdk-references/exceptions#authorisationerror-objects) - You cannot manage the captured project.

#### get\_export\_job

```python theme={"dark"}
def get_export_job(job_id: Union[str, UUID],
                   *,
                   timeout_seconds: float = 0) -> VersionExportJob
```

Get the state of an export job, waiting up to `timeout_seconds` for it to finish.

**Arguments**:

* `job_id` - The job, as returned by [create\_export\_job()](https://docs.encord.com/sdk-documentation/sdk-references/label_set.md#create_export_job).
* `timeout_seconds` - How long to wait while the job is pending, polling with backoff. `0` reads the state
  once and returns it. The job is never cancelled; a pending result after the wait means it is still
  running and can be read again.

**Returns**:

* `VersionExportJob` - One of [LabelSetJobPending](https://docs.encord.com/sdk-documentation/sdk-references/orm.label_set.md#labelsetjobpending-objects),
  [VersionExportJobDone](https://docs.encord.com/sdk-documentation/sdk-references/orm.label_set.md#versionexportjobdone-objects) with a link to the archive, valid for seven days
  and renewed on each read, [VersionExportJobFailed](https://docs.encord.com/sdk-documentation/sdk-references/orm.label_set.md#versionexportjobfailed-objects), or
  [LabelSetJobUnknown](https://docs.encord.com/sdk-documentation/sdk-references/orm.label_set.md#labelsetjobunknown-objects) for a state this SDK version does not recognize.

**Raises**:

* `ValueError` - `job_id` is a badly formed UUID.
* [`ResourceNotFoundError`](https://docs.encord.com/sdk-documentation/sdk-references/exceptions#resourcenotfounderror-objects) - The job does not exist under this version, or you
  cannot read it.
* [`EncordException`](https://docs.encord.com/sdk-documentation/sdk-references/exceptions#encordexception-objects) - The platform returned a job state this SDK cannot read.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.