Generations

Get a generation's transcript

Returns one generation's turn read back as an ordered sequence of steps: what it was asked, each model step with its tool calls and results, and how it ended.

The transcript is assembled at read time from the generation record and the trace's steps object; nothing is stored, so it cannot outlive the content it projects. Requires traces:GetTrace in addition to generations:GetGeneration, because the response merges content from both resources.

A generation whose content is unavailable — never written under zero-retention, or cleared by a purge — returns 200 with the skeleton rather than an error: input and output are null, steps is empty, and the content_redacted_* fields say which happened. content_redacted_by_principal_id is zero_retention when the content was never stored, and the purging principal's ID when it was erased later. A generation that is still running returns the same shape with an empty steps; status disambiguates the two.

get/v1/projects/{project_id}/generations/{generation_id}/transcript

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/generations/{generation_id}/transcript
  • 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)

Path parameters

generation_idstring required

Public ID of the generation

Response

The generation's transcript

generation_idstring
trace_idstring nullable
project_idstring
agent_idstring
agent_versioninteger nullable

Agent config version that served the turn.

status'running' | 'requires_action' | 'completed' | 'failed'

Lifecycle status of the generation. Disambiguates an empty steps caused by a run still in flight from one caused by erased content.

stop_reasonstring nullable

Why the generation stopped — the provider's finish reason, or one of the platform's own ('max_steps', 'depth_guard', 'chain_limit', 'error').

started_atstring date-time
completed_atstring date-time nullable
step_countinteger

Number of steps this turn recorded. A counter rather than content, so it survives a purge and still reports the size of a turn whose steps are gone. Scoped to the generation, not the trace: a trace that groups several generations counts them all in its own step_count, while each transcript reports only its own.

inputobject[] nullable

The messages the turn was asked, as recorded. Message content is caller-owned and passed through verbatim. Null when the content was never stored or has been purged.

content_redacted_atstring date-time nullable

When the generation's content was erased; null while it is intact.

content_redacted_by_principal_type'user' | 'api_key' | 'agent' | 'automation' | 'approval' | 'system'

What kind of principal acted. user and api_key are authenticated callers, and the id is the user's (user_…) or the key's own (key_…), so a record names which key acted rather than its owner. agent is an agent writing under its own identity (agent_…). automation is the task engine acting on a dispatch outcome and approval an approval resolution; neither carries an id. system is the platform itself, with an id naming the mechanism (retention_sweep, zero_retention).

content_redacted_by_principal_idstring nullable

Public id of that principal. zero_retention when the content was never stored, distinguishing it from content erased later.

Example response

{
  "generation_id": "gen_V1StGXR8Z5jdHi6B",
  "trace_id": "trace_V1StGXR8Z5jdHi6B",
  "status": "completed",
  "stop_reason": "stop",
  "step_count": 2,
  "steps": [
    {
      "finish_reason": "tool-calls",
      "tool_calls": [
        {
          "tool_name": "weather",
          "args": {
            "cityName": "Paris"
          }
        }
      ],
      "tool_results": [
        {
          "tool_name": "weather",
          "result": {
            "tempC": 18
          },
          "error": {
            "code": "AI_PROVIDER_ERROR",
            "message": "Provider returned 402: insufficient credits"
          }
        }
      ]
    }
  ],
  "output": {
    "content": "It's 18°C in Paris right now.",
    "finish_reason": "stop"
  },
  "error": {
    "code": "AI_PROVIDER_ERROR",
    "message": "Provider returned 402: insufficient credits"
  },
  "content_redacted_by_principal_type": "user"
}

Changes

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