# Data Structure

When you connect blocks, understanding the data structure of different block outputs is important because the output data structure from the source block determines what values are available in the destination block. Each block type produces a specific output structure that you can reference in downstream blocks.

Understanding these data structures is essential for effectively using connection tags and
accessing the right data in your workflows.

## Block Output Structures

Different block types produce different output structures. Here's what you can expect from each block type:

**Agent Output**

```json
{
  "content": "The generated text response",
  "model": "gpt-4o",
  "tokens": {
    "input": 120,
    "output": 85,
    "total": 205
  },
  "toolCalls": {
    "list": [],
    "count": 0
  },
  "providerTiming": {
    "duration": 1250,
    "modelTime": 1250,
    "toolsTime": 0,
    "iterations": 1
  },
  "cost": {
    "input": 0.0006,
    "output": 0.001275,
    "total": 0.001875
  }
}
```

### Agent Block Output Fields

* **content**: The main text response generated by the agent
* **model**: The AI model used (e.g., "gpt-4o", "claude-3-opus")
* **requestedModel**: Present only when the selected model was retired and the response came from its replacement; holds the selected model, while **model** holds the one that ran
* **tokens**: Token usage statistics
  * **input**: Number of input tokens consumed
  * **output**: Number of output tokens generated
  * **total**: Total tokens used
* **toolCalls**: Object containing the ordered tool-call **list** and its **count**
* **providerTiming**: Provider, model, and tool execution timing details
* **cost**: Estimated input, output, tool, and total provider costs

**API Output**

```json
{
  "data": "Response data",
  "status": 200,
  "headers": {
    "content-type": "application/json",
    "cache-control": "no-cache"
  }
}
```

### API Block Output Fields

* **data**: The response data from the API (can be any type)
* **status**: HTTP status code of the response
* **headers**: HTTP headers returned by the API

**Function Output**

```json
{
  "result": "Function return value",
  "stdout": "Console output",
}
```

### Function Block Output Fields

* **result**: The return value of the function (can be any type)
* **stdout**: Console output captured during function execution

**Evaluator Output**

```json
{
  "content": {
    "metric1": 8.5,
    "metric2": 7.2,
    "metric3": 9.0
  },
  "model": "gpt-5",
  "tokens": {
    "input": 120,
    "output": 85,
    "total": 205
  },
  "cost": {
    "input": 0.0006,
    "output": 0.001275,
    "total": 0.001875
  },
  "metric1": 8.5,
  "metric2": 7.2,
  "metric3": 9.0
}
```

### Evaluator Block Output Fields

* **content**: Object of every metric score, keyed by metric name
* **model**: The AI model used for evaluation
* **tokens**: Token usage statistics (**input**, **output**, **total**)
* **cost**: Estimated input, output, and total provider costs
* **\[metricName]**: Score for each metric defined in the evaluator (dynamic fields)

**Condition Output**

```json
{
  "conditionResult": true,
  "selectedPath": {
    "blockId": "2acd9007-27e8-4510-a487-73d3b825e7c1",
    "blockType": "agent",
    "blockTitle": "Follow-up Agent"
  },
  "selectedOption": "condition-1"
}
```

### Condition Block Output Fields

* **conditionResult**: Boolean result of the condition evaluation
* **selectedPath**: Information about the selected path
  * **blockId**: ID of the next block in the selected path
  * **blockType**: Type of the next block
  * **blockTitle**: Title of the next block
* **selectedOption**: ID of the selected condition

**Router Output**

```json
{
  "context": "The text the router was asked to route",
  "model": "gpt-4o",
  "tokens": {
    "input": 120,
    "output": 85,
    "total": 205
  },
  "cost": {
    "input": 0.0006,
    "output": 0.001275,
    "total": 0.001875
  },
  "selectedRoute": "route-1",
  "selectedPath": {
    "blockId": "2acd9007-27e8-4510-a487-73d3b825e7c1",
    "blockType": "agent",
    "blockTitle": "Customer Service Agent"
  }
}
```

### Router Block Output Fields

* **context**: The input text the router evaluated (Router blocks created before routes were introduced emit it as **prompt**)
* **model**: The AI model used for routing
* **tokens**: Token usage statistics (**input**, **output**, **total**)
* **cost**: Estimated input, output, and total provider costs
* **selectedRoute**: ID of the chosen route
* **selectedPath**: Information about the selected path
  * **blockId**: ID of the selected destination block
  * **blockType**: Type of the selected block
  * **blockTitle**: Title of the selected block

The Router block does not emit a `content` field.

## Custom Output Structures

Some blocks may produce custom output structures based on their configuration:

1. **Agent Blocks with Response Format**: When using a response format in an Agent block, the defined schema fields are returned at the output root alongside standard execution metadata such as `tokens`, `toolCalls`, `providerTiming`, and `cost`.

2. **Function Blocks**: The `result` field can contain any data structure returned by your function code.

3. **API Blocks**: The `data` field will contain whatever the API returns, which could be any valid JSON structure.

Always check the actual output structure of your blocks during development to ensure you're
referencing the correct fields in your connections.

## Nested Data Structures

Many block outputs contain nested data structures. You can access these using dot notation in connection tags:

```
<blockName.path.to.nested.data>
```

For example:

* `<agent1.tokens.total>` - Access the total tokens from an Agent block
* `<api1.data.results[0].id>` - Access the ID of the first result from an API response
* `<function1.result.calculations.total>` - Access a nested field in a Function block's result

## Common Questions

**What output fields does an Agent block produce?**

Without a response format, an Agent block outputs content (the text response), model (the model used, e.g. gpt-4o), tokens (an object with input, output, and total counts), toolCalls (an object with list and count), providerTiming, and cost. There is no separate usage output. When a response format is configured, its fields replace content and model at the output root while the standard execution metadata remains available.

**What does the API block output look like?**

The API block returns data (the response body, which can be any type), status (the HTTP status code as a number), and headers (an object containing the response HTTP headers).

**What does a Function block return?**

A Function block outputs result (the return value of your function, which can be any type) and stdout (any console output captured during execution).

**How does the Condition block output differ from the Router block?**

The Condition block outputs conditionResult (a boolean), selectedPath (with blockId, blockType, and blockTitle of the next block), and selectedOption (the ID of the matched condition). The Router block outputs context (the text it routed), model, tokens, cost, selectedRoute (the chosen route ID), and selectedPath, but does not include content, conditionResult, or selectedOption.

**What happens to the Agent block output when a response format schema is configured?**

When you define a response format on an Agent block, the schema fields are returned at the output root instead of content and model. Standard execution metadata such as tokens, toolCalls, providerTiming, and cost remains available.

**How do I access deeply nested data from an API response?**

Use dot notation with bracket indices in your connection tags. For example, <api1.data.results[0].id> navigates into the data field, then into the results array at index 0, and retrieves the id property.
