Skip to main content

Generations Commands

See Generations module docs for permissions and data model.

soat list-generations​

List generations

  • Method: GET
  • Path: /api/v1/generations

Usage​

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​

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​

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​

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​

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

Options​

--generation-id​

Public ID of the generation

  • Source: path
  • Required: yes
  • Type: string