Learning to Use Nodes — Google Sheets Node

This document walks you through the Google Sheets node in Agentria. The Google Sheets node creates, retrieves, adds sheets to, and reads, writes, and clears data in Google Spreadsheets. The fields shown in the Node Editor change depending on which Task you choose.

The Google Sheets node runs one Task per node. This document guides you through the function and usage of all 7 tasks, each demonstrated with a single-node example.

Before You Begin

For instructions on how to enter the Agentria Canvas, refer to the 🔗3-Step Core Guide.

To use the Google Sheets node, you first need to register a Google Credential and connect your Google account. For registration steps, refer to the 🔗Google Credential Setup guide. If you connect using the Client ID / Client Secret method, search for and enable Google Sheets API in the data access scopes.

• You can only work with spreadsheets that the connected Google account can access. To work with someone else's sheet, that sheet must be shared with the connected account.

Common Node Editor Structure

Place the Google Sheets node on the Canvas and double-click it to open the Node Editor. Regardless of which Task you select, the two rules below apply in common.

• The Node Editor initially shows only Credential and Task. Other fields (Spreadsheet ID, range, values, etc.) do not appear on screen right away — you must click the Add Variable button and check the fields you need in the modal before clicking Save for them to appear in the Node Editor. This applies even to required fields, so make sure to check every field the task needs.

• Every task outputs a single Object value called result. It holds the Google Sheets API response as-is, so what it contains differs by task. After running a Node Test, the most reliable way to check the contents is to expand result in the Result tab of the Output panel.

Task List

Choose one of the 7 tasks below from the Task dropdown.

Append to Sheet and Update Sheet are easy to confuse. Append to Sheet finds where to write on its own and appends after the last filled row of existing data, while Update Sheet writes exactly at the specified location, overwriting whatever value was there.

Spreadsheet ID

Every task except Create Spreadsheet requires a Spreadsheet ID (spreadsheet_id). It is the unique string that identifies which Google Spreadsheet file you're working with, and it's found in the address bar URL.

For example, if the address is https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit#gid=0, copy only the part between /d/ and the next / — 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms.

The description text on the Spreadsheet ID field says "ID or URL," but in practice only the ID part works, not the full URL. Entering the full URL causes the node run to fail.

• Correct value: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms

• Incorrect value: https://docs.google.com/spreadsheets/d/1BxiMVs.../edit

If you just created a file with Create Spreadsheet, you can use the resulting result.spreadsheetId value directly.

1. Create Spreadsheet — Create a New Spreadsheet

Creates a new Google Spreadsheet file.

Select Create Spreadsheet from Task, then click Add Variable to bring out the fields below.

If you leave Spreadsheet Title empty, the file is created with the name New Spreadsheet.

After running a Node Test, expand result in the Result tab to check the values below. Detailed information such as sheet properties and formatting is also returned, but the values you'll actually use are the two below.

To write or read values in the file this task created, enter the value of result.spreadsheetId directly into the Spreadsheet ID field of another task.

2. Get Spreadsheet — Retrieve File Information

Retrieves the file title and the list of sheets (tabs) it contains. It does not retrieve cell contents. To read cell values, use Get Sheet Data.

Select Get Spreadsheet from Task, then click Add Variable to bring out the fields below. No new options appear here — both were already covered in Spreadsheet ID and Timeout above.

The result has the same shape as Create Spreadsheet. Expanding result in the Result tab shows the file title at result.properties.title, and the sheet (tab) list in the result.sheets array. If there are multiple sheets, the array has that many entries, and each sheet's name is held in result.sheets[index].properties.title.

3. Create Sheet — Add a Sheet (Tab)

Adds a new sheet (tab) to an existing file.

Select Create Sheet from Task, then click Add Variable to bring out the fields below. The only newly introduced option is Sheet Name (sheet_name).

If you leave Sheet Name empty, it's auto-generated in the format Sheet + a number (e.g. Sheet3). This number keeps increasing based on the total number of sheets ever created in the file, and it does not decrease even if you delete sheets in between. For example, if you create sheets up through Sheet14 and then delete all of them, the next one created will be named Sheet15, not Sheet1.

If a sheet with the same name already exists, you'll get an API operation failed: Failed to create sheet (HTTP 400) error. Use a name that changes each time, such as a date, or check the sheet list first with Get Spreadsheet.

After running a Node Test, expand result in the Result tab in the order result → replies → [0] → addSheet → properties to check the values below.

4. Get Sheet Data — Read Sheet Data

Reads cell values from a specified range.

Select Get Sheet Data from Task, then click Add Variable to bring out the fields below.

If you leave Sheet Range empty, an error occurs. If you omit the sheet name and enter only a column range like A:Z, it targets the Sheet1 tab. Data Interpretation Method (major_dimension) is chosen between Rows and Columns. Rows (default) returns data row by row, matching how a person would see the table; Columns groups values by column, which is convenient for processing column by column. Use Rows unless you have a specific reason not to.

After running a Node Test, expand result in the Result tab to check the values below.

If the sheet looks like this,

result.values holds the data as [["Name", "Age", "City"], ["John", 30, "Seoul"]], one array per row.

If the range has no values at all, result contains only range and majorDimension, and values is not present at all. If a downstream node assumes "there's an array in values," it can fail — plan for the empty case.

5. Append to Sheet — Append Data

Adds a new row at the bottom of existing data. Google figures out where the last row is on its own.

Select Append to Sheet from Task, then click Add Variable to bring out the fields below. The field configuration is the same as 6. Update Sheet.

The decisive difference from Update Sheet is what Sheet Range means. For Append to Sheet, it doesn't mean "write here" — it means "find the table starting from here." If you specify a wide column range like Sheet1!A:C, it automatically appends right after the last already-filled row.

If Values has more columns than the width specified in Sheet Range, the extra columns are still written beyond the range. For example, even if Sheet Range is Sheet1!A:B (2 columns), if Values has 3 columns, column C gets written too. In other words, the column width of Sheet Range isn't a hard limit of "write only up to here" — it's just a reference point for locating the existing table. It works the same way whether you give a narrow range like Sheet1!A2:B3 or just a sheet name like Sheet1.

You can put multiple rows into Values at once. For example, [["Alice", 28, "Incheon"], ["Bob", 34, "Daegu"]] appends both rows together.

After running a Node Test, expand result in the Result tab to check the values below.

6. Update Sheet — Overwrite Data

Writes values exactly at the specified location. Any value that was already there is overwritten.

Select Update Sheet from Task, then click Add Variable to bring out the fields below.

The size of Sheet Range and Values must match. If the range is 3 rows but the values are 5 rows, you'll get an error; if the range is 3 rows but the values are 2 rows, the remaining 3rd row is not cleared and stays as it was. If you want to clear and rewrite, it's safer to clear first with Clear Sheet before writing.

After running a Node Test, expand result in the Result tab to check the values below.

Unlike Append to Sheet, these values are not wrapped once more inside updates — they sit directly under result.

7. Clear Sheet — Clear Data

Clears only the values in a specified range. The sheet itself and formatting (colors, borders, etc.) remain unchanged.

Select Clear Sheet from Task, then click Add Variable to bring out the fields below. No new options appear here.

To keep the header row and clear only the data, specify the range starting from the 2nd row. Specifying Sheet1!A2:Z1000, for instance, keeps the header in row 1 and clears only the values from row 2 onward.

After running a Node Test, expand result in the Result tab to check the value below.

Only the values are cleared — cell formatting (colors, borders, etc.) and the sheet itself remain unchanged.

Range Notation

The Sheet Range (range_name) field uses the same cell-address style as Excel. It's entered in the form SheetName!StartCell:EndCell.

If a sheet name has a space, it's recommended to wrap it in single quotes. It works fine even without quotes since it's handled internally, but wrapping it makes the notation clearer.

• Recommended: 'Sales Summary'!A1:D100

• Also works without quotes: Sales Summary!A1:D100

How to Enter Values (Table Data)

The Values (values) field is best thought of as writing an entire table as a two-dimensional array.

1. Wrap each row in square brackets [ ]. Example: ["John", 30, "Seoul"]

2. Wrap those row brackets in one more outer bracket. Example: [row1, row2, row3]

If you want to enter this table,

you write it like this.

[
  ["Name", "Age", "City"],
  ["John", 30, "Seoul"],
  ["Jane", 25, "Busan"]
]

[
  ["Name", "Age", "City"],
  ["John", 30, "Seoul"],
  ["Jane", 25, "Busan"]
]

[
  ["Name", "Age", "City"],
  ["John", 30, "Seoul"],
  ["Jane", 25, "Busan"]
]

Even for a single row, the outer brackets are required.

• Correct: [["Alice", 28, "Incheon"]]

• Incorrect: ["Alice", 28, "Incheon"] — this can end up written vertically or cause an error

Wrap text in double quotes " ", and write numbers without quotes. Leave empty cells as "".

The kinds of values you can put in a single cell are below.

Dates, percentages, currency, and formulas are only interpreted when Value Input Option is User Entered. If it's Raw, everything is stored as literal text. Links are an exception — a URL-shaped string becomes a clickable link automatically regardless of User Entered or Raw. See Value Input Option for a detailed comparison.

To include a double quote or a line break inside text, prefix it with a backslash \.

A single quote ' and a comma , can be used as-is inside text.

Value Input Option

Value Input Option (value_input_option) determines whether Google interprets the values you enter in Append to Sheet and Update Sheet, or stores them as literal text.

The typical case for choosing Raw is when you're dealing with values where a leading zero must not be dropped, such as phone numbers, postal codes, or employee IDs. In every other case, keep the default User Entered.

If you write the same value (e.g. a date, a percentage, a number, a formula) once with User Entered and once with Raw, the difference is clear. The User Entered row shows dates, percentages, and numbers all right-aligned, indicating they were recognized as actual date/number types, and a formula such as =SUM(1,2,3) is calculated into its result value. The Raw row is left-aligned as literal text, and a formula stays exactly as typed.

A link (a URL string such as https://example.com) shows up as a clickable link under both options. Google Sheets appears to auto-linkify URL-shaped strings regardless of the value input option.

Include Values In Response

Include Values In Response (include_values_in_response) is a checkbox you can bring out via Add Variable for the Append to Sheet and Update Sheet tasks.

When turned on, updatedData is added inside result.updates; expanding it in the Result tab shows the range actually written (updatedData.range) and the values (updatedData.values).

Turn this on when Value Input Option is User Entered and Google may have converted the value before storing it (for example, entering "0123" and having it stored as 123), and you want to confirm exactly what was written. Since the result grows larger with more data, it's recommended to leave it off in normal use.

Timeout

The maximum time to wait for Google's response.

• Unit: seconds (default 60 seconds)

• Enter as a whole number with no decimal point

If you get a timeout error while reading a wide range or writing many rows at once, increase this value. If it still fails, consider narrowing the range and processing it in multiple passes instead.

Chaining Multiple Nodes

The examples in this document use a single node to check the input and output of each task on its own. In real workflows, you often need to chain several Google Sheets nodes so values pass automatically, such as "create a new file → write a value using its ID."

Because each task's output is nested inside a single Object called result, you can't drag and drop a single value inside it, such as spreadsheetId, directly into a String field of the next node (e.g. spreadsheet_id). In that case, the usual approach is to connect the Google Sheets node as a function node called from a Python node, then extract only the value you need with something like result.get("spreadsheetId"). This setup requires writing Python code and is an advanced use case not covered in this document.

What This Node Cannot Do

The Google Sheets node does not support the tasks below. If you need them, you'll have to handle them directly in Google Sheets or find another method.

• Deleting, renaming, or reordering sheets (tabs)

• Deleting the spreadsheet file or changing sharing settings

• Specifying cell formatting (font, color, borders, conditional formatting)

• Inserting/deleting rows or columns, adjusting column width

• Creating charts or pivot tables

• Applying filters or sorting

Common Mistakes

Next Steps

🎉 Congratulations! You've run each of the 7 tasks of the Google Sheets node in Agentria.

Try building a workflow that chains multiple tasks together, such as writing a header row with Update Sheet and then piling up data with Append to Sheet on a file you created with Create Spreadsheet.

Agentria is a place where ideas become reality—your workflow can expand infinitely with your creativity.

• For more Ability examples, visit the 🔗Ability Guide.

• For Agent-based examples, visit the 🔗Agent Guide.

Frequently Asked Questions

What is the Google Sheets node?

The Google Sheets node is a node in Agentria that creates, retrieves, adds sheets to, and reads, writes, and clears data in Google Spreadsheets. It belongs to the Utility & Productivity category, and you choose one of Create Spreadsheet, Get Spreadsheet, Create Sheet, Get Sheet Data, Append to Sheet, Update Sheet, or Clear Sheet from the Task field to determine its behavior.

What do I need to prepare to use the Google Sheets node?

You need to register a Google Credential and connect your Google account. For connection steps, refer to the 🔗Google Credential Setup guide. You can only work with spreadsheets accessible to the connected account, so a sheet owned by someone else needs to be shared with you first.

Fields like Spreadsheet ID don't show up in the Node Editor.

The Google Sheets node shows only Credential and Task by default — every other field must be checked and brought out via the Add Variable button. This applies even to required fields, so make sure to check every field the task you're using needs, in the Add Variable modal.

How is Append to Sheet different from Update Sheet?

Append to Sheet finds the last filled row of existing data on its own and adds a new row after it. Update Sheet, on the other hand, writes values exactly at the specified range, and whatever was there before is overwritten. Use Append to Sheet for data that needs to keep accumulating, like logs or submissions, and Update Sheet when you need to update a specific cell or area.

What format do I use for table data in the Values field?

Wrap each row's values in brackets, then wrap those rows in one more outer bracket — a two-dimensional array. For example, a two-row table would be written as [["John", 30, "Seoul"], ["Jane", 25, "Busan"]]. Even a single row still needs the outer brackets. For detailed notation rules, see How to Enter Values (Table Data).

Can one node handle multiple tasks?

No. A single Google Sheets node only runs the one action selected in Task. To process multiple tasks in sequence, place several Google Sheets nodes and select a different Task on each, then connect them in order.