# Google Sheets

> Read and write Google Sheets via OAuth.

Lets an agent list, create, and edit spreadsheets in a Google Drive
account you connect.

## What it can do

| Method | What it does |
| --- | --- |
| `list_spreadsheets` | List Google Sheets in Drive; name_contains optional, page_token for next page. |
| `create_spreadsheet` | Create a new spreadsheet; returns spreadsheet_id and URL. |
| `add_sheet` | Add a new tab to a spreadsheet by spreadsheet_id. |
| `list_sheets` | List tabs in a spreadsheet: sheet_id, title, index, grid size. |
| `get_values` | Read cell values by A1 range. |
| `update_values` | Write values to a range (overwrites the target cells). |

## Write a whole file into a sheet

`update_values` takes small data inline as `values`, or a CSV, TSV, JSONL or
JSON file as `dataset_input`: the whole file is written to the range in one
request (in chunks of 50 rows).

```json
{
  "spreadsheet_id": "1AbC...",
  "range": "Sheet1!A1",
  "dataset_input": {"source": {"agent_file_id": 1234}}
}
```

`format` is `auto` by default (read from the file); set `csv`, `tsv`, `jsonl` or
`json` when the file name does not say.

- **In an agent run** the agent passes the `agent_file_id` of a file it can use
  in that run: a file it made, a file attached to the agent, or (for a lead) a
  file its subagents made. Nothing else is needed.
- **From the API** (`POST /api/v1/agents/custom-tools/call/` with `tool`,
  `action` and `arguments`), any file of your own account works by its
  `agent_file_id` alone: no `execution_id` is needed. Add `execution_id` only to
  run the call inside that run; it then sees that run's files.
- A file of another account is never found, whichever way you call.

## How to get credentials

Google OAuth - no token to copy.

1. Start the setup in FlyMyAI; enter the Google email you want to use.
2. On the Google consent screen, sign in with that account.
3. Approve the requested scopes (`spreadsheets`, `drive.readonly`).
4. You land back in FlyMyAI; the tool flips to **Configured**.

## Fields to fill in FlyMyAI

| FlyMyAI field | Where it comes from |
| --- | --- |
| `USER_GOOGLE_EMAIL` | The Google account whose Sheets the agent should access |

## Troubleshooting

- **`403` on a specific sheet** - the account doesn't have edit access.
  Share the sheet with that account, then retry.
- **Empty result from `list_spreadsheets`** - the filter didn't match. Try
  without `name_contains`.
- **File not found by `agent_file_id`** - the id must be a file of your own
  account; with `execution_id`, it must also be a file of that run (see above).

## Links

- [Google Sheets API](https://developers.google.com/sheets/api)
- [Revoke FlyMyAI access](https://myaccount.google.com/permissions)