Authorized turn read API

01Reference and return value

Preview capability · SDK 0.1.0-alpha.9

Call through getAutomation(context).conversations or context.conversations. Requires project-scoped conversations.read.

interface TurnReference { conversationId: string; turnId: string; version: number }
interface TurnSnapshot extends TurnReference {
  projectId: string; status: string;
  messages: { id: string; role: string; text: string }[];
}
conversations.getTurn(reference: TurnReference): Promise<TurnSnapshot>;

02Version and authorization

Use the original reference from the completion event. Initial version 1 is an immutable terminal snapshot. Never fall back to the latest content after a read failure. Handle errors for project moves, deleted conversations, missing versions and revoked grants.

03Data scope

Returns message id, role and text, not attachment binaries, tool arguments, model keys or a separate project-path field. Paths already present in text remain text. No historical turn listing, live streaming or arbitrary version editing is exposed. Snapshots are retained for seven days, not as permanent history. getTurn enforces a 256 KiB snapshot JSON limit at read time; background jobs separately limit aggregate frozen text to 48,000 bytes.