> ## Documentation Index
> Fetch the complete documentation index at: https://support.detrics.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Persistence

> Store permanent copies of ad creative images from platforms with expiring URLs

<Info>**Last updated:** March 18, 2026</Info>

## The Problem with Ephemeral URLs

Some marketing platforms return **temporary URLs** for images and creative assets. Meta Ads, TikTok, and Instagram generate CDN-signed URLs that typically expire within 24 hours. This means:

* Image URLs in your BigQuery data stop working after a day
* If you use these URLs in dashboards or reports, the images break
* Every API call returns a new URL for the same image, even if the content hasn't changed

## How Image Persistence Works

Image Persistence is an optional feature that gives you **permanent URLs** for ad creative images.

When enabled on a destination:

1. After a transfer sync completes, Detrics identifies all image URL fields in the synced data
2. Each image is downloaded from the platform's CDN
3. The image is compressed to an optimized WebP format (approximately 400px wide, \~14KB per image)
4. A content hash is computed, if the same image already exists in your bucket, it's not re-uploaded
5. The image is uploaded to a Google Cloud Storage (GCS) bucket in your project
6. The temporary URL in your BigQuery table is replaced with a permanent `https://storage.googleapis.com/...` URL

### What Gets Processed

Currently, image persistence supports these fields from **Meta Ads**:

* `ad_image_url`: The ad's main creative image
* `ad_image`: Image references embedded in creative data

Support for additional platforms (TikTok, Instagram) is planned.

## Enabling Image Persistence

1. Go to [**Data Warehouse → Destinations**](https://app.detrics.io/data-warehouse/destinations)
2. Open the destination where you want to enable image persistence
3. Click **Enable Image Bucket**
4. Detrics will create a GCS bucket in your project named `detrics-images-{workspace-id}`
5. Grant the Detrics service account **Storage Object Admin** role on the bucket (or project-wide)

<Note>
  The Detrics service account needs the **Storage Object Admin** IAM role to upload images to GCS. This is in addition to the BigQuery roles already granted.
</Note>

<Note>
  The steps above describe the **Standard Setup**. Under **[Least-Privilege Access](/bigquery/least-privilege-access)** you pre-create the bucket yourself and grant a narrower **Storage Object User** role scoped to that bucket, see that guide for the exact steps.
</Note>

## Storage Costs

Image persistence is designed to be cost-effective:

* Images are compressed to WebP format (\~14KB per image)
* Content-based deduplication means the same image is stored only once, even if it appears in multiple rows or across accounts
* Typical monthly cost for a large account: under \$1/month for storage

## How It Affects Deduplication

Image URL fields are marked as **ephemeral** in Detrics. This means:

* URL changes don't affect the `_detrics_row_id` hash
* When a platform returns a new temporary URL for the same image, Detrics doesn't count it as a row change
* This prevents unnecessary row updates in Incremental sync mode

This behavior applies regardless of whether Image Persistence is enabled. Image Persistence adds the permanent URL replacement on top of the dedup exclusion.

## Disabling Image Persistence

You can disable Image Persistence on a destination at any time. Existing images in the GCS bucket are preserved, and their URLs in BigQuery continue to work. New syncs will write the platform's ephemeral URLs instead of permanent ones.