Reddit Ads¶

Reddit Ads is a platform that allows businesses and marketers to create, manage, and analyze advertising campaigns on Reddit.

omniload supports Reddit Ads as a source.

URI format¶

The URI format for Reddit Ads as a source is as follows:

redditads://?access_token=<access_token>&account_ids=<account_ids>

URI parameters:¶

access_token(required): The OAuth2 access token used for authentication with the Reddit Ads API. This token grants access to the advertising data associated with your Reddit Ads accounts.
account_ids(required): A comma-separated list of Ad Account IDs specifying the Reddit Ad Accounts for which you want to retrieve data. These IDs uniquely identify the Reddit Ad Accounts associated with your business.

Reddit Ads requires an access_token and account_ids to retrieve data from the Reddit Ads API v3. Please follow these steps to obtain the access_token and account_ids.

Create a Reddit developer application to obtain an access token¶

Go to Reddit App Preferences and log in with your Reddit account.
Click “create another app…” at the bottom of the page.
Fill out the form:
- Name: Your application name
- Type: Select “web app”
- Redirect URI: A valid redirect URI for your OAuth flow (e.g., http://localhost:8080/callback)
Click “create app” and note your client_id (shown under the app name) and client_secret.

Authorize your app and obtain access token¶

Direct the user to the Reddit authorization URL:

https://www.reddit.com/api/v1/authorize?client_id=<client_id>&response_type=code&state=<random_string>&redirect_uri=<redirect_uri>&duration=permanent&scope=adsread

After authorization, Reddit redirects to your redirect URI with a code parameter.
Exchange the code for an access token:
```
POST https://www.reddit.com/api/v1/access_token
```
Use HTTP Basic Auth with client_id:client_secret and include grant_type=authorization_code, code=<code>, and redirect_uri=<redirect_uri> in the request body.
The response includes an access_token and a refresh_token.

[!NOTE] Access tokens expire after approximately 1 hour. Use the refresh_token with grant_type=refresh_token to obtain a new access token when needed.

To find the Ad Account IDs, go to the Reddit Ads Dashboard and navigate to your account settings. The account ID is displayed in the URL or account details.

Tables¶

Reddit Ads source allows ingesting the following sources into separate tables:

Table	PK	Inc Key	Inc Strategy	Details
accounts	id	-	replace	Retrieves all ad accounts accessible by the authenticated user.
campaigns	id	-	replace	Retrieves campaigns for each ad account.
ad_groups	id	-	replace	Retrieves ad groups for each ad account.
ads	id	-	replace	Retrieves ads for each ad account.
posts	id	-	replace	Retrieves ad posts (creatives) for each ad account.
custom_audiences	id	-	replace	Retrieves custom audiences for targeting.
saved_audiences	id	-	replace	Retrieves saved audience configurations.
pixels	id	-	replace	Retrieves conversion tracking pixels.
funding_instruments	id	-	replace	Retrieves funding instruments (payment methods) for each ad account.
custom	[level_id, breakdowns]	date	merge	Custom reports allow you to retrieve performance data based on specific levels, breakdowns, and metrics.

Use these as --source-table parameter in the omniload ingest command.

Example¶

Retrieve all campaigns:

omniload ingest \
    --source-uri "redditads://?access_token=token_123&account_ids=id_123,id_456" \
    --source-table 'campaigns' \
    --dest-uri 'duckdb:///reddit.duckdb' \
    --dest-table 'dest.campaigns'

Retrieve all ad groups:

omniload ingest \
    --source-uri "redditads://?access_token=token_123&account_ids=id_123" \
    --source-table 'ad_groups' \
    --dest-uri 'duckdb:///reddit.duckdb' \
    --dest-table 'dest.ad_groups'

Custom Reports¶

The custom table uses the Reddit Ads Reports API to pull advertising performance reports. This allows you to retrieve metrics like impressions, clicks, and spend broken down by dimensions such as date, country, or community.

Format:

custom:<level>,<breakdowns>:<metrics>

Parameters:

level(required): The first element specifies the reporting level. Must be one of: account, campaign, ad_group, ad.
breakdowns(optional): Comma-separated list of breakdowns after the level. Valid breakdowns: date, country, region, community, placement, device_os, gender, interest, keyword, carousel_card. Maximum 2 breakdowns per report.
metrics(required): A comma-separated list of metrics to retrieve. Common metrics include: impressions, reach, clicks, spend, ecpm, ctr, cpc, and various video and conversion metrics.

[!NOTE] By default, omniload fetches data from January 1, 2020 to today’s date. You can specify a custom date range using the --interval-start and --interval-end parameters.

[!NOTE] Monetary metrics (spend, ecpm, cpc) are automatically converted from microcurrency to standard currency values.

Custom Reports Examples¶

Retrieve daily campaign performance data:

omniload ingest \
    --source-uri "redditads://?access_token=token_123&account_ids=id_123,id_456" \
    --source-table 'custom:campaign,date:impressions,clicks,spend' \
    --dest-uri 'duckdb:///reddit.duckdb' \
    --dest-table 'dest.campaign_daily'

The applied parameters for the report are:

level: CAMPAIGN
breakdowns: date
metrics: IMPRESSIONS, CLICKS, SPEND

Retrieve ad group performance by country for a specific date range:

omniload ingest \
    --source-uri "redditads://?access_token=token_123&account_ids=id_123" \
    --source-table 'custom:ad_group,date,country:impressions,reach,ctr' \
    --dest-uri 'duckdb:///reddit.duckdb' \
    --dest-table 'dest.ad_group_country' \
    --interval-start '2024-10-15' \
    --interval-end '2024-12-31'

The applied parameters for the report are:

level: AD_GROUP
breakdowns: date, country
metrics: IMPRESSIONS, REACH, CTR

Retrieve account-level spend data:

omniload ingest \
    --source-uri "redditads://?access_token=token_123&account_ids=id_123,id_456" \
    --source-table 'custom:account,date:spend,impressions' \
    --dest-uri 'duckdb:///reddit.duckdb' \
    --dest-table 'dest.account_spend'

The applied parameters for the report are:

level: ACCOUNT
breakdowns: date
metrics: SPEND, IMPRESSIONS

This command will retrieve data and save it to the destination table in the DuckDB database.