Googlesheets

Learn how to use Googlesheets with Composio

Overview

SLUG: GOOGLESHEETS

Description

Google Sheets is a cloud-based spreadsheet tool enabling real-time collaboration, data analysis, and integration with other Google Workspace apps

Authentication Details

client_id
stringRequired
client_secret
stringRequired
oauth_redirect_uri
stringDefaults to https://backend.composio.dev/api/v1/auth-apps/add
scopes
stringDefaults to https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/userinfo.email
bearer_token
string

Connecting to Googlesheets

Create an auth config

Use the dashboard to create an auth config for the Googlesheets toolkit. This allows you to connect multiple Googlesheets accounts to Composio for agents to use.

1

Select App

Navigate to Googlesheets.

2

Configure Auth Config Settings

Select among the supported auth schemes of and configure them here.

3

Create and Get auth config ID

Click “Create Googlesheets Auth Config”. After creation, copy the displayed ID starting with ac_. This is your auth config ID. This is not a sensitive ID — you can save it in environment variables or a database. This ID will be used to create connections to the toolkit for a given user.

Connect Your Account

Using OAuth2

1from composio import Composio
2
3# Replace these with your actual values
4googlesheets_auth_config_id = "ac_YOUR_GOOGLESHEETS_CONFIG_ID" # Auth config ID created above
5user_id = "0000-0000-0000" # UUID from database/application
6
7composio = Composio()
8
9
10def authenticate_toolkit(user_id: str, auth_config_id: str):
11 connection_request = composio.connected_accounts.initiate(
12 user_id=user_id,
13 auth_config_id=auth_config_id,
14 )
15
16 print(
17 f"Visit this URL to authenticate Googlesheets: {connection_request.redirect_url}"
18 )
19
20 # This will wait for the auth flow to be completed
21 connection_request.wait_for_connection(timeout=15)
22 return connection_request.id
23
24
25connection_id = authenticate_toolkit(user_id, googlesheets_auth_config_id)
26
27# You can also verify the connection status using:
28connected_account = composio.connected_accounts.get(connection_id)
29print(f"Connected account: {connected_account}")

Tools

Executing tools

To prototype you can execute some tools to see the responses and working on the Googlesheets toolkit’s playground

Python
1from composio import Composio
2from openai import OpenAI
3import json
4
5openai = OpenAI()
6composio = Composio()
7
8# User ID must be a valid UUID format
9user_id = "0000-0000-0000" # Replace with actual user UUID from your database
10
11tools = composio.tools.get(user_id=user_id, toolkits=["GOOGLESHEETS"])
12
13print("[!] Tools:")
14print(json.dumps(tools))
15
16def invoke_llm(task = "What can you do?"):
17 completion = openai.chat.completions.create(
18 model="gpt-4o",
19 messages=[
20 {
21 "role": "user",
22 "content": task, # Your task here!
23 },
24 ],
25 tools=tools,
26 )
27
28 # Handle Result from tool call
29 result = composio.provider.handle_tool_calls(user_id=user_id, response=completion)
30 print(f"[!] Completion: {completion}")
31 print(f"[!] Tool call result: {result}")
32
33invoke_llm()

Tool List

Tool Name: Add Sheet to Spreadsheet

Description

Adds a new sheet (worksheet) to a spreadsheet. use this tool to create a new tab within an existing google sheet, optionally specifying its title, index, size, and other properties.

Action Parameters

includeSpreadsheetInResponse
boolean
properties
object
responseIncludeGridData
boolean
spreadsheetId
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Append Dimension

Description

Tool to append new rows or columns to a sheet, increasing its size. use when you need to add empty rows or columns to an existing sheet.

Action Parameters

dimension
stringRequired
length
integerRequired
sheet_id
integerRequired
spreadsheet_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Batch update spreadsheet

Description

Updates a specified range in a google sheet with given values, or appends them as new rows if `first cell location` is omitted; ensure the target sheet exists and the spreadsheet contains at least one worksheet.

Action Parameters

first_cell_location
string
includeValuesInResponse
boolean
sheet_name
stringRequired
spreadsheet_id
stringRequired
valueInputOption
stringDefaults to USER_ENTERED
values
arrayRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Clear Basic Filter

Description

Tool to clear the basic filter from a sheet. use when you need to remove an existing basic filter from a specific sheet within a google spreadsheet.

Action Parameters

sheet_id
integerRequired
spreadsheet_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete Dimension (Rows/Columns)

Description

Tool to delete specified rows or columns from a sheet in a google spreadsheet. use when you need to remove a range of rows or columns.

Action Parameters

delete_dimension_request
objectRequired
include_spreadsheet_in_response
boolean
response_include_grid_data
boolean
response_ranges
array
spreadsheet_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Delete Sheet

Description

Tool to delete a sheet (worksheet) from a spreadsheet. use when you need to remove a specific sheet from a google sheet document.

Action Parameters

sheet_id
integerRequired
spreadsheetId
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Spreadsheet by Data Filter

Description

Returns the spreadsheet at the given id, filtered by the specified data filters. use this tool when you need to retrieve specific subsets of data from a google sheet based on criteria like a1 notation, developer metadata, or grid ranges.

Action Parameters

dataFilters
arrayRequired
excludeTablesInBandedRanges
boolean
includeGridData
boolean
spreadsheetId
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get spreadsheet info

Description

Retrieves comprehensive metadata for a google spreadsheet using its id, excluding cell data.

Action Parameters

spreadsheet_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Insert Dimension in Google Sheet

Description

Tool to insert new rows or columns into a sheet at a specified location. use when you need to add empty rows or columns within an existing google sheet.

Action Parameters

include_spreadsheet_in_response
boolean
insert_dimension
objectRequired
response_include_grid_data
boolean
response_ranges
array
spreadsheet_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Search Developer Metadata

Description

Tool to search for developer metadata in a spreadsheet. use when you need to find specific metadata entries based on filters.

Action Parameters

dataFilters
arrayRequired
spreadsheetId
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Set Basic Filter

Description

Tool to set a basic filter on a sheet in a google spreadsheet. use when you need to filter or sort data within a specific range on a sheet.

Action Parameters

filter
objectRequired
spreadsheetId
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Copy Sheet to Another Spreadsheet

Description

Tool to copy a single sheet from a spreadsheet to another spreadsheet. use when you need to duplicate a sheet into a different spreadsheet.

Action Parameters

destination_spreadsheet_id
stringRequired
sheet_id
integerRequired
spreadsheet_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Append Values to Spreadsheet

Description

Tool to append values to a spreadsheet. use when you need to add new data to the end of an existing table in a google sheet.

Action Parameters

includeValuesInResponse
boolean
insertDataOption
string
majorDimension
string
range
stringRequired
responseDateTimeRenderOption
string
responseValueRenderOption
string
spreadsheetId
stringRequired
valueInputOption
stringRequired
values
arrayRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Batch Clear Spreadsheet Values

Description

Tool to clear one or more ranges of values from a spreadsheet. use when you need to remove data from specific cells or ranges while keeping formatting and other properties intact.

Action Parameters

ranges
arrayRequired
spreadsheet_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Batch Clear Values By Data Filter

Description

Clears one or more ranges of values from a spreadsheet using data filters. the caller must specify the spreadsheet id and one or more datafilters. ranges matching any of the specified data filters will be cleared. only values are cleared -- all other properties of the cell (such as formatting, data validation, etc..) are kept.

Action Parameters

dataFilters
arrayRequired
spreadsheetId
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Batch Get Spreadsheet Values by Data Filter

Description

Tool to return one or more ranges of values from a spreadsheet that match the specified data filters. use when you need to retrieve specific data sets based on filtering criteria rather than entire sheets or fixed ranges.

Action Parameters

dataFilters
arrayRequired
dateTimeRenderOption
string
majorDimension
string
spreadsheetId
stringRequired
valueRenderOption
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Update Sheet Properties

Description

Tool to update properties of a sheet (worksheet) within a google spreadsheet, such as its title, index, visibility, tab color, or grid properties. use this when you need to modify the metadata or appearance of a specific sheet.

Action Parameters

spreadsheetId
stringRequired
updateSheetProperties
objectRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Update Spreadsheet Properties

Description

Tool to update properties of a spreadsheet, such as its title, locale, or auto-recalculation settings. use when you need to modify the overall configuration of a google sheet.

Action Parameters

fields
stringRequired
properties
objectRequired
spreadsheetId
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Aggregate Column Data

Description

Searches for rows where a specific column matches a value and performs mathematical operations on data from another column.

Action Parameters

case_sensitive
booleanDefaults to True
has_header_row
booleanDefaults to True
operation
stringRequired
percentage_total
number
search_column
stringRequired
search_value
stringRequired
sheet_name
stringRequired
spreadsheet_id
stringRequired
target_column
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Batch get spreadsheet

Description

Retrieves data from specified cell ranges in a google spreadsheet; ensure the spreadsheet has at least one worksheet and any explicitly referenced sheet names in ranges exist.

Action Parameters

ranges
array
spreadsheet_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Batch Update Values by Data Filter

Description

Tool to update values in ranges matching data filters. use when you need to update specific data in a google sheet based on criteria rather than fixed cell ranges.

Action Parameters

data
arrayRequired
includeValuesInResponse
boolean
responseDateTimeRenderOption
stringDefaults to SERIAL_NUMBER
responseValueRenderOption
stringDefaults to FORMATTED_VALUE
spreadsheetId
stringRequired
valueInputOption
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Clear spreadsheet values

Description

Clears cell content (preserving formatting and notes) from a specified a1 notation range in a google spreadsheet; the range must correspond to an existing sheet and cells.

Action Parameters

range
stringRequired
spreadsheet_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create Chart in Google Sheets

Description

Create a chart in a google sheets spreadsheet using the specified data range and chart type.

Action Parameters

background_blue
number
background_green
number
background_red
number
chart_type
stringRequired
data_range
stringRequired
legend_position
stringDefaults to BOTTOM_LEGEND
sheet_id
integer
spreadsheet_id
stringRequired
subtitle
string
title
string
x_axis_title
string
y_axis_title
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create a Google Sheet

Description

Creates a new google spreadsheet in google drive using the provided title.

Action Parameters

title
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create spreadsheet column

Description

Creates a new column in a google spreadsheet, requiring a valid `spreadsheet id` and an existing `sheet id`; an out-of-bounds `insert index` may append/prepend the column.

Action Parameters

inherit_from_before
boolean
insert_index
integer
sheet_id
integerRequired
spreadsheet_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create spreadsheet row

Description

Inserts a new, empty row into a specified sheet of a google spreadsheet at a given index, optionally inheriting formatting from the row above.

Action Parameters

inherit_from_before
boolean
insert_index
integer
sheet_id
integerRequired
spreadsheet_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Execute SQL on Spreadsheet

Description

Execute sql queries against google sheets tables. supports select, insert, update, and delete operations with familiar sql syntax. tables are automatically detected and mapped from the spreadsheet structure.

Action Parameters

delete_method
stringDefaults to clear
dry_run
boolean
spreadsheet_id
stringRequired
sql
stringRequired

Action Response

affected_rows
integerRequired
data
array
error
string
message
stringRequired
operation
stringRequired
successful
booleanRequired
table_schema
array

Tool Name: Find worksheet by title

Description

Finds a worksheet by its exact, case-sensitive title within a google spreadsheet; returns a boolean indicating if found and the complete metadata of the entire spreadsheet, regardless of whether the target worksheet is found.

Action Parameters

spreadsheet_id
stringRequired
title
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Format cell

Description

Applies text and background cell formatting to a specified range in a google sheets worksheet.

Action Parameters

blue
numberDefaults to 0.9
bold
boolean
end_column_index
integerRequired
end_row_index
integerRequired
fontSize
integerDefaults to 10
green
numberDefaults to 0.9
italic
boolean
red
numberDefaults to 0.9
spreadsheet_id
stringRequired
start_column_index
integerRequired
start_row_index
integerRequired
strikethrough
boolean
underline
boolean
worksheet_id
integerRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get sheet names

Description

Lists all worksheet names from a specified google spreadsheet (which must exist), useful for discovering sheets before further operations.

Action Parameters

spreadsheet_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Table Schema

Description

This action is used to get the schema of a table in a google spreadsheet, call this action to get the schema of a table in a spreadsheet before you query the table. analyze table structure and infer column names, types, and constraints. uses statistical analysis of sample data to determine the most likely data type for each column. call this action after calling the list tables action to get the schema of a table in a spreadsheet.

Action Parameters

sample_size
integerDefaults to 50
sheet_name
string
spreadsheet_id
stringRequired
table_name
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Tables in Spreadsheet

Description

This action is used to list all tables in a google spreadsheet, call this action to get the list of tables in a spreadsheet. discover all tables in a google spreadsheet by analyzing sheet structure and detecting data patterns. uses heuristic analysis to find header rows, data boundaries, and table structures.

Action Parameters

min_columns
integerDefaults to 1
min_confidence
numberDefaults to 0.5
min_rows
integerDefaults to 2
spreadsheet_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Look up spreadsheet row

Description

Finds the first row in a google spreadsheet where a cell's entire content exactly matches the query string, searching within a specified a1 notation range or the first sheet by default.

Action Parameters

case_sensitive
boolean
query
stringRequired
range
string
spreadsheet_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Query Spreadsheet Table

Description

This action is used to query a table in a google spreadsheet, call this action to query a table in a spreadsheet. execute sql-like select queries against spreadsheet tables. supports where conditions, order by, limit clauses. call this action after calling the get table schema action to query a table in a spreadsheet.

Action Parameters

include_formulas
boolean
spreadsheet_id
stringRequired
sql
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Search Spreadsheets

Description

Search for google spreadsheets using various filters including name, content, date ranges, and more.

Action Parameters

created_after
string
include_trashed
boolean
max_results
integerDefaults to 10
modified_after
string
order_by
stringDefaults to modifiedTime desc
query
string
shared_with_me
boolean
starred_only
boolean

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create sheet from JSON

Description

Creates a new google spreadsheet and populates its first worksheet from `sheet json`, which must be non-empty as its first item's keys establish the headers.

Action Parameters

sheet_json
arrayRequired
sheet_name
stringRequired
title
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired