# Lineages


A **lineage** is a sandbox together with everything that descends from it: its [forks](/zbox/lifecycle#fork-a-sandbox), the forks of those forks, and the sandboxes [restored from its snapshots](/zbox/lifecycle#snapshots-and-restore). It lets you find every sandbox that shares a common starting point.

## How lineages are formed

A sandbox created from a [base or a template](/zbox/images), with `zbox new` or `POST /api/rest/sandbox`, starts a new lineage and has no parent. Two sandboxes from the same template belong to two different lineages.

A fork child and a restored sandbox join the lineage of the sandbox they came from, and record that sandbox as their **parent**.

An [imported](/zbox/export) sandbox has no parent and starts a lineage of its own. The exception is an archive uploaded from a file: the upload gets a lineage, and every import of that upload joins it.

Each sandbox carries both:

| Field | Meaning |
|---|---|
| `lineageId` | The lineage the sandbox belongs to. Set at create and never changes. |
| `parentId` | The sandbox it was forked or restored from. Empty for a sandbox created from a base or a template, and for an imported one. |

`zbox get` shows them as **Lineage** and **Parent**.

A lineage has no name and no status of its own, only an ID and the time it was created. It stays in the workspace while the workspace keeps the record of any of its sandboxes, or an export file of it. After that, [retention](/zbox/lifecycle#retention) deletes the lineage with its export records. Objects in a bucket stay.

## List and inspect lineages

```bash
# all lineages in the workspace, newest first
zbox lineage list
# a page of 50, then the next one
zbox lineage list --limit 50
zbox lineage list --limit 50 --before <last-lineage-id>
# one lineage by its ID
zbox lineage get <lineage-id>
```

`GET /api/rest/lineage-list` pages with `limit` (at most 1000) and `beforeId` like the [sandbox list](/zbox/access#paging-lists), and answers every lineage when you pass no `limit`.

To see the sandboxes of a lineage, filter the sandbox list. Like any `zbox list`, it shows only live sandboxes unless you ask for other [statuses](/zbox/lifecycle#sandbox-statuses):

```bash
# sandboxes of one lineage
zbox list --lineage <lineage-id>
# only the removed ones, until retention deletes them
zbox list --lineage <lineage-id> --status terminated,archived
# direct children of one sandbox (forks and restores), by ID or name
zbox list --parent app
```

`--parent` lists only direct children. To find everything descended from a sandbox, list its lineage.

## Export and import

To move a sandbox out of the workspace or into another one, see [export and import](/zbox/export).