---
title: "Get a machine's lineage."
method: GET
path: "/v1/machines/{id}/lineage"
tags: ["machines"]
---

# Get a machine's lineage.

`GET /v1/machines/{id}/lineage`

## Request

- Base URL: `https://api.smolmachines.com`
- URL: `https://api.smolmachines.com/v1/machines/{id}/lineage`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/smolmachines/apis/smolfleet-api/docs/v1/machines/:id/lineage/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns the machines and checkpoints this machine was branched or restored from. Requires the `machine:read` scope.

## Path parameters

- `id` string, required

## Response `200`

Complete branch lineage

- MachineLineage: One complete live branch lineage, suitable for rendering as a tree. Parent relationships remain on each machine so clients do not have to infer them from names or creation order.
  - `machines` MachineInfo[], required
    - `arch` string, nullable: The machine's actual CPU arch (`arm64`/`amd64`): the arch of the node it runs on, falling back to `source.arch` (a `.smolmachine`'s pinned arch) when the machine is unplaced or its node is gone. `None` only when neither is known. Lets the console show an arch badge for every machine, including ones whose source pinned no arch. Populated by the server's `machine_info`.
    - `autoStopSeconds` integer, nullable
    - `branchGeneration` integer, nullable: Zero for a root branch source, one for its children, and so on.
    - `branchState` 'mutable' | 'freezing' | 'frozen': User-visible state of a live-RAM checkpoint.
    - `branchable` boolean: Whether this machine can produce live copy-on-write branches.
    - `cacheDisk` MachineCacheDisk: The cache disk a machine runs with.
      - `cacheDiskId` string, required
      - `intoSlot` boolean: Put in a cache slot by a restore, which needs an engine that serves slots.
      - `mountPath` string, required
      - `slot` boolean: Attached unmounted, as a slot a restore can put another cache in.
      - `version` integer, required
    - `capabilities` MachineCapabilities: Dynamic machine operations for clients that must feature-detect instead of guessing from a server or engine version.
      - `branch` boolean, required
      - `branchBatch` boolean, required
      - `exec` boolean, required
      - `fork` boolean, required
      - `forkBatch` boolean, required
      - `maxBranchBatch` integer, required
      - `maxForkBatch` integer, required: Legacy alias for `max_branch_batch`.
      - `nestedBranch` boolean, required
      - `nestedFork` boolean, required
    - `checkpointState` 'mutable' | 'freezing' | 'frozen': User-visible state of a live-RAM checkpoint.
    - `createdAt` string, required
    - `createdBy` string, nullable: The account id of whoever created the machine; null when nobody is.
    - `env` object, required
    - `ephemeral` boolean, required
    - `error` string, nullable: When [`Self::state`] is `"error"`, a human-readable reason the machine failed — the latest control-plane error event (e.g. `"start failed: …"`, `"auto-start failed: …"`, or `"machine stuck in creating state"`). `null` for machines that are not in an error state. Gives clients something actionable instead of a bare `error` with no explanation.
    - `forkGeneration` integer, nullable: Legacy alias for `branch_generation`.
    - `forkable` boolean: Legacy alias for `branchable`.
    - `id` string, required
    - `labels` object: Labels set at create time (or inherited from a branch source).
    - `lastActivityAt` string, nullable
    - `name` string, nullable
    - `network` union, required
      - object: No outbound access for the guest. The image PULL runs in-guest too, so a `blocked` machine whose image isn't already node-cached CANNOT fetch it and its start fails on an unreachable registry — opt into this deliberately.
        - `mode` 'blocked', required
      - object: Unrestricted outbound access. This is the DEFAULT: it matches what the `smol` CLI already sends, and means a create that omits `network` (raw API/SDK) can pull remote images out of the box instead of failing the start on an unreachable registry. Tighten with `blocked`/`allowCidrs`.
        - `mode` 'open', required
      - object
        - `cidrs` string[]
        - `hosts` string[]
        - `mode` 'allowCidrs', required
    - `parentMachineId` string, nullable: Immediate live-RAM checkpoint this machine was branched from. `null` for ordinary machines and root checkpoints.
    - `ports` MachinePort[]: Published ports with their allocated node host ports.
      - `hostPort` integer, nullable: Node host port allocated at placement (read-only; ignored on create).
      - `port` integer, required: Guest port the workload listens on.
    - `ready` boolean: Whether the machine is READY to do work. `state == "started"` only means the VM process launched on the node — the guest OS and your in-VM workload still need a moment to boot. `ready` becomes true once the guest agent is reachable (an `exec`/`connect` will succeed) and, if the machine publishes a port, that port is accepting connections. Wait for `ready` (poll `GET /v1/machines/:id`) before expecting an in-guest worker to have started or before connecting to it — do NOT act on `started` alone.
    - `readyAt` string, nullable: When a probe first observed this machine serving (RFC3339), or `null`. This is a readiness gate, not a boot timestamp: it is stamped when the published port accepts a connection (or, for a machine with no published ports, when its guest agent answers), and it is cleared on every stop so a restart must re-prove itself. A short-lived machine may finish its whole life as `null` here without anything being wrong. Use `createdAt` if you want when the machine came into existence.
    - `resources` MachineResources, required
      - `cpus` integer
      - `diskDurability` 'full' | 'deferred': When a machine's guest disk writes must reach the node's physical disk.
      - `diskGb` integer, nullable
      - `memoryMb` integer
    - `rootBranchId` string, nullable: Root source for this live branch lineage. A root points to itself; ordinary machines have no lineage.
    - `rootCheckpointId` string, nullable: Legacy alias for `root_branch_id`.
    - `source` union, required
      - object
        - `arch` string, nullable: Requested CPU arch ("arm64"/"amd64"). Optional: an OCI image is usually multi-arch (the node pulls its own variant), so `None` means "no constraint" — but a caller that NEEDS a specific arch (e.g. x86-only binaries inside) can pin placement with it. Was previously silently dropped by deserialization.
        - `reference` string, required
        - `type` 'image', required
      - object
        - `arch` string, nullable: Canonical CPU arch the packed artifact targets ("arm64"/"amd64"). A `.smolmachine` is single-arch, so this becomes a hard placement constraint. `None` (older clients) means "no arch constraint".
        - `reference` string, required
        - `type` 'smolmachine', required
    - `state` string, required
    - `ttlSeconds` integer, nullable
    - `updatedAt` string, required
    - `url` string, nullable: Public ingress URL for the machine's first published port, when the machine is started and the control plane has a public base URL configured. `null` for stopped machines, machines with no published port, or when the deployment exposes no public base URL.
    - `workdir` string, nullable
  - `rootMachineId` string, required

## Other responses

- `401`: Missing or invalid API key
- `403`: Key lacks the required scope
- `404`: Not found
- `429`: Rate limited; retry after the Retry-After header
- `500`: Internal error

## Changes

- **2026-10-16** `bc31fc04a568`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/smolmachines/apis/smolfleet-api/changes/v1/machines/:id/lineage/get.md)

---

[API](https://skmtc.dev/smolmachines/apis/smolfleet-api.md) - [All operations](https://skmtc.dev/smolmachines/apis/smolfleet-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smolmachines/apis/smolfleet-api/revisions/bc31fc04a568?raw)