> 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/integrations-and-plugins/integrations/google-sheets/work-with-google-sheets-in-agentic-workflows.md).

# Work with Google Sheets in Agentic Workflows

Get rows, search rows, append rows, and update rows in Google Sheets directly from Agentic Workflows in Kizen.

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

**Purpose:** Describes the procedures for using Google Sheets action steps in <code class="expression">space.vars.Kizen\_company\_name</code>'s <code class="expression">space.vars.automations</code>.
{% endhint %}

## Overview

{% hint style="warning" %}
**Caution:** This setup reflects Kizen's default configuration. Your administrator may have customized your layout, so columns or navigation may appear differently. Trial accounts may have limited features.
{% endhint %}

With the Google Sheets integration, you can set up <code class="expression">space.vars.automations</code> in <code class="expression">space.vars.Kizen\_company\_name</code> to retrieve live Google Sheets™ data, search data on the sheet, append new rows to the sheet, and update existing rows or cells.

***

## Before You Begin

To work with Google Sheets in <code class="expression">space.vars.automations</code>, you need an active, authenticated connection to Google Sheets.

For more information, see [Set Up Google Sheets in Kizen](/docs/integrations-and-plugins/integrations/google-sheets/set-up-google-sheets-in-kizen.md).

***

## Work with Google Sheets in Agentic Workflows

To work with Google Sheets in <code class="expression">space.vars.automations</code>:

{% stepper %}
{% step %}

#### Go to the Agentic Workflow builder

In the global navigation, select **Agentic Workflows**. Then, to open the builder, do one of the following:

* Select **New Agentic Workflow**.
* Select the name of an existing <code class="expression">space.vars.automation</code>.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FpWfApnarj1esWvuOL1Xy%2Fglobal_newagenticworkflow.png?alt=media&amp;token=a3289c6f-f03c-4ee5-ba3e-9e39e4274af4" alt="The New Agentic Workflows button on the Agentic Workflows page" width="563"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

#### Add an action to the workflow

Select **+**, and then select **Add Action**.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2F4I4RYiryLGZqxzqBUpsT%2Fglobal_addaction.png?alt=media&amp;token=4c641727-01fc-4dd4-b533-a58ed1e08a61" alt="The Add Action context menu item in the Agentic Workflow builder" width="563"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

#### Select the Google Sheets action

In the Add Action modal that opens, scroll to the Integration section, and select the Google Sheets connector card.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2F55ce6t07XxjgUlz7RHRq%2Fgooglesheets_addaction.png?alt=media&amp;token=cd273d11-b4e8-46dd-8f56-91f4ddfa960a" alt="The Google Sheets connector card on the Add Action modal" width="563"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

#### Choose the function to perform

In the Action Settings section of the Add Action modal, select the **Action** dropdown menu, and do one of the following:

* To add a new row to the bottom of a sheet, select **Append Row**, and set up the action. For more information, see [Set Up an Append Row Action](#set-up-an-append-row-action) below.
* To return one or more rows from a sheet, select **Get Rows**, and set up the action. For more information, see [Set Up a Get Rows Action](#set-up-a-get-rows-action) below.
* To find sheet data that matches search criteria, select **Search Rows**, and set up the action. For more information, see [Set Up a Search Rows Action](#set-up-a-search-rows-action) below.
* To update the data in a row or cell, select **Update Row/Cell**, and set up the action. For more information, see [Set Up an Update Row/Cell](#set-up-an-update-row-cell-action) Action below.
  {% endstep %}

{% step %}

#### Configure error handling

In the Error Handling section of the modal, specify how to handle errors in this step of the <code class="expression">space.vars.automation</code>.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FGzhPBGaxlzsW1tWJMZYU%2FScreenshot%202026-07-16%20at%209.13.52%E2%80%AFAM.png?alt=media&amp;token=5dc5daed-6009-44f6-8120-e7124eb6aee8" alt="The error handling options in the Add Action modal" width="563"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

#### Save the Google Sheets action

Select **Save**.
{% endstep %}
{% endstepper %}

***

## Set Up an Append Row Action

The Append Row action adds a new row to the bottom of the specified sheet.

{% hint style="info" %}
**Note:** Google Sheets treats your row data exactly as if you had typed it onto the sheet and converts the data types of certain values accordingly.

For more information, see [Google Sheets](/docs/integrations-and-plugins/integrations/google-sheets.md#input-handling).
{% endhint %}

To set up an Append Row action:&#x20;

{% stepper %}
{% step %}

#### Configure the sources for the script inputs

For each of the fields in the Script Inputs section of the Add Action modal, select the source of the field's value from the **Input Source** dropdown menu, and then configure the source with the additional controls that appear.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2Fm5X58lnKBT8zpBsw81xU%2Fgooglesheets_appendrow_inputs.png?alt=media&amp;token=364aefcd-68d8-4248-afce-f6bff3a602a0" alt="The script inputs for the Append Row action in the Add Action modal" width="563"><figcaption></figcaption></figure></div>

The fields are as follows:

<table data-search="false"><thead><tr><th>Field</th><th>Type</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><strong>Header Column</strong></td><td><code>Number</code></td><td>The column of the sheet that contains the header. Convert the alphabetical header to its numerical equivalent: <code>A</code> = <code>1</code>, <code>B</code> = <code>2</code>, <code>C</code> = <code>3</code>, and so on. The default value is <code>1</code>.</td><td>No</td></tr><tr><td><strong>Header Row</strong></td><td><code>Number</code></td><td>The row of the sheet that contains the header. The default value is <code>1</code>.</td><td>No</td></tr><tr><td><strong>Row Data</strong></td><td><code>String</code></td><td>A JSON object containing the row data to append to the sheet, such as <code>{"Movie": "Carrie", "Year": 1976}</code> .</td><td>Yes</td></tr><tr><td><strong>Sheet Name</strong></td><td><code>String</code></td><td>The name of the sheet tab.</td><td>Yes</td></tr><tr><td><strong>Spreadsheet ID</strong></td><td><code>String</code></td><td>The technical identifier of the sheet. For more information, see <a href="/docs/integrations-and-plugins/integrations/google-sheets.md#sheet-identification">Google Sheets</a>.</td><td>Yes</td></tr></tbody></table>

{% endstep %}

{% step %}

#### Configure the destinations for the script outputs

For each of the fields in the Script Outputs section of the modal, select the destination of the field's value from the **Output Destination** dropdown menu, and then configure the destination with the additional controls that appear.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2F50DWj93nTwHCrOWLVsDk%2Fgooglesheets_appendrow_outputs.png?alt=media&amp;token=955e2aa1-7279-4019-9d6d-4e8a90037198" alt="The script outputs for the Append Row action in the Add Action modal" width="563"><figcaption></figcaption></figure></div>

The fields are as follows:

| Field              | Type     | Description                                                                                                                                                          | Required? |
| ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| **Row Number**     | `Number` | The number of the appended row.                                                                                                                                      | No        |
| **Spreadsheet ID** | `String` | The technical identifier of the sheet. For more information, see [Google Sheets](/docs/integrations-and-plugins/integrations/google-sheets.md#sheet-identification). | No        |
| {% endstep %}      |          |                                                                                                                                                                      |           |
| {% endstepper %}   |          |                                                                                                                                                                      |           |

***

## Set Up a Get Rows Action

The Get Rows action returns one or more rows of data from the specified sheet:

* By default, this action returns all the rows on the sheet tab.
* To limit the results to certain rows, identify the rows to return according to a particular column value using the **Filter Value** and **Filter Column** input fields. For example, to return only those rows in a horror movie spreadsheet where Tobe Hooper is the director, set **Filter Column** to the director column and **Filter Value** to `Tobe Hooper`.&#x20;

{% hint style="info" %}
**Note:** You can't retrieve more than 50,000 characters with this action.

See [Google Sheets](/docs/integrations-and-plugins/integrations/google-sheets.md#results-handling) for more information.
{% endhint %}

To set up a Get Rows action:&#x20;

{% stepper %}
{% step %}

#### Configure the sources for the script inputs

For each of the fields in the Script Inputs section of the Add Action modal, select the source of the field's value from the **Input Source** dropdown menu, and then configure the source with the additional controls that appear.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FFZCV8GruUR7F3qKDx7Av%2Fgooglesheets_getrows_inputs.png?alt=media&amp;token=f6cabc8b-5ecc-49d9-a06c-f122198870cb" alt="The script inputs for the Get Rows action in the Add Action modal" width="563"><figcaption></figcaption></figure></div>

The fields are as follows:

<table data-search="false"><thead><tr><th>Field</th><th>Type</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><strong>Filter Column</strong></td><td><code>String</code></td><td>The column to use to filter the results.</td><td>No</td></tr><tr><td><strong>Filter Value</strong></td><td><code>String</code></td><td>The value of the filter column to target.</td><td>No</td></tr><tr><td><strong>Header Column</strong></td><td><code>Number</code></td><td>The column of the sheet that contains the header. Convert the alphabetical header to its numerical equivalent: <code>A</code> = <code>1</code>, <code>B</code> = <code>2</code>, <code>C</code> = <code>3</code>, and so on. The default value is <code>1</code>.</td><td>No</td></tr><tr><td><strong>Header Row</strong></td><td><code>Number</code></td><td>The row of the sheet that contains the header. The default value is <code>1</code>.</td><td>No</td></tr><tr><td><strong>Sheet Name</strong></td><td><code>String</code></td><td>The name of the sheet tab.</td><td>Yes</td></tr><tr><td><strong>Spreadsheet ID</strong></td><td><code>String</code></td><td>The technical identifier of the sheet. For more information, see <a href="/docs/integrations-and-plugins/integrations/google-sheets.md#sheet-identification">Google Sheets</a>.</td><td>Yes</td></tr></tbody></table>
{% endstep %}

{% step %}

#### Configure the destinations for the script outputs

For each of the fields in the Script Outputs section of the modal, select the destination of the field's value from the **Output Destination** dropdown menu, and then configure the destination with the additional controls that appear.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FVoWk5ruMvmYKIy07NMgQ%2Fgooglesheets_getrows_outputs.png?alt=media&amp;token=5b963152-2be9-4bae-8f86-6e15be7a4639" alt="The script outputs for the Get Rows action in the Add Action modal" width="563"><figcaption></figcaption></figure></div>

The fields are as follows:

| Field            | Type     | Description                               | Required? |
| ---------------- | -------- | ----------------------------------------- | --------- |
| **Row Count**    | `Number` | The total number of rows in the results.  | No        |
| **Rows**         | `String` | The row data as a stringified JSON array. | No        |
| {% endstep %}    |          |                                           |           |
| {% endstepper %} |          |                                           |           |

***

## Set Up a Search Rows Action

The Search Rows action finds data on a sheet that matches your search criteria. Specifically, the integration returns the data from the matching rows under a particular column of the sheet. You identify the column under which to search, the target value, and the comparison to apply to the target value with the action input fields.

{% hint style="info" %}
**Note:** The results set for this action can't contain more than 50,000 characters.

See [Google Sheets](/docs/integrations-and-plugins/integrations/google-sheets.md#results-handling) for more information.
{% endhint %}

To set up a Search Rows action:&#x20;

{% stepper %}
{% step %}

#### Configure the sources for the script inputs

For each of the fields in the Script Inputs section of the Add Action modal, select the source of the field's value from the **Input Source** dropdown menu, and then configure the source with the additional controls that appear.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2Ff9Z9hobOsIP4imCpX0q2%2Fgooglesheets_searchrows_inputs.png?alt=media&amp;token=c07e2019-cdf8-4c05-936e-9cb0f6ec5843" alt="The script inputs for the Search Rows action in the Add Action modal" width="563"><figcaption></figcaption></figure></div>

The fields are as follows:

<table data-search="false"><thead><tr><th>Field</th><th>Type</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><strong>Column Name</strong></td><td><code>String</code></td><td>The column to search.</td><td>Yes</td></tr><tr><td><strong>Header Column</strong></td><td><code>Number</code></td><td>The column of the sheet that contains the header. Convert the alphabetical header to its numerical equivalent: <code>A</code> = <code>1</code>, <code>B</code> = <code>2</code>, <code>C</code> = <code>3</code>, and so on. The default value is <code>1</code>.</td><td>No</td></tr><tr><td><strong>Header Row</strong></td><td><code>Number</code></td><td>The row of the sheet that contains the header. The default value is <code>1</code>.</td><td>No</td></tr><tr><td><strong>Match Type</strong></td><td><code>String</code></td><td>The comparison to use against the <strong>Match Value</strong> field. The supported match types are <code>equals</code>, <code>not_equals</code>, <code>contains</code>, <code>starts_with</code>, <code>is_empty</code>, and <code>is_not_empty</code>.</td><td>No</td></tr><tr><td><strong>Match Value</strong></td><td><code>String</code></td><td>The value against which the comparison in the <strong>Match Type</strong> field is made. You must supply a comparison value for all mach types except <code>is_empty</code> and <code>is_not_empty</code>.</td><td>No</td></tr><tr><td><strong>Return All Matches</strong></td><td><code>Boolean</code></td><td>Whether to return all matching rows (<code>true</code>) or stop at the first match (<code>false</code>).</td><td>Yes</td></tr><tr><td><strong>Sheet Name</strong></td><td><code>String</code></td><td>The name of the sheet tab.</td><td>Yes</td></tr><tr><td><strong>Spreadsheet ID</strong></td><td><code>String</code></td><td>The technical identifier of the sheet. For more information, see <a href="/docs/integrations-and-plugins/integrations/google-sheets.md#sheet-identification">Google Sheets</a>.</td><td>Yes</td></tr></tbody></table>
{% endstep %}

{% step %}

#### Configure the destinations for the script outputs

For each of the fields in the Script Outputs section of the modal, select the destination of the field's value from the **Output Destination** dropdown menu, and then configure the destination with the additional controls that appear.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FIquCbobWmfNJADRrzmka%2Fgooglesheets_searchrows_outputs.png?alt=media&amp;token=c7ef6742-2060-4ecb-ae02-1eff427c4bc0" alt="The script outputs for the Search Rows action in the Add Action modal" width="563"><figcaption></figcaption></figure></div>

The fields are as follows:

| Field             | Type     | Description                                                  | Required? |
| ----------------- | -------- | ------------------------------------------------------------ | --------- |
| **Matching Rows** | `String` | The row data from the results as a stringified JSON array    | No        |
| **Row Numbers**   | `String` | The row numbers from the results as a stringified JSON array | No        |
| {% endstep %}     |          |                                                              |           |
| {% endstepper %}  |          |                                                              |           |

***

## Set Up an Update Row/Cell Action

The Update Row/Cell action writes new data to the specified row or cell of a sheet. Identify the row or cell to update in one of two ways:

* By its row. This is the more precise method.
* By a matching value in a column on the sheet. Because more than one row might have the same target value in the column, this method can return ambiguous results. Unless you set the action to update all the matching rows, it fails with an error when more than one row meets the match criteria.

{% hint style="info" %}
**Note:** Google Sheets treats your row data exactly as if you had typed it onto the sheet and converts the data types of certain values accordingly.

See [Google Sheets](/docs/integrations-and-plugins/integrations/google-sheets.md#input-handling) for details.
{% endhint %}

To set up an Update Row/Cell action:&#x20;

{% stepper %}
{% step %}

#### Configure the sources for the script inputs

For each of the fields in the Script Inputs section of the Add Action modal, select the source of the field's value from the **Input Source** dropdown menu, and then configure the source with the additional controls that appear.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2Fz3eSsgRPrltuCkFNQmaW%2Fgooglesheets_updaterowcell_inputs.png?alt=media&amp;token=336428ff-2858-4ac2-a89a-b3e8648b0d65" alt="The script inputs for the Update Row/Cell action in the Add Action modal" width="563"><figcaption></figcaption></figure></div>

The fields are as follows:

<table data-search="false"><thead><tr><th>Field</th><th>Type</th><th>Description</th><th>Required?</th></tr></thead><tbody><tr><td><strong>Header Column</strong></td><td><code>Number</code></td><td>The column of the sheet that contains the header. Convert the alphabetical header to its numerical equivalent: <code>A</code> = <code>1</code>, <code>B</code> = <code>2</code>, <code>C</code> = <code>3</code>, and so on. The default value is <code>1</code>.</td><td>No</td></tr><tr><td><strong>Header Row</strong></td><td><code>Number</code></td><td>The row of the sheet that contains the header. The default value is <code>1</code>.</td><td>No</td></tr><tr><td><strong>Match Column</strong></td><td><code>String</code></td><td>The name of the column in which to look for the match value.</td><td>No</td></tr><tr><td><strong>Match Value</strong></td><td><code>String</code></td><td>The target value from the match column.</td><td>No</td></tr><tr><td><strong>Row Data</strong></td><td><code>String</code></td><td>A JSON object containing the data to write to the sheet of the row, such as <code>{"Movie": "Scream", "Year": 1996}</code> .</td><td>Yes</td></tr><tr><td><strong>Row Number</strong></td><td><code>Number</code></td><td>The number of the row to update.</td><td>No</td></tr><tr><td><strong>Sheet Name</strong></td><td><code>String</code></td><td>The name of the sheet tab.</td><td>Yes</td></tr><tr><td><strong>Spreadsheet ID</strong></td><td><code>String</code></td><td>The technical identifier of the sheet. For more information, see <a href="/docs/integrations-and-plugins/integrations/google-sheets.md#sheet-identification">Google Sheets</a>.</td><td>Yes</td></tr><tr><td><strong>Update All Matches</strong></td><td><code>Boolean</code></td><td>Whether to update all possible matches in the sheet tab. If <code>false</code> and more than one row matches your criteria, the integration throws an error.</td><td>Yes</td></tr></tbody></table>
{% endstep %}

{% step %}

#### Configure the destinations for the script outputs

For each of the fields in the Script Outputs section of the modal, select the destination of the field's value from the **Output Destination** dropdown menu, and then configure the destination with the additional controls that appear.

<div data-with-frame="true"><figure><img src="https://3898351136-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQd8ufpN7wkdnx7JtgoeZ%2Fuploads%2FNN2vGswH4ig6rNGCCQuZ%2Fgooglesheets_updaterowcell_outputs.png?alt=media&amp;token=4633335f-fda2-4f73-b380-bee08fb634c4" alt="The script outputs for the Update Row/Cell action in the Add Action modal" width="563"><figcaption></figcaption></figure></div>

The fields are as follows:

| Field            | Type      | Description                              | Required? |
| ---------------- | --------- | ---------------------------------------- | --------- |
| **Rows Updated** | `String`  | The number of rows updated               | No        |
| **Success**      | `Boolean` | Whether the update action was successful | No        |

{% hint style="info" %}
**Note:** The **Rows Updated** field returns a numerical value, but as the `String` data type, not as a `Number`.
{% endhint %}
{% endstep %}
{% endstepper %}

***

## What's Next

Continue to [Troubleshoot Google Sheets](/docs/integrations-and-plugins/integrations/google-sheets/troubleshoot-google-sheets.md) to find solutions for common issues with the Google Sheets integration.

<details>

<summary><strong>Related Topics</strong></summary>

* [Google Sheets](/docs/integrations-and-plugins/integrations/google-sheets.md)
* [Set Up Google Sheets in Kizen](/docs/integrations-and-plugins/integrations/google-sheets/set-up-google-sheets-in-kizen.md)
* [Troubleshoot Google Sheets](/docs/integrations-and-plugins/integrations/google-sheets/troubleshoot-google-sheets.md)

</details>

***

*Google Sheets™ is a trademark of Google LLC. Kizen's Google Sheets integration is not affiliated with, sponsored by, or endorsed by Google LLC.*


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.kizen.com/docs/integrations-and-plugins/integrations/google-sheets/work-with-google-sheets-in-agentic-workflows.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.