Skip to main content
The Google Cloud Storage destination sends every import to a bucket in your own Google Cloud Storage as a single file, in CSV or JSON format. Each import produces one file in your bucket. Importing again with the same file name replaces the earlier file.

​
Before you start

You need:
  • A Google Cloud project with a Cloud Storage bucket.
  • A service account in that project, with a JSON key file.
  • The service account allowed to write to the bucket (see Permissions).

​
Create the service account and key

1

Create or pick a service account

In the Google Cloud console, open IAM & Admin > Service Accounts and create a service account (or pick an existing one).
2

Download a JSON key

Open the service account, go to Keys > Add key > Create new key, choose JSON and download the file.
Keep the file safe. It gives access to your bucket.

​
Permissions

Open your bucket in the console, go to Permissions, and grant the service account one of these roles on the bucket: The service account does not need access to anything else in your project.

​
Set up the destination

1

Select Google Cloud Storage as the destination

Open your importer, go to the Destination tab and choose Google Cloud Storage.
2

Add the key file

For JSON Key File, choose the key file you downloaded.
3

Set the bucket and path

Enter the Bucket Name: the bucket name only, for example my-bucket. Do not include gs://.Optionally, enter a Path: a folder inside the bucket, for example imports/2026. Folders are created automatically.
4

Set the file name and data type

Optionally, enter a File Name: the name of the file, without the extension. See File names.Then choose the Data Type: CSV or JSON.
5

Test the connection

Click Test Connection, then Save.
Test Connection checks the key, finds the bucket and confirms the service account can write to it. Nothing is stored until Google accepts the key.
When the destination is connected, the key file and its service account email are shown and the bucket, path and data type are locked. To change them, click Disconnect and set the destination up again. Disconnecting deletes the stored key.
If Google rejects a key, it is discarded and the file picker comes back so you can choose another file.

​
File names

The file is saved as <path>/<file name>.<csv or json>. The extension is added for you, and never doubled: report.csv in the File Name field still produces report.csv. The name is chosen in this order:
  1. A file name passed with the import itself, if there is one.
  2. The File Name setting on the destination.
  3. The default, <import id>_<user id>, for example 9368_default123.
The File Name setting accepts these placeholders: A name can be up to 200 characters and cannot contain slashes or line breaks. Use the Path field for folders. Leading and trailing spaces are removed, and control characters are stripped.

​
Replacing and keeping files

  • A fixed name (for example customers) means every import replaces the previous file. Use it when you always want the latest data in one place.
  • A name with {IMPORT_ID} or {UNIQUE_ID} means every import creates a new file. Use it to keep a history.
If the service account has only the Storage Object Creator role, a repeated name fails with a permission error. The destination shows a warning when it detects this.

​
What is written to the bucket

CSV
  • UTF-8 with a byte order mark, so Excel opens it correctly.
  • The first row holds the column headers; the remaining rows hold the data.
  • Content type text/csv.
JSON
  • A single JSON array with one object per row, keyed by column name.
  • Content type application/json.
Each file also carries your CSVBox user ID as custom metadata (user_id).

​
File size and large imports

  • An import is written as one file, no matter how many rows it has.
  • Large files are supported. A test import of 1,000,000 rows (about 146 MB as CSV) completed and stored as one file.
  • Google allows objects up to 5 TiB.
  • The number of rows imported is still limited by your CSVBox plan.
Large imports take longer, because the whole file is sent when the import finishes. Wait for the import to show as complete.

​
Troubleshooting

Failed imports show a message on the import. The common ones: If the destination is disconnected, imports to it fail instead of writing with an old key.

​
Frequently asked questions

Each importer has one Google Cloud Storage destination. Create another importer, or use a different destination, for a second bucket.
The key is stored encrypted. It is never sent back to your browser; only its file name and the service account email are shown. Disconnecting deletes it.
Yes. Choose the key file in each importer.