> For the complete documentation index, see [llms.txt](https://developer.kizen.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.kizen.com/docs/concepts/agentic-workflows/agentic-workflow-data-model.md).

# Agentic Workflow Data Model

Explore the Kizen Agentic Workflow data model, including core entities, execution records, step history, data guarantees, API mapping, and variable encoding.

{% hint style="success" %}
**Audience:** Administrators, Developers, and Solution Architects

**Purpose:** Explains how <code class="expression">space.vars.automations</code>, executions, and step history are structured, related, and persisted, so you can design reliable integrations, interpret execution data correctly, and build API-driven workflows with a robust understanding of the underlying data.
{% endhint %}

## Overview

<code class="expression">space.vars.automations</code> are backed by a structured data model that governs how workflow configurations, execution <code class="expression">space.vars.entities</code>, and step history are stored and related. Understanding this model is essential when you build integrations, work with the API, or need to trace how execution data relates back to its source entities.

The model spans the core entities that define an <code class="expression">space.vars.automation</code>, as well as the execution and step history <code class="expression">space.vars.entities</code> those entities produce at runtime. The model also frames the guarantees and boundaries that govern that data, and the encoding applied when that data crosses system boundaries through APIs and webhooks.

Use the <code class="expression">space.vars.automation</code> data model if you are:

* Building integrations that read execution or step history data
* Working with <code class="expression">space.vars.automations</code> executions through the API
* Interpreting execution <code class="expression">space.vars.entities</code> and step history to debug a run or to trace which steps ran and what data they produced

The data model builds on the [Agentic Workflow Core Concepts](/docs/concepts/agentic-workflows/agentic-workflow-core-concepts.md) and the [Agentic Workflow Execution & Process Model](/docs/concepts/agentic-workflows/agentic-workflow-execution-and-process-model.md).&#x20;

***

## How Agentic Workflow Data Is Organized

The data model is built from a small set of core entities in a nested hierarchy. Each level contains the next: an <code class="expression">space.vars.automation</code> can have many executions, and each execution can generate many step history <code class="expression">space.vars.entities</code>.&#x20;

<code class="expression">space.vars.entity</code>-scoped configurations sit under an <code class="expression">space.vars.object</code>, which can have many <code class="expression">space.vars.automations</code>. Global configurations have no <code class="expression">space.vars.object</code> above them, so their hierarchy starts at the <code class="expression">space.vars.automation</code>.

### Core Components

* **Agentic Workflow configuration:** The <code class="expression">space.vars.automation</code> definition itself, along with its triggers and steps. A configuration is either <code class="expression">space.vars.entity</code>-scoped, tied to a specific <code class="expression">space.vars.object</code> and running in the context of one <code class="expression">space.vars.entity</code>, or else it's global, running without a <code class="expression">space.vars.entity</code> context for platform-wide logic.
* **Execution:** A single run of an <code class="expression">space.vars.automation</code>, created when a trigger fires. <code class="expression">space.vars.entity</code>-scoped executions runs against a specific <code class="expression">space.vars.entity</code>. One <code class="expression">space.vars.automation</code> configuration can have many executions over time, each as an independent run.
* **Step history:** The step-level events within an execution. Each <code class="expression">space.vars.entity</code> identifies the step, when it was created, when it was last updated, a detailed log, and its current status (Pending, Pending Retry, Completed, and so on). A single step can produce multiple step history <code class="expression">space.vars.entities</code> within one execution if it runs more than once.

The components form a navigable hierarchy. Use it to move between a configuration, its executions, and the step history within a given execution, whether you're troubleshooting in the UI or working with the API directly.

### Step History vs. Execution Records

An execution <code class="expression">space.vars.entity</code> and its step history <code class="expression">space.vars.entities</code> offer two different levels of detail:

* The **execution record** is the summary of the overall run: its status, its start and end times, and its association with the <code class="expression">space.vars.automation</code> and the <code class="expression">space.vars.entity</code>.
* The **step history records** are the details, the individual step-level events within that run.

To debug a run, start from the execution <code class="expression">space.vars.entity</code> for the summary, then use step history for the moment-to-moment analysis.

***

## Agentic Workflow Execution

An <code class="expression">space.vars.automation</code> execution has a defined data model, covering the data it holds, the guarantees the platform makes about that data, and how deleted steps appear in the historical record.

### Execution Status

An execution tracks its current status, not a history of the transitions it has moved through. Its key fields are:

<table><thead><tr><th width="135.5703125">Field</th><th width="216.75390625">Type</th><th>What it Represents</th></tr></thead><tbody><tr><td><code>status</code></td><td>String (enum)</td><td>The execution's current state: <code>Active</code>, <code>Paused</code>, <code>Canceled</code>, <code>Completed</code> or <code>Failed</code>.</td></tr><tr><td><code>priority</code></td><td>String (enum)</td><td>Which queue lane the execution runs in, <code>Standard Processing</code> for low-latency operational runs or <code>Low / Data Seeding</code> for bulk/migration work. Child executions inherit the parent's priority.</td></tr><tr><td><code>in_queue</code></td><td>Boolean</td><td>True when the execution is queued but hasn't started running yet.</td></tr><tr><td><code>debug_mode</code></td><td>Boolean</td><td>Whether the execution pauses at each step for manual advance.</td></tr><tr><td><code>created</code></td><td>Timestamp (date-time)</td><td>When the execution was created.</td></tr><tr><td><code>updated</code></td><td>Timestamp (date-time)</td><td>When the execution was last updated.</td></tr></tbody></table>

For the operational meaning of each state and how to interpret it in the UI, see [Agentic Workflow Status & Lifecycle](/docs/concepts/agentic-workflows/agentic-workflow-status-and-lifecycle.md).

### Data Guarantees & Boundaries

Execution <code class="expression">space.vars.entities</code> guarantee certain data unconditionally, and they bound other data by scope or by configuration changes made after the run.

* **Guarantees:** Every execution has a start timestamp, and every step that has started has a step history record (not only those steps that complete or fail). The state of variables is captured at the execution level. Each step history record carries an `is_pending` flag. Once it's set to false, the record is frozen and won't be modified again. Once an execution reaches a terminal state (Canceled, Failed, or Completed), it can't be resumed or modified, except in debug mode, where you can restart an execution from any previous step.
* **Boundaries:** Only variable values are scoped to a single execution. <code class="expression">space.vars.entity</code> changes are visible immediately to any other automation running against that <code class="expression">space.vars.entity</code>. Most steps run sequentially, but condition, code, and HTTP request steps can execute in parallel across branches, and step history covers every branch in that run.

### Delete Steps

When a step is deleted from an Agentic Workflow configuration after it's already run, Kizen retains the history of its executions. The API returns that history, with the deleted step marked `[Deleted]`. In the product, that history shows in the list view, though not in the canvas view.

The step's own configuration isn't retained. You can't view a deleted step in the product or through the API. Don't rely on resolving a historical step history record back to the configuration that produced it.

***

## How the Data Model Maps to APIs and Webhooks

The <code class="expression">space.vars.automation</code> data model is exposed through APIs and webhooks, and through the encoding model used to represent variable values as they cross system boundaries.

### Mapping to APIs

The <code class="expression">space.vars.automation</code> configuration maps to an API resource, allowing you to list and filter configurations through the API. The response includes the configuration's identity (`id`, `name`, `api_name`) and its `type` (`record_based` or `global`) and `active` state.

It also carries a `revision` number, live counts of active, paused, and completed executions, and the custom object and folder it belongs to. Audit fields track who created and last updated it.

For endpoint-level detail on what's currently available, see the [Kizen API Reference](/api/readme.md).

### Mapping to Webhooks

Before the execution starts, <code class="expression">space.vars.Kizen\_company\_name</code> checks that the caller has permission to start <code class="expression">space.vars.automations</code> on the <code class="expression">space.vars.entity</code>'s <code class="expression">space.vars.object</code>, plus View access to the <code class="expression">space.vars.entity</code> itself. A call that fails either check is rejected with a 403 and no execution is created. The <code class="expression">space.vars.entity</code> reference also determines whether the run executes in <code class="expression">space.vars.entity</code> context, since global <code class="expression">space.vars.automations</code> don't require one.

One webhook call produces one execution, tied to the <code class="expression">space.vars.automation</code> and <code class="expression">space.vars.entity</code> named in the request. That's what lets you trace a webhook call forward to the execution it produced, or trace an execution <code class="expression">space.vars.entity</code> back to the webhook that triggered it.

### Variable Encoding Model

<code class="expression">space.vars.automation</code> variable values are encoded as type/value (T/V) pairs when they are passed across system boundaries, such as in API responses, webhook payloads, and execution history. For example, a String value encodes as:

```
{"t": "s", "v": "Hello, World!"}
```

Each value is encoded as a pair where the type code identifies the <code class="expression">space.vars.Kizen\_company\_name</code> data type and the value contains the serialized content. This encoding exists because <code class="expression">space.vars.Kizen\_company\_name</code>'s type system is richer than native JSON, so a custom encoding is needed to preserve type fidelity.&#x20;

For the full list of type codes and more examples, review the <code class="expression">space.vars.Kizen\_company\_name</code> Data Types and Data Encoding in [Agentic Workflow Code Steps](/docs/concepts/agentic-workflows/automation-code-steps.md).

***

## What's Next

Continue to [Agentic Workflow Code Steps](/docs/concepts/agentic-workflows/automation-code-steps.md) to see how the data model is applied in practice. Code steps build directly on the model described here:

* How <code class="expression">space.vars.Kizen\_company\_name</code> variable values are encoded and passed into code step execution
* How typed <code class="expression">space.vars.objects</code> are provided for working with complex field types
* How execution history captures code step inputs, outputs, and logs

Continue in sequence through the developer documentation for a complete understanding of how to build advanced <code class="expression">space.vars.automation</code> logic programmatically.

<details>

<summary>Related Topics</summary>

* [Agentic Workflow Core Concepts](/docs/concepts/agentic-workflows/agentic-workflow-core-concepts.md)
* [Agentic Workflow Execution & Process Model](/docs/concepts/agentic-workflows/agentic-workflow-execution-and-process-model.md)
* [Agentic Workflow Status & Lifecycle](/docs/concepts/agentic-workflows/agentic-workflow-status-and-lifecycle.md)
* [Agentic Workflow Permissions](/docs/concepts/agentic-workflows/agentic-workflow-permissions.md)

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.kizen.com/docs/concepts/agentic-workflows/agentic-workflow-data-model.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.