# Generations Commands

> See [Generations module docs](../../modules/generations) for permissions and data model.

# Generations Commands

See [Generations module docs](../../modules/generations) for permissions and data model.

### `soat list-generations`

List generations

- Method: `GET`
- Path: `/api/v1/generations`

#### Usage

```bash
soat list-generations
```

#### Options

##### `--agent-id`

Filter by agent public ID

- Source: `query`
- Required: no
- Type: `string`

##### `--trace-id`

Filter by trace public ID

- Source: `query`
- Required: no
- Type: `string`

##### `--initiator-generation-id`

Filter by the public ID of the parent generation. Returns all generations triggered by that generation — sub-agent invocations. Null-initiated (top-level) generations are not returned. 

- Source: `query`
- Required: no
- Type: `string`

##### `--chain-id`

Filter by the continuation chain the generation belongs to. This is how a chain is expanded into its members — the chain record carries only their count. 

- Source: `query`
- Required: no
- Type: `string`

##### `--orchestration-run-id`

Filter by the orchestration run that dispatched the generation. This is how a run is traced back to what its agent nodes did — a node execution record stores no generation id. 

- Source: `query`
- Required: no
- Type: `string`

##### `--node-id`

Filter by the orchestration node that dispatched the generation. Combine with `orchestration_run_id` to narrow to one node of one run; a retried node returns one generation per `node_attempt`. 

- Source: `query`
- Required: no
- Type: `string`

##### `--status`

Filter by lifecycle status

- Source: `query`
- Required: no
- Type: `enum("in_progress", "requires_action", "completed", "failed")`

##### `--limit`

—

- Source: `query`
- Required: no
- Type: `integer`
- Default: `50`

##### `--offset`

—

- Source: `query`
- Required: no
- Type: `integer`
- Default: `0`

### `soat get-generation`

Get a generation

- Method: `GET`
- Path: `/api/v1/generations/{generation_id}`

#### Usage

```bash
soat get-generation --generation-id <string>
```

#### Options

##### `--generation-id`

Public ID of the generation

- Source: `path`
- Required: yes
- Type: `string`

### `soat update-generation`

Update generation metadata

- Method: `PATCH`
- Path: `/api/v1/generations/{generation_id}`

#### Usage

```bash
soat update-generation --generation-id <string> --metadata <object<string, unknown>>
```

#### Options

##### `--generation-id`

Public ID of the generation

- Source: `path`
- Required: yes
- Type: `string`

##### `--metadata`

Caller-supplied key/value metadata to shallow-merge into the generation record's caller-owned `metadata` bag. No key is reserved: server-owned state lives in its own top-level fields and cannot be written from here. 

- Source: `body`
- Required: yes
- Type: `object<string, unknown>`
- Example: `\{"team":"payments","ticket_id":"OPS-4821"\}`

### `soat purge-generation-content`

Purge generation content

- Method: `DELETE`
- Path: `/api/v1/generations/{generation_id}/content`

#### Usage

```bash
soat purge-generation-content --generation-id <string>
```

#### Options

##### `--generation-id`

Public ID of the generation

- Source: `path`
- Required: yes
- Type: `string`

### `soat get-generation-transcript`

Get a generation's transcript

- Method: `GET`
- Path: `/api/v1/generations/{generation_id}/transcript`

#### Usage

```bash
soat get-generation-transcript --generation-id <string>
```

#### Options

##### `--generation-id`

Public ID of the generation

- Source: `path`
- Required: yes
- Type: `string`