Configuring Export Pipeline Destinations & Permissions

Before you can schedule exports, you need a Destination: a cloud storage bucket where Clarisights uploads your exported files. This article covers how to set up Amazon S3 and Google Cloud Storage destinations and which permissions Clarisights needs.

Note: Exports need read and write access to your bucket. If you already gave Clarisights access to a bucket for importing data, that access is usually read-only and is not enough for exports. Confirm which bucket the exports should go to.

Amazon S3

Configuration Fields

Authentication Options

Choose one of the following:

Option A: Grant access to the Clarisights role (no credentials to share)

• Add a bucket policy that lets the Clarisights role arn:aws:iam::747179778889:role/ClarisightsExternalAccessRole read from and write to your bucket. Leave Role ARN and access keys empty.

Option B: Cross-Account IAM Role (Recommended)

• Role ARN: The ARN of an IAM role in your AWS account that Clarisights can assume (e.g., arn:aws:iam::123456789012:role/ClarisightsExportRole)

• External ID (optional): An external ID for additional security when assuming the role

Option C: Direct Credentials

• Access Key ID and Secret Access Key for an IAM user with read and write permissions to the bucket

Required S3 Permissions

Whichever option you choose, the Clarisights role, your IAM role, or your IAM user must have the following permissions on the target bucket:

s3:PutObject
s3:PutObjectAcl
s3:GetObject
s3:ListBucket

Clarisights uploads every file with the bucket-owner-full-control ACL, so that your account owns the files. This is why s3:PutObjectAcl is needed. It also works on buckets where ACLs are disabled (Object Ownership set to "Bucket owner enforced").

Read access (s3:GetObject and s3:ListBucket) lets our team confirm that your files arrived and investigate if an export goes wrong. Note that s3:ListBucket applies to the bucket itself (arn:aws:s3:::YOUR_BUCKET), while the other permissions apply to the objects in it (arn:aws:s3:::YOUR_BUCKET/*).

Example bucket policy for Option A:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::747179778889:role/ClarisightsExternalAccessRole"
      },
      "Action": ["s3:PutObject", "s3:PutObjectAcl", "s3:GetObject"],
      "Resource": "arn:aws:s3:::YOUR_BUCKET/*"
    },
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::747179778889:role/ClarisightsExternalAccessRole"
      },
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::YOUR_BUCKET"
    }
  ]
}

Example trust policy for Option B (attach it to your IAM role so that Clarisights can assume it):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::747179778889:role/ClarisightsExternalAccessRole"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": { "sts:ExternalId": "YOUR_EXTERNAL_ID" }
      }
    }
  ]
}

Leave out the Condition block if you don't use an External ID. Then give the role itself a permissions policy that allows s3:PutObject, s3:PutObjectAcl and s3:GetObject on arn:aws:s3:::YOUR_BUCKET/*, and s3:ListBucket on arn:aws:s3:::YOUR_BUCKET.

Google Cloud Storage

Configuration Fields

Required GCS Permissions

Option A: Grant access to the Clarisights service account

Grant the following permissions to the Clarisights service account 101712083634-compute@developer.gserviceaccount.com on the target bucket:

storage.objects.create
storage.objects.get
storage.objects.list

The simplest way is to assign the Storage Object Creator and Storage Object Viewer roles to the Clarisights service account on your bucket. Read access lets our team confirm that your files arrived and investigate if an export goes wrong.

Option B: Let Clarisights impersonate your own service account

1. Give a service account in your project the Storage Object Creator and Storage Object Viewer roles on the bucket.

2. Grant the Clarisights service account the Service Account Token Creator role on that service account.

3. Share the service account's email with us as the destination's Service Account.

If your file name template writes the same file name on every run (so that each run replaces the previous file), the account also needs storage.objects.delete, for example through the Storage Object User role. The default template creates a new file name on every run, so this is not needed by default.

File Structure in Your Bucket

With the default file name template, exported files are organized as follows:

{path_prefix}/{pipeline_name}/v{manifest_version}/{extract_id}/{epoch_time}_{export_start_date}_{export_end_date}.csv.gz
{path_prefix}/{pipeline_name}/v{manifest_version}/{extract_id}/{epoch_time}_{export_start_date}_{export_end_date}.meta.json

Each export produces two files per extract:

• Data file (.csv.gz, or .csv without compression): The exported data in CSV format, with a header row

• Metadata file (.meta.json): Contains column mapping, date range, and compression info

Metadata File Structure

{
  "pipeline_name": "my_pipeline",
  "extract_id": "core_metrics",
  "date_range": {
    "start_date": "2026-04-10",
    "end_date": "2026-04-17"
  },
  "compression": "gzip",
  "column_mapping": [
    { "column_name": "Campaign", "ui_name": "Campaign" },
    { "column_name": "fb_impressions", "ui_name": "FB: Impressions" },
    { "column_name": "_extracted_at", "ui_name": null, "generated": true }
  ]
}

Dimension columns use the dimension's name as shown in Clarisights. Metric columns use the metric's key, and ui_name gives its name as shown in Clarisights. The _extracted_at column is added by the export and marked as generated.

Each extract is always delivered as a single file, however many rows it has. Files are not split into parts.

Managing Destinations

• Destination names must be unique within your company

• A destination cannot be deleted while any schedule uses it, including paused schedules and schedules deleted in the last 30 days

• You can update destination credentials at any time without affecting existing schedules

Common Mistakes

• Read-only access: Read and list permissions alone are not enough. Exports also need s3:PutObject and s3:PutObjectAcl (S3) or storage.objects.create (GCS).

• Wrong role ARN: The format must be arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME. Check for typos and the right account ID.

• A bucket policy that denies access: Even when the IAM role is correct, a restrictive bucket policy can block uploads. Check bucket-level policies too.

• Encrypted buckets: If your S3 bucket uses your own KMS key for default encryption, the role or user also needs permission to use that key (kms:GenerateDataKey to write files and kms:Decrypt to read them).

If an export still fails, see Troubleshooting Export Failures, or reach out from the in-app messenger.