Advanced Analytica Advanced Analytica: IBOM
← All connectors
Reddit Ads logo

Source connector

Reddit Ads

Set up Reddit Ads as a source and move its data into your chosen destination.

Version 1.0.5 certified generally available

Reddit Ads

The Reddit Ads source syncs data from the Reddit Ads API v3 for one ad account. This includes the account, campaigns, ads and ad groups. It also includes daily performance metrics for the account, campaigns, ads and ad groups.

Before you start

  • A Reddit Ads account with at least one ad account. You also need a Reddit user with access to the ad account you want to sync.
  • The Ad Account ID for the ad account you want to sync. It starts with a2_. See Find your ad account ID.
  • Credentials for the Authentication field, based on your chosen option:
    • Authenticate with Reddit: You don’t need to prepare anything. Sign in to Reddit from Airbyte, which obtains the refresh token for you.
    • Use your own Reddit app:
      • The OAuth Client ID and OAuth Client Secret for a Reddit developer app. Reddit displays these as the app ID and secret. This connector uses them as the client ID and client secret. Only business admins with a verified Reddit account can create a developer app. See Create a developer app.
      • An OAuth Refresh Token for that app, authorised with the adsread scope. See Get a refresh token.
  • Optional: a User Agent to send when the connector requests access tokens from Reddit. If empty, the connector sends an Airbyte user agent.

Set up the connector

Choose one of two Authentication options:

  • Authenticate with Reddit: Sign in to Reddit from Airbyte, which obtains the refresh token for you. This is the default option in Airbyte Cloud. You don’t need a developer app, so skip Create a developer app and Get a refresh token.
  • Use your own Reddit app: Enter the client ID, client secret and refresh token for a Reddit developer app you manage. Choose this option for self-managed Airbyte or an existing developer app. Complete Create a developer app and Get a refresh token first.

Sources created before version 0.2.0 automatically move to Use your own Reddit app. They keep their existing client ID, client secret and refresh token, so you don’t need to act.

Step 1: Set up Reddit Ads

Create a developer app

You only need a developer app for the Use your own Reddit app option.

  1. In Reddit Ads Manager, open your business’s Developer Applications page.
  2. Select Add Apps > Create an app. Then enter the app name, About URL, redirect URL and primary contact. Reddit requires a redirect URL, although the connector never uses it interactively. You can enter any URL you control, such as https://example.com/oauth/callback.
  3. Select Create App. Reddit displays the app ID and secret. Copy both values. The app ID is your OAuth Client ID, and the secret is your OAuth Client Secret.

If you already have a Reddit app under Preferences > Apps, select Add Apps > Migrate an existing app instead. Migrating restricts the app’s scope to the Ads API.

For more details, see Reddit’s Create a Developer Application guide.

Get a refresh token

You only need a refresh token for the Use your own Reddit app option. The connector authenticates through the OAuth refresh token grant, which requires a long-lived refresh token. Get one through the authorisation code flow in Reddit’s authentication guide.

  1. Sign in to Reddit as the user whose ads data you want to sync. Then open the following URL in a browser and replace the placeholders:

    https://www.reddit.com/api/v1/authorize?client_id=YOUR_APP_ID&response_type=code&state=airbyte&redirect_uri=YOUR_REDIRECT_URL&duration=permanent&scope=adsread

    Set duration to permanent. A temporary authorisation doesn’t return a refresh token, so the connector can’t sync. The connector only needs the adsread scope.

  2. Select Allow. Reddit redirects you to your redirect URL with a code query parameter. Copy the code and remove any trailing #_ characters. The code expires after 10 minutes and works once.

  3. Exchange the code for tokens:

    curl -X POST https://www.reddit.com/api/v1/access_token \
      -H 'content-type: application/x-www-form-urlencoded' \
      -A 'YOUR_USER_AGENT' \
      -u 'YOUR_APP_ID:YOUR_APP_SECRET' \
      -d 'grant_type=authorization_code&code=YOUR_CODE&redirect_uri=YOUR_REDIRECT_URL'
  4. Copy the refresh_token value from the response. This is your OAuth Refresh Token. The connector uses it to obtain access tokens, so you don’t need the access_token value.

Find your ad account ID

Sign in to Reddit Ads Manager. Your ad account ID appears in the top-right corner and starts with a2_.

You can also open Business Manager > Assets > Ad Accounts in Reddit Ads Manager. The ID appears below the ad account’s name and starts with a2_. Alternatively, call List Ad Accounts By Business with an access token for your app.

Step 2: Set up Reddit Ads in Airbyte

Except for Authentication, the source uses the same fields in Airbyte Cloud and Airbyte Open Source:

  • Ad Account ID: Required. Enter the ID from Find your ad account ID, such as a2_abc123.
  • User Agent: Optional. This is the user agent sent when the connector requests a new access token. The connector sends it to Reddit’s token endpoint, https://www.reddit.com/api/v1/access_token. Reddit recommends the format platform:app_id:version (by /u/username), for example airbyte:reddit-ads-sync:v1.0 (by /u/your-username). If empty, the connector sends airbyte:source-reddit-ads:v1. The connector doesn’t send this value with requests that read your ads data.
  • Start Date: Optional. Set the earliest data to sync in RFC 3339 format with a UTC offset, such as 2024-05-11T00:00:00Z. This setting applies to incremental streams. It sets the earliest modified_at for ad, ad_group and campaign. It also sets the earliest report date for the four report streams. If empty, these streams start 24 months before the current sync.
  • Number of Concurrent Workers: Optional. Set the number of parallel requests from 1 to 10. The default is 3. Higher values can accelerate syncs but increase the chance of Reddit rate limiting.
  • Report Lookback Window (Days): Optional. Set the whole days re-read before the last synced report date during each incremental sync. Choose from 0 to 30. The default is 7 days.

Airbyte Cloud

  1. In Airbyte Cloud, create a source and select Reddit Ads.
  2. Under Authentication, select Authenticate with Reddit, then select Authenticate your Reddit Ads account. Sign in to Reddit as a user with access to the ad account you want to sync. Then select Allow. To use your own developer app, select Use your own Reddit app instead. Then follow step 2 of For Airbyte Open Source.
  3. Enter the Ad Account ID.
  4. Optionally, set User Agent, Start Date, Number of Concurrent Workers and Report Lookback Window (Days).
  5. Select Set up source.

Airbyte Open Source

  1. In Airbyte, create a source and select Reddit Ads.
  2. Under Authentication, select Use your own Reddit app. Enter the OAuth Client ID and OAuth Client Secret from Create a developer app. Then enter the OAuth Refresh Token from Get a refresh token.
  3. Enter the Ad Account ID.
  4. Optionally, set User Agent, Start Date, Number of Concurrent Workers and Report Lookback Window (Days).
  5. Select Set up source.

Supported sync modes

The Reddit Ads source supports these sync modes:

ad_account only supports full refresh. The other seven streams support both full refresh and incremental sync.

Supported streams

StreamAPI endpointPrimary keyIncremental cursor
ad_accountGET /api/v3/ad_accounts/{ad_account_id}idNone
adGET /api/v3/ad_accounts/{ad_account_id}/adsidmodified_at
ad_groupGET /api/v3/ad_accounts/{ad_account_id}/ad_groupsidmodified_at
campaignGET /api/v3/ad_accounts/{ad_account_id}/campaignsidmodified_at
ad_account_reportPOST /api/v3/ad_accounts/{ad_account_id}/reportsaccount_id, datedate
campaign_reportPOST /api/v3/ad_accounts/{ad_account_id}/reportscampaign_id, datedate
ad_group_reportPOST /api/v3/ad_accounts/{ad_account_id}/reportsad_group_id, datedate
ad_reportPOST /api/v3/ad_accounts/{ad_account_id}/reportsad_id, datedate

All eight streams read from the single ad account you configure. To sync multiple ad accounts, create one source for each account.

campaign_report, ad_account_report, ad_group_report and ad_report return one row for each entity per UTC day. The entities are campaigns, accounts, ad groups and ads, respectively. Rows include delivery and conversion metrics, such as impressions, clicks, spend, reach and frequency. They also include per-objective conversion counts and values.

Performance

Reddit applies rate limits by Reddit app, authorised user and endpoint group. Sources using the same app and Reddit user share these limits. The connector calls endpoints in two groups:

Reddit rate limit groupEndpointsStreamsQuota
ads-campaign-management-readGet Ad Account, List Ads, List Ad Groups, List Campaignsad_account, ad, ad_group, campaign400 requests per 60 seconds
ads-reportingGet A Reportad_account_report, campaign_report, ad_group_report, ad_report60 requests per 60 seconds

The connector throttles its requests to stay within these quotas. It only counts its own requests. Other sources using the same app and Reddit user can still exceed the limit. Each report stream requests a continuous three-day UTC window per call. A long backfill therefore makes many report calls.

By default, the connector runs up to 3 parallel requests. You can change this with Number of Concurrent Workers, up to a maximum of 10. Lower this value if syncs often reach rate limits.

The connector retries 429 and 5xx responses up to 10 times with exponential backoff. See Reddit’s rate limiting documentation for all endpoint groups and quotas.

The connector reuses an access token until it expires, then refreshes it. If a request still fails with 401, the connector refreshes the token and retries the request. If Reddit returns a new refresh token, the connector saves it to the source configuration. You don’t need to rotate it yourself.

Limitations and troubleshooting

Sync behaviour and limitations

  • Report metrics use micro-units. Reddit multiplies spend, cpc, cpv, ecpm and the conversion_*_ecpa metrics by 1,000,000. It multiplies the conversion_*_total_value metrics by 100. The connector loads these values unchanged. Divide them in your destination before reporting currency amounts. Since version 1.0.0, spend and the conversion_*_total_value metrics are integers. Some warehouses truncate integer division, so cast these values to a decimal type before dividing.
  • Recent report data changes after it lands. Reddit says metrics can take up to 6 hours to stabilise. A daily refresh applies late conversions to earlier hours or days. Each incremental report-stream sync re-reads the last synced date and the configured Report Lookback Window (Days). Conversion metrics follow your ad account’s attribution window. To include late conversions from older days, increase the lookback to cover that window, up to 30 days. Use Incremental | Append + Deduped so re-read rows replace earlier rows. The current UTC day’s row remains partial until a sync runs after the day ends.
  • Report streams re-read days without data. A report stream saves its latest row’s date as its state. Without delivery after that date, each incremental sync requests every later day again. An account with no delivery history requests the full 24 months during every sync.
  • Refresh the source schema after upgrading to 1.0.0. Version 1.0.0 types the ad and campaign timestamps as date-times. It types the report date as a date in YYYY-MM-DD format. It also types 26 count and micro-currency report metrics, plus campaign.spend_cap, as integers. The version also adds start_time and end_time to campaign. Connections syncing only ad_account and ad_group don’t need any action. Only clear a stream if a sync fails after the schema refresh. Some destinations can’t change an existing column’s type, including S3 Data Lake and other Iceberg destinations. If this happens, back up the affected tables. Then clear only the streams named in the error and sync them again. See the Reddit Ads migration guide for full instructions and the risks of clearing report streams.
  • Refresh campaign_report after upgrading from a version earlier than 0.3.0. Earlier versions requested report windows with gaps. Any sync covering more than three days left some dates missing or partial, including the first sync. Each incremental sync also resent the row before the last synced date with only that day’s final 7 hours. The lookback window only corrects recent days, so run a refresh with Refresh stream and retain records. In Incremental | Append mode, keep the latest row for each campaign_id and date. Don’t use Refresh stream and remove records or Clear. Reddit only provides the last 24 months of report data, so you can’t resync older rows. Full refresh syncs correct themselves during the next sync.
  • Report history has a limit. Delivery data covers the last 24 months. Reach and frequency data begins in June 2024. If Start Date is earlier, report streams still start 24 months before the current sync. Reddit rejects requests for older report data. ad, ad_group and campaign aren’t clamped.
  • Report streams use fixed breakdowns. Each report stream breaks metrics down by entity ID and UTC date. ad_group_report and ad_report also break data down by campaign, so their rows include campaign_id. ad_account_report sets account_id to your Ad Account ID. To find an ad_report row’s ad group, join ad on ad_id. Country and region breakdowns aren’t available. Custom conversion events by name aren’t available either.
  • Versions earlier than 0.0.9 synced only the first page of each stream. Reddit returns the next-page token URL-encoded. Earlier versions passed it back without decoding it, so every stream stopped after its first page. After upgrading from an earlier version, clear affected streams if records are missing from your destination. Then run a new sync.
  • ad, ad_group, and campaign read every record on each sync. The Reddit API can’t filter these lists by modified_at. Each incremental sync therefore requests every record in the ad account. It keeps only records modified since the previous sync, or since Start Date during the first sync. Sync duration depends on the account’s size, not the amount of new data.
  • Deletions aren’t detected. The connector doesn’t detect or mark deletions. Reddit marks a deleted ad, ad group or campaign with a configured_status or effective_status of DELETED. If Reddit still lists the item, the connector syncs it with that status. If Reddit stops listing it, the last-synced row remains in your destination. A Full Refresh | Overwrite sync replaces the table.

Troubleshooting

ErrorCause and fix
Refresh token was rejected by the OAuth providerReddit’s token endpoint rejected the refresh token or the client credentials. If you use Authenticate with Reddit, select Authenticate your Reddit Ads account again. If you use Use your own Reddit app, confirm the OAuth Client ID and Client Secret, then get a new refresh token with duration=permanent.
Reddit denied access to ad account (HTTP 403)The refresh token lacks the adsread scope, or the Reddit user who authorized it can’t access this ad account. Re-authenticate, or get a new refresh token with the adsread scope, while signed in as a user with access to the ad account.
Reddit could not find ad account (HTTP 404) or Reddit rejected the ad account IDThe Ad Account ID is wrong. Find your ad account ID, which starts with a2_, and update the source.
Reddit rejected the request as invalid (HTTP 400)Reddit rejected the request for a reason unrelated to the ad account. The error message includes the explanation Reddit returned.

IP allow list

If you use Airbyte Cloud and restrict access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Changelog

Expand to review
VersionDatePull RequestSubject
1.0.52026-11-1091692Update dependencies
1.0.42026-11-0390706Update dependencies
1.0.32026-10-2790048Update dependencies
1.0.22026-10-2289672Promote to certified
1.0.12026-10-2289670Use Reddit’s official icon from the Reddit Brand System; document where to find the ad account ID
1.0.02026-10-2089083Type timestamp, date and integer fields to match Reddit’s API and normalize report date to YYYY-MM-DD
0.4.12026-10-2088784Update dependencies
0.4.02026-10-1688964Add ad_account, ad_group, ad_account_report, ad_group_report and ad_report streams; show Reddit’s field-level reason in HTTP 400 error messages
0.3.02026-10-1588963Fix campaign_report windows that skipped one day in every three and overwrote earlier days with partial data; add a configurable report lookback window
0.2.02026-10-1488145Add OAuth (Authenticate with Reddit) for Airbyte Cloud with automatic config migration to a credentials object; make User Agent optional
0.1.12026-10-0688015Update dependencies
0.1.02026-10-0587043Show actionable errors for rejected refresh tokens or client credentials, invalid ad account IDs, and 400/403/404 responses, add a client-side API budget and configurable concurrency, add suggested streams, make spec titles human-readable, and add unit tests
0.0.122026-09-2987338Update dependencies
0.0.112026-09-2286789Update dependencies
0.0.102026-09-1586198Update dependencies
0.0.92026-09-0984850Fix pagination so every stream syncs all pages instead of only the first
0.0.82026-09-0885629Update dependencies
0.0.72026-08-1884348Enable acceptance test suite with GSM test secrets
0.0.62026-08-1884725Update dependencies
0.0.52026-08-1184089Update dependencies
0.0.42026-08-0483603Update dependencies
0.0.32026-08-0483266Stop refreshing the access token before every request, and refresh it before retrying a 401. Make start_time optional, apply it to all three streams, and default it to 24 months before the sync; clamp campaign_report to Reddit’s 24-month reporting window
0.0.22026-07-2883100Update dependencies
0.0.12026-07-2781399Initial release by @Ella6882 via Connector Builder
Advanced Analytica

Most businesses are sitting on information they can’t use at speed. The people who hold it are busy, and when they leave, the knowledge goes with them. The documents are static, and the processes around them weren’t designed for AI.

Advanced Analytica works with these businesses to turn that information into structured data assets. Once they're integrated, AI systems can govern it, and the business can use it. We bring in the strategy, the specification and the AI skills to rework how the business operates.

MOVE FAST. STAY SAFE.