Configuring Export Pipeline Destinations & Permissions

A destination is the cloud storage location where Clarisights writes your export files: an Amazon S3 bucket, a Google Cloud Storage bucket or an Azure Blob Storage container, with the access details Clarisights uses to sign in. Destinations belong to your workspace, so any pipeline can reuse them. Users with the Admin or Data Manager role can manage them.

Setting one up takes two parts: first grant Clarisights access on your side, then add the destination in Clarisights and test the connection.

Note: exports need read, write and overwrite access to the bucket. If you already gave Clarisights read-only access to a bucket for importing data, that isn't enough for exports.

Grant Clarisights access

Pick the authentication method you will choose in the destination form, and grant the access listed for it.

Provider	Authentication	What you grant
Amazon S3	Clarisights role (default)	A bucket policy that lets the Clarisights role read and write
Amazon S3	IAM role	A role in your account that Clarisights can assume, with read and write permissions on the bucket
Amazon S3	Access key	An IAM user with read and write permissions on the bucket, and its access key
Google Cloud Storage	Clarisights service account (default)	A role on the bucket for the Clarisights service account
Google Cloud Storage	Impersonation	A role on the bucket for your own service account, and the Service Account Token Creator role on it for Clarisights
Google Cloud Storage	JSON key	A role on the bucket for your own service account, and a key for it
Azure Blob Storage	Account key (the only option)	The storage account's access key, with account key access allowed

Amazon S3

Whichever method you choose, the identity Clarisights writes as needs these permissions:

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

• s3:ListBucket applies to the bucket itself (arn:aws:s3:::YOUR_BUCKET). The others apply to the objects in it (arn:aws:s3:::YOUR_BUCKET/*). Don't limit s3:ListBucket with a condition such as s3:prefix.

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

• Read access lets the connection test confirm access to the bucket.

Clarisights role (default). Add a bucket policy that lets the Clarisights role arn:aws:iam::747179778889:role/ClarisightsExternalAccessRole read from and write to your bucket:

{
  "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"
    }
  ]
}

IAM role. Create a role in the same AWS account as the bucket and let Clarisights assume it:

1. Choose an External ID yourself, for example a random string. Clarisights doesn't generate one, and it is optional, but we recommend it.

2. Attach this trust policy to the role:

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

3. Give the role 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.

4. In the destination form, enter the role's ARN in Role ARN and the same value in External ID. If you don't use an External ID, leave out the Condition block and leave the field empty.

Access key. Create an IAM user in the same AWS account as the bucket, give it the permissions above, and create an access key for it. Root user keys aren't supported.

Encrypted buckets. If the bucket encrypts by default with your own KMS key, the key policy must also allow the identity Clarisights writes as to use kms:GenerateDataKey.

Google Cloud Storage

The identity Clarisights writes as needs these permissions, granted on the bucket itself (a grant limited to a folder can't be tested):

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

The simplest way is the Storage Object User role on the bucket. storage.objects.delete is what lets Clarisights overwrite a file, and the connection test checks it.

• Clarisights service account (default): grant the role on your bucket to 101712083634-compute@developer.gserviceaccount.com.

• Impersonation: grant the role on your bucket to a service account in your own project. Then grant the Clarisights service account 101712083634-compute@developer.gserviceaccount.com the Service Account Token Creator role on that service account. No key leaves your project.

• JSON key: grant the role on your bucket to a service account in your own project, and create a JSON key for it. Paste the whole key file into the form.

Azure Blob Storage

• Clarisights signs in with the storage account name and one of its access keys. Shared access signatures (SAS) and Microsoft Entra ID sign-in aren't supported.

• In the storage account's settings, Allow storage account key access must be turned on.

• If the storage account limits network access, its firewall rules must allow Clarisights. For the details, click ? at the bottom right of Clarisights and choose Send us a message, or email support@clarisights.com.

• The form also asks you to grant the Storage Blob Data Contributor role on the container. An account key already has full access to its storage account, so this matters only if your organization manages container access with Azure roles.

Adding a destination

You can add a destination in two places:

• On the Export pipelines page, open the Destinations tab and click Add destination.

• While creating or editing a schedule, open the Destination list and choose + Create new destination…. The new destination is then selected for the schedule.

1. Enter a Name, unique in your workspace, for example prod-reports-s3.

2. Choose the Storage provider. It can't be changed after the destination is created.

3. For Amazon S3 and Google Cloud Storage, choose the Authentication method and fill in its fields (see the tables below).

4. Enter the bucket or container name, and optionally a Path prefix: the folder your files go under. Leave it blank for the root. Target path shows the result.

5. Click Test connection (see Testing the connection).

6. Click Save destination. Saving runs the test too.

Amazon S3 fields

Field	Required	What to enter
Authentication	Yes	Clarisights role (default), IAM role or Access key
Role ARN	For IAM role	Your role's ARN, for example arn:aws:iam::123456789012:role/cs-export
External ID	No	The External ID in your role's trust policy, if you set one
Access key ID and Secret access key	For Access key	The IAM user's access key pair
Bucket name	Yes	The bucket name only, for example acme-exports: not its ARN, and no folders (put those in Path prefix)
Region	Yes	The bucket's region code, for example eu-central-1
Path prefix	No	A folder in the bucket, for example reports/

Google Cloud Storage fields

Google Cloud Storage destinations have no region field.

Field	Required	What to enter
Authentication	Yes	Clarisights service account (default), Impersonation or JSON key
Service account	For Impersonation	The email of your service account, for example export-loader@acme-eu.iam.gserviceaccount.com
JSON key	For JSON key	The whole service account key file
Project ID	No	For JSON key. Leave it blank to use the project in the key.
Bucket name	Yes	The bucket name only
Path prefix	No	A folder in the bucket

Azure Blob Storage fields

Field	Required	What to enter
Storage account name	Yes	3 to 24 lowercase letters or numbers, for example acmeanalytics
Account key	Yes	One of the storage account's access keys
Container name	Yes	3 to 63 lowercase letters, numbers or hyphens, starting and ending with a letter or number
Path prefix	No	A folder in the container

Testing the connection

Test connection checks that Clarisights can read, write and overwrite files in the bucket or container. It writes nothing there, and it can take up to 25 seconds. When it passes, you see "Connection works" with the access it confirmed.

• Google Cloud Storage: Clarisights asks Google which permissions the identity has on the bucket.

• Azure Blob Storage: Clarisights lists the container with the account key. An account key can do anything in its storage account, so a successful read also confirms write. The test can't see immutability policies or legal holds on the container.

• Amazon S3: Clarisights checks read access directly. S3 has no way to test a write without writing, so the test asks for one more step.

Confirming write access on Amazon S3

After the read check passes, the form shows One more step to confirm write access with a command to run.

1. Click Copy next to the command.

2. Run it with the AWS CLI as an administrator of the AWS account that owns the bucket. AWS CloudShell in that account works well. The command only reads settings: the bucket policy, encryption and ownership settings, the KMS key policy and, for an IAM role or access key, what IAM allows.

3. Paste the whole output into Command output and click Verify.

• The output must be from the last 24 hours and for exactly these details. If you change the bucket, prefix, region or credentials, test again and run the new command.

• For an IAM role or access key, the role or IAM user must be in the same AWS account as the bucket.

• Buckets with Requester Pays turned on aren't supported. Writes through an access point ARN can't be checked: use the bucket's own name.

If the test doesn't pass

You can still click Save anyway, but exports to this destination will fail until access is fixed. Fix the access on your side, then open the destination with Manage and test again.

Test connection messages

Message	What to do
Access denied	Grant the permissions listed in Grant Clarisights access, on the bucket itself. The details under the title name what is missing. For Azure, check that account key access is allowed and that the storage account's firewall rules allow Clarisights.
Sign-in failed	Check the access key pair, the JSON key or the account key. Keys that were deleted or disabled are rejected.
Couldn't assume the role	Check the Role ARN, the External ID and the role's trust policy.
Impersonation failed	Grant the Clarisights service account the Service Account Token Creator role on your service account.
Bucket not found / Container not found	Check the bucket or container name, and for S3 the region.
Wrong region	Enter the region the bucket is in and test again.
Couldn't reach the provider	Check the bucket and storage account names, then try again.
Provider error	Try again in a few minutes.
The check timed out	Try again.
Couldn't complete the check	The problem is on our side. Try again later, or contact us if it continues.
Too many checks	Wait for the countdown, then test again.
Some details need fixing	Fix the highlighted fields and test again.
That output can't be used	Paste the whole output of the command. If it is more than a day old, run the command again.
The output doesn't match these details	Run the new command shown and paste its output.
Write can't be checked for access points	Enter the bucket's name instead of an access point ARN.
Root user keys aren't supported	Use an IAM user's access key or an IAM role.
This is a Clarisights bucket, role or service account, or These are Clarisights credentials	Use a bucket, role, service account or key from your own account. The Clarisights role and service account are chosen with the default Authentication option.

How secrets are handled

• The Secret access key, JSON key and Account key are never shown again after you save. The destination card shows them as Saved.

• To change one, open the destination with Manage and click Replace. The current value stays in use until you save.

• If you change the Access key ID or the Storage account name, you must enter the matching secret again.

Editing and deleting destinations

• Click Manage on a destination card to edit it. You can change everything except the storage provider. Changes apply to every schedule that uses the destination.

• Each card shows how many active schedules use the destination.

• To delete a destination, click Delete in the Manage window. It is only possible when no active schedule uses it: pause or delete those schedules, or move them to another destination, first.

• Paused schedules that still point to a deleted destination must pick a new destination before they can resume. Clarisights asks for one when you click Resume.

• Files already in the bucket stay where they are. The name of a deleted destination can be used again.

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 run writes two files per extract, for every version that is still exporting:

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

• Metadata file (.meta.json): the date range, the compression, the row count and the column mapping.

For 30 days after you publish a new version, the previous version keeps exporting too. The default template puts each version in its own v1, v2 folder. To change the layout, edit the schedule's file name template: see Managing Export Schedules.

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",
  "rows_count": 1250,
  "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 holds the time of the export and is marked as generated.

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

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 and storage.objects.delete (Google Cloud Storage).

• A folder in the bucket name: enter only the bucket name and put folders in Path prefix.

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

• A role or IAM user in another AWS account: it must be in the same account as the bucket.

• 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, the key policy must allow kms:GenerateDataKey for the identity Clarisights writes as.

• Azure account key access turned off: turn on Allow storage account key access in the storage account's settings.

• Saving without a passing test: a destination saved with Save anyway fails at its first run. Test again after fixing access.

If an export still fails, see Troubleshooting Export Failures, or click ? at the bottom right of Clarisights and choose Send us a message.