grr
api reference · v4

Every Sheets method, from the index.

All 17 methods of the Sheets API, rendered at build time from the committed Discovery index the grr binary embeds — the same data grr api describe reads at runtime. Flags are kebab-cased parameter names: userId is --user-id.

17 methods · v4 · revision 20261111

sheets.spreadsheets

4 methods

sheets.spreadsheets.batchUpdate

POST

grr sheets spreadsheets batchUpdate v4/spreadsheets/{spreadsheetId}:batchUpdate

Applies one or more updates to the spreadsheet. Each request is validated before being applied. If any request is not valid then the entire request will fail and nothing will be applied. Some requests have replies to give you some information about how they are applied. The replies will mirror the requests. For example, if you applied 4 updates and the 3rd one had a reply, then the response will have 2 empty replies, the actual reply, and another empty reply, in that order. Due to the collaborative nature of spreadsheets, it is not guaranteed that the spreadsheet will reflect exactly your chan

Parameter Type Required Repeated Location Description Enum values
spreadsheetId string yes — path The spreadsheet to apply the updates to. —
https://www.googleapis.com/auth/spreadsheets least privilege
3 scopes
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/spreadsheets
grr sheets spreadsheets batchUpdate 
grr sheets spreadsheets batchUpdate --spreadsheet-id <spreadsheet-id> --body-file ./body.json

sheets.spreadsheets.create

POST

grr sheets spreadsheets create v4/spreadsheets

Creates a spreadsheet, returning the newly created spreadsheet.

No parameters.

https://www.googleapis.com/auth/spreadsheets least privilege
3 scopes
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/spreadsheets
grr sheets spreadsheets create 
grr sheets spreadsheets create --body-file ./body.json

sheets.spreadsheets.get

GET

grr sheets spreadsheets get v4/spreadsheets/{spreadsheetId}

Returns the spreadsheet at the given ID. The caller must specify the spreadsheet ID. By default, data within grids is not returned. You can include grid data in one of 2 ways: * Specify a field mask listing your desired fields using the fields URL parameter in HTTP * Set the includeGridData URL parameter to true. If a field mask is set, the includeGridData parameter is ignored For large spreadsheets, as a best practice, retrieve only the specific spreadsheet fields that you want. To retrieve only subsets of spreadshee

Parameter Type Required Repeated Location Description Enum values
commentsViewMode string — — query The comments view mode to apply to the spreadsheet. This allows viewing the spreadsheet with comments omitted or included. If one is not specified, COMMENTS_VIE COMMENTS_VIEW_MODE_UNSPECIFIED · COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS · COMMENTS_VIEW_MODE_OMITTED · COMMENTS_VIEW_MODE_INCLUDED
excludeTablesInBandedRanges boolean — — query True if tables should be excluded in the banded ranges. False if not set. —
includeGridData boolean — — query True if grid data should be returned. This parameter is ignored if a field mask was set in the request. —
ranges string — yes query The ranges to retrieve from the spreadsheet. —
spreadsheetId string yes — path The spreadsheet to request. —
https://www.googleapis.com/auth/spreadsheets.readonly least privilege
5 scopes
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/drive.readonly
  • https://www.googleapis.com/auth/spreadsheets
  • https://www.googleapis.com/auth/spreadsheets.readonly
grr sheets spreadsheets get 
grr sheets spreadsheets get --spreadsheet-id <spreadsheet-id>

sheets.spreadsheets.getByDataFilter

POST

grr sheets spreadsheets getByDataFilter v4/spreadsheets/{spreadsheetId}:getByDataFilter

Returns the spreadsheet at the given ID. The caller must specify the spreadsheet ID. For more information, see Read, write, and search metadata. This method differs from GetSpreadsheet in that it allows selecting which subsets of spreadsheet data to return by specifying a dataFilters parameter. Multiple DataFilters can be specified. Specifying one or more data filters returns the portions of the spreadsheet that intersect ranges matched by any of the filters. By default, data within grids is not returned. You can include gri

Parameter Type Required Repeated Location Description Enum values
spreadsheetId string yes — path The spreadsheet to request. —
https://www.googleapis.com/auth/spreadsheets least privilege
3 scopes
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/spreadsheets
grr sheets spreadsheets getByDataFilter 
grr sheets spreadsheets getByDataFilter --spreadsheet-id <spreadsheet-id> --body-file ./body.json

sheets.spreadsheets.developerMetadata

2 methods

sheets.spreadsheets.developerMetadata.get

GET

grr sheets spreadsheets developerMetadata get v4/spreadsheets/{spreadsheetId}/developerMetadata/{metadataId}

Returns the developer metadata with the specified ID. The caller must specify the spreadsheet ID and the developer metadata's unique metadataId. For more information, see Read, write, and search metadata.

Parameter Type Required Repeated Location Description Enum values
metadataId integer yes — path The ID of the developer metadata to retrieve. —
spreadsheetId string yes — path The ID of the spreadsheet to retrieve metadata from. —
https://www.googleapis.com/auth/spreadsheets least privilege
3 scopes
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/spreadsheets
grr sheets spreadsheets developerMetadata get 
grr sheets spreadsheets developerMetadata get --metadata-id <metadata-id> --spreadsheet-id <spreadsheet-id>

sheets.spreadsheets.sheets

1 method

sheets.spreadsheets.sheets.copyTo

POST

grr sheets spreadsheets sheets copyTo v4/spreadsheets/{spreadsheetId}/sheets/{sheetId}:copyTo

Copies a single sheet from a spreadsheet to another spreadsheet. Returns the properties of the newly created sheet.

Parameter Type Required Repeated Location Description Enum values
sheetId integer yes — path The ID of the sheet to copy. —
spreadsheetId string yes — path The ID of the spreadsheet containing the sheet to copy. —
https://www.googleapis.com/auth/spreadsheets least privilege
3 scopes
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/spreadsheets
grr sheets spreadsheets sheets copyTo 
grr sheets spreadsheets sheets copyTo --sheet-id <sheet-id> --spreadsheet-id <spreadsheet-id> --body-file ./body.json

sheets.spreadsheets.values

10 methods

sheets.spreadsheets.values.append

POST

grr sheets spreadsheets values append v4/spreadsheets/{spreadsheetId}/values/{range}:append

Appends values to a spreadsheet. The input range is used to search for existing data and find a "table" within that range. Values will be appended to the next row of the table, starting with the first column of the table. See the guide and sample code for specific details of how tables are detected and data is appended. The caller must specify the spreadsheet ID, range, and a valueInputOption. The valueInputOption only contro

Parameter Type Required Repeated Location Description Enum values
includeValuesInResponse boolean — — query Determines if the update response should include the values of the cells that were appended. By default, responses do not include the updated values. —
insertDataOption string — — query How the input data should be inserted. OVERWRITE · INSERT_ROWS
range string yes — path The A1 notation of a range to search for a logical table of data. Values are appended —
responseDateTimeRenderOption string — — query Determines how dates, times, and durations in the response should be rendered. This is ignored if response_value_render_option is FORMATTED_VALUE. The default d SERIAL_NUMBER · FORMATTED_STRING
responseValueRenderOption string — — query Determines how values in the response should be rendered. The default render option is FORMATTED_VALUE. FORMATTED_VALUE · UNFORMATTED_VALUE · FORMULA
spreadsheetId string yes — path The ID of the spreadsheet to update. —
valueInputOption string — — query How the input data should be interpreted. INPUT_VALUE_OPTION_UNSPECIFIED · RAW · USER_ENTERED
https://www.googleapis.com/auth/spreadsheets least privilege
3 scopes
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/spreadsheets
grr sheets spreadsheets values append 
grr sheets spreadsheets values append --range <range> --spreadsheet-id <spreadsheet-id> --body-file ./body.json

sheets.spreadsheets.values.batchClear

POST

grr sheets spreadsheets values batchClear v4/spreadsheets/{spreadsheetId}/values:batchClear

Clears one or more ranges of values from a spreadsheet. The caller must specify the spreadsheet ID and one or more ranges. Only values are cleared -- all other properties of the cell (such as formatting and data validation) are kept.

Parameter Type Required Repeated Location Description Enum values
spreadsheetId string yes — path The ID of the spreadsheet to update. —
https://www.googleapis.com/auth/spreadsheets least privilege
3 scopes
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/spreadsheets
grr sheets spreadsheets values batchClear 
grr sheets spreadsheets values batchClear --spreadsheet-id <spreadsheet-id> --body-file ./body.json

sheets.spreadsheets.values.batchClearByDataFilter

POST

grr sheets spreadsheets values batchClearByDataFilter v4/spreadsheets/{spreadsheetId}/values:batchClearByDataFilter

Clears one or more ranges of values from a spreadsheet. For more information, see Read, write, and search metadata. 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.

Parameter Type Required Repeated Location Description Enum values
spreadsheetId string yes — path The ID of the spreadsheet to update. —
https://www.googleapis.com/auth/spreadsheets least privilege
3 scopes
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/spreadsheets
grr sheets spreadsheets values batchClearByDataFilter 
grr sheets spreadsheets values batchClearByDataFilter --spreadsheet-id <spreadsheet-id> --body-file ./body.json

sheets.spreadsheets.values.batchGet

GET

grr sheets spreadsheets values batchGet v4/spreadsheets/{spreadsheetId}/values:batchGet

Returns one or more ranges of values from a spreadsheet. The caller must specify the spreadsheet ID and one or more ranges.

Parameter Type Required Repeated Location Description Enum values
dateTimeRenderOption string — — query How dates, times, and durations should be represented in the output. This is ignored if value_render_option is FORMATTED_VALUE. The default dateTime render opti SERIAL_NUMBER · FORMATTED_STRING
majorDimension string — — query The major dimension that results should use. For example, if the spreadsheet data is: A1=1,B1=2,A2=3,B2=4, then requesting ranges=["A1:B2"],majorDimension=RO DIMENSION_UNSPECIFIED · ROWS · COLUMNS
ranges string — yes query The A1 notation or R1C1 notation of the range to retrieve values from. —
spreadsheetId string yes — path The ID of the spreadsheet to retrieve data from. —
valueRenderOption string — — query How values should be represented in the output. The default render option is ValueRenderOption.FORMATTED_VALUE. FORMATTED_VALUE · UNFORMATTED_VALUE · FORMULA
https://www.googleapis.com/auth/spreadsheets.readonly least privilege
5 scopes
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/drive.readonly
  • https://www.googleapis.com/auth/spreadsheets
  • https://www.googleapis.com/auth/spreadsheets.readonly
grr sheets spreadsheets values batchGet 
grr sheets spreadsheets values batchGet --spreadsheet-id <spreadsheet-id>

sheets.spreadsheets.values.batchGetByDataFilter

POST

grr sheets spreadsheets values batchGetByDataFilter v4/spreadsheets/{spreadsheetId}/values:batchGetByDataFilter

Returns one or more ranges of values that match the specified data filters. For more information, see Read, write, and search metadata. The caller must specify the spreadsheet ID and one or more DataFilters. Ranges that match any of the data filters in the request will be returned.

Parameter Type Required Repeated Location Description Enum values
spreadsheetId string yes — path The ID of the spreadsheet to retrieve data from. —
https://www.googleapis.com/auth/spreadsheets least privilege
3 scopes
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/spreadsheets
grr sheets spreadsheets values batchGetByDataFilter 
grr sheets spreadsheets values batchGetByDataFilter --spreadsheet-id <spreadsheet-id> --body-file ./body.json

sheets.spreadsheets.values.batchUpdate

POST

grr sheets spreadsheets values batchUpdate v4/spreadsheets/{spreadsheetId}/values:batchUpdate

Sets values in one or more ranges of a spreadsheet. The caller must specify the spreadsheet ID, a valueInputOption, and one or more ValueRanges.

Parameter Type Required Repeated Location Description Enum values
spreadsheetId string yes — path The ID of the spreadsheet to update. —
https://www.googleapis.com/auth/spreadsheets least privilege
3 scopes
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/spreadsheets
grr sheets spreadsheets values batchUpdate 
grr sheets spreadsheets values batchUpdate --spreadsheet-id <spreadsheet-id> --body-file ./body.json

sheets.spreadsheets.values.batchUpdateByDataFilter

POST

grr sheets spreadsheets values batchUpdateByDataFilter v4/spreadsheets/{spreadsheetId}/values:batchUpdateByDataFilter

Sets values in one or more ranges of a spreadsheet. For more information, see Read, write, and search metadata. The caller must specify the spreadsheet ID, a valueInputOption, and one or more DataFilterValueRanges.

Parameter Type Required Repeated Location Description Enum values
spreadsheetId string yes — path The ID of the spreadsheet to update. —
https://www.googleapis.com/auth/spreadsheets least privilege
3 scopes
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/spreadsheets
grr sheets spreadsheets values batchUpdateByDataFilter 
grr sheets spreadsheets values batchUpdateByDataFilter --spreadsheet-id <spreadsheet-id> --body-file ./body.json

sheets.spreadsheets.values.clear

POST

grr sheets spreadsheets values clear v4/spreadsheets/{spreadsheetId}/values/{range}:clear

Clears values from a spreadsheet. The caller must specify the spreadsheet ID and range. Only values are cleared -- all other properties of the cell (such as formatting, data validation, etc..) are kept.

Parameter Type Required Repeated Location Description Enum values
range string yes — path The A1 notation or R1C1 notation of the values to clear. —
spreadsheetId string yes — path The ID of the spreadsheet to update. —
https://www.googleapis.com/auth/spreadsheets least privilege
3 scopes
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/spreadsheets
grr sheets spreadsheets values clear 
grr sheets spreadsheets values clear --range <range> --spreadsheet-id <spreadsheet-id> --body-file ./body.json

sheets.spreadsheets.values.get

GET

grr sheets spreadsheets values get v4/spreadsheets/{spreadsheetId}/values/{range}

Returns a range of values from a spreadsheet. The caller must specify the spreadsheet ID and a range.

Parameter Type Required Repeated Location Description Enum values
dateTimeRenderOption string — — query How dates, times, and durations should be represented in the output. This is ignored if value_render_option is FORMATTED_VALUE. The default dateTime render opti SERIAL_NUMBER · FORMATTED_STRING
majorDimension string — — query The major dimension that results should use. For example, if the spreadsheet data in Sheet1 is: A1=1,B1=2,A2=3,B2=4, then requesting range=Sheet1!A1:B2?major DIMENSION_UNSPECIFIED · ROWS · COLUMNS
range string yes — path The A1 notation or R1C1 notation of the range to retrieve values from. —
spreadsheetId string yes — path The ID of the spreadsheet to retrieve data from. —
valueRenderOption string — — query How values should be represented in the output. The default render option is FORMATTED_VALUE. FORMATTED_VALUE · UNFORMATTED_VALUE · FORMULA
https://www.googleapis.com/auth/spreadsheets.readonly least privilege
5 scopes
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/drive.readonly
  • https://www.googleapis.com/auth/spreadsheets
  • https://www.googleapis.com/auth/spreadsheets.readonly
grr sheets spreadsheets values get 
grr sheets spreadsheets values get --range <range> --spreadsheet-id <spreadsheet-id>

sheets.spreadsheets.values.update

PUT

grr sheets spreadsheets values update v4/spreadsheets/{spreadsheetId}/values/{range}

Sets values in a range of a spreadsheet. The caller must specify the spreadsheet ID, range, and a valueInputOption.

Parameter Type Required Repeated Location Description Enum values
includeValuesInResponse boolean — — query Determines if the update response should include the values of the cells that were updated. By default, responses do not include the updated values. If the rang —
range string yes — path The A1 notation of the values to update. —
responseDateTimeRenderOption string — — query Determines how dates, times, and durations in the response should be rendered. This is ignored if response_value_render_option is FORMATTED_VALUE. The default d SERIAL_NUMBER · FORMATTED_STRING
responseValueRenderOption string — — query Determines how values in the response should be rendered. The default render option is FORMATTED_VALUE. FORMATTED_VALUE · UNFORMATTED_VALUE · FORMULA
spreadsheetId string yes — path The ID of the spreadsheet to update. —
valueInputOption string — — query How the input data should be interpreted. INPUT_VALUE_OPTION_UNSPECIFIED · RAW · USER_ENTERED
https://www.googleapis.com/auth/spreadsheets least privilege
3 scopes
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/spreadsheets
grr sheets spreadsheets values update 
grr sheets spreadsheets values update --range <range> --spreadsheet-id <spreadsheet-id> --body-file ./body.json