Skip to main content

​
Overview

Upload data files manually through the Google Cloud Console when you need to test an import, perform a one-time data upload, or don’t have automated upload infrastructure in place. This guide walks through the GCS Console upload process.
Prerequisites:
  • A GCS import already created in Permutive
  • A Google account with access to the Permutive-managed bucket
  • Your bucket path (provided when the import was created)
  • Data files in the correct format (gzip compressed)

​
When to Use Manual Upload

Manual upload is ideal for:
  • Testing: Validate your data format before setting up automation
  • One-time imports: Upload a single partner file or backfill dataset
  • Small-scale operations: When upload frequency doesn’t justify automation
  • Troubleshooting: Isolate issues by uploading files directly
For regular, recurring uploads, consider programmatic upload instead.

​
File Format Requirements

Before uploading, ensure your files meet these requirements:
RequirementDetails
FormatTab-separated values (TSV)
Compressiongzip with .gz extension (NOT .gzip)
StructureUSER_ID<TAB>SEGMENT_CODES per line
Segment codesComma-separated, no spaces
Example file content (before compression): 
76E5F445-1993-4B13-A67A-76E5F4451993	0002,0007,0012
5E824DCF-2C6D-4A89-9B34-5E824DCF2C6D	0010,0011
A1B2C3D4-E5F6-7890-ABCD-EF1234567890	demo_25_34,intent_auto
Common format mistakes:
  • Using spaces instead of tabs as the delimiter
  • Using .gzip extension instead of .gz
  • Including spaces in segment codes
  • Using comma-separated values (CSV) instead of tab-separated

​
Upload Steps

1

Access Google Cloud Console

Navigate to Google Cloud Console and sign in with the Google account that has been granted access to the Permutive-managed bucket.
2

Navigate to Cloud Storage

In the Google Cloud Console, go to Cloud Storage > Buckets. You can also use the search bar to find “Cloud Storage”.
3

Find the Permutive Bucket

Locate the Permutive-managed bucket. The bucket name and path were provided when you created your import in the Permutive Dashboard.
If you don’t remember your bucket path, go to Connectivity > Imports in the Permutive Dashboard and view your import settings.
4

Navigate to Your Import Folder

Browse to the specific folder path for your import. Each import has a unique folder path within the bucket.
5

Upload Your File

Click Upload Files and select your gzip-compressed data file. The file should have a .gz extension.Alternatively, drag and drop the file directly into the browser window.
6

Verify the Upload

After upload completes:
  1. Confirm the file appears in the folder with the correct name and size
  2. Check that the file extension is .gz
  3. Note the upload timestamp
7

Check Processing Status

Return to the Permutive Dashboard and navigate to your import. The file will be processed automatically, typically within 15-30 minutes depending on file size.Monitor the import status to confirm successful processing.

​
Troubleshooting

Your Google account may not have access to the Permutive-managed bucket.Solution: Verify you are signed in with the correct Google account. If you need access granted, contact your Permutive representative or the admin who set up the import.
The file may have format issues or segment codes may not be in your taxonomy.Solution:
  1. Verify your taxonomy includes all segment codes in the file
  2. Check the file uses tabs (not spaces or commas) as delimiters
  3. Ensure the file is properly gzip compressed with .gz extension
  4. Verify user IDs match the format tracked by your Permutive SDK
You may not have the bucket name correct, or your account lacks list permissions.Solution: Check your import settings in the Permutive Dashboard for the exact bucket path. The bucket is managed by Permutive, so you need specific access granted to view it.
Large files or high system load can extend processing time.Solution: Files approaching the 10 million user ID limit may take longer to process. For very large files, processing may take up to a few hours. Contact Support if processing seems stuck.

​
Next Steps

Uploading Data Files Programmatically

Automate uploads with service account

Configuring Taxonomy

Define segment codes and metadata

Using Imports in Cohorts

Create cohorts with imported segments

Back to Imports

Return to Imports overview