Generations

List generations

Returns generations the caller can access, optionally filtered by agent, trace, orchestration run, node, and status. The generations of one trace are the trace_id filter.

Filtering by orchestration_run_id is the supported way to get from an orchestration run to the generations its agent nodes produced: a node execution record carries no generation id, so the pointer lives here, alongside the run's other attribution columns.

get/v1/projects/{project_id}/generations

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/generations
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Query parameters

agent_idstring

Filter by agent public ID

trace_idstring

Filter by trace public ID

session_idstring

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.

actor_idstring

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.

initiator_generation_idstring

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.

chain_idstring

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.

orchestration_run_idstring

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.

node_idstring

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.

statusstring[]

Filter by lifecycle status. Repeat the parameter to OR values. A value outside the enum, empty string included, is a 400.

limitinteger

Results per page, 1 to 100 (default 50). Above 100 it is clamped; below 1 or not an integer it is 400.

offsetinteger

Results to skip. Negative or not an integer it is 400.

Response

Paginated list of generations

totalinteger
limitinteger
offsetinteger

Example response

{
  "data": [
    {
      "id": "gen_V1StGXR8Z5jdHi6B",
      "started_by_principal_type": "user",
      "started_by_principal_id": "user_V1StGXR8Z5jdHi6B",
      "status": "failed",
      "stop_reason": "error",
      "error": {
        "code": "AI_PROVIDER_ERROR",
        "message": "Provider returned 402: insufficient credits"
      },
      "tool_surface": {
        "tools": 61,
        "bytes": 152161,
        "estimated_tokens": 45148
      },
      "retrieval": [
        {
          "source_type": "document",
          "document_id": "doc_V1StGXR8Z5jdHi6B",
          "document_version": 3,
          "chunk_id": "dchunk_V1StGXR8Z5jdHi6B",
          "page": 2,
          "similarity_score": 0.82
        }
      ],
      "idempotency_key": "discord-1287654321098765432",
      "metadata": {
        "author": "John",
        "revision": 2
      },
      "content_redacted_by_principal_type": "user",
      "content_redacted_by_principal_id": "user_V1StGXR8Z5jdHi6B"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.