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
--session-id​

Return only the generations dispatched through one session — the turns behind that conversation's spend. A session that does not exist in scope yields an empty page.

  • Source: query
  • Required: no
  • Type: string
--actor-id​

Return only the generations one end user started, across every session they appear in. An actor that does not exist in scope yields an empty page.

  • Source: query
  • Required: no
  • Type: string
--initiator-generation-id​

Filter by the public ID of the parent generation. Returns every generation started by that generation: sub-agent invocations, approval continuations, client-tool re-handoffs and memory-rule handler turns. 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. Repeat the parameter to OR values. A value outside the enum, empty string included, is a 400.

  • Source: query
  • Required: no
  • Type: array<enum("running", "requires_action", "completed", "failed")>

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 <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: 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 list-generation-memory-assertions​

List the memory writes a generation made

  • Method: GET
  • Path: /api/v1/generations/{generation_id}/memory-assertions

Usage​

soat list-generation-memory-assertions --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