Canvas introspection

Every run writes its output into a canvas — a directed graph of blocks (documents, spreadsheets, research notes, images, etc.) linked by dependency edges. The SDK exposes three read-only introspection methods so you can audit exactly what a run produced.

The block graph

const dag = await client.canvases.getDag(canvasId);

for (const node of dag.nodes) {
  console.log(`${node.type.padEnd(24)} ${node.status.padEnd(10)} ${node.name}`);
}

for (const edge of dag.edges) {
  console.log(`${edge.source_id} -> ${edge.target_id}`);
}

Each Block exposes:

Field	Description
`id`	UUID of the block.
`name`	Human-readable block name.
`type`	Block type (e.g. `document-block`, `excel-block`).
`status`	Current state (`idle`, `running`, `completed`, `error`, …).
`content`	Textual content, when applicable.
`url`	External or pre-signed download URL, when applicable.
`sources`	Source attributions (block-type specific).

The task tree

The task tree describes the agent execution that produced the canvas — parent tasks, persona tasks, individual tool calls. It is split into completed and in-progress subtrees:

const tree = await client.canvases.getTasks(canvasId);

function printTree(tasks: Task[], indent = 0): void {
  for (const t of tasks) {
    console.log('  '.repeat(indent) + `- ${t.name} (${t.task_type}, ${t.status})`);
    if (t.children) printTree(t.children, indent + 1);
  }
}

console.log('Completed:');
printTree(tree.completed);
console.log('In progress:');
printTree(tree.not_completed);

A single task

If you already have a task id (from a progress webhook or a previous tree), fetch just that one with its immediate children:

const task = await client.canvases.getTask(canvasId, taskId);
console.log(task.status, task.name);

Timing

A canvas is created during runs.create, but its canvas_id may not be populated on the very first poll — the server persists it a moment after the run starts. Read it from the run object once status moves past running, or after a short wait:

const run = await client.runs.retrieve(runId);
if (run.status !== 'running' && run.canvas_id) {
  const canvas = await client.canvases.getDag(run.canvas_id);
}

Get Started

Concepts

Use with agents

Endpoints

Resources

Python SDK

TypeScript SDK

Runs

Canvas

The block graph

The task tree

A single task

Timing

​The block graph

​The task tree

​A single task

​Timing

The block graph

The task tree

A single task

Timing