How to Integrate Retool with Reddit Ads

To use the Reddit Ads API, you need a Reddit developer application. Log in to Reddit and navigate to reddit.com/prefs/apps (or go to your account settings and click the Develop Apps link). Scroll to the bottom and click Create another app. In the form, enter a Name for your app (e.g., Retool Integration). For the app type, select 'script' if you are the only person using this Retool dashboard, or 'web app' for broader team use. For the redirect URI, enter https://retool.com/oauth/callback (this is used only for user-facing OAuth flows; for client credentials you use a different grant type, but Reddit still requires a redirect URI at app creation). Leave the description field optional. Click Create app. Reddit creates the application and shows you the credentials. The client_id is the string displayed just below the app name in the app listing (it looks like a random 14-character alphanumeric string). The client_secret is shown under the app details as 'secret'. Copy both values. Also note that the Reddit Ads API requires your app to be granted Ads API access separately from the standard Reddit API — you may need to apply for Ads API access at ads.reddit.com/developer or contact Reddit's API team. Once approved, your client credentials will have permission to call ads-api.reddit.com endpoints. Store both the client_id and client_secret securely — you will add them to Retool configuration variables in the next step.

Reddit's Ads API uses OAuth 2.0. Before any API call, you must exchange your client credentials for an access token. The token endpoint is https://www.reddit.com/api/v1/access_token. In Retool, create a dedicated token exchange query to handle this. First, add your credentials as configuration variables in Retool Settings → Configuration Variables: add REDDIT_CLIENT_ID (value: your client_id), REDDIT_CLIENT_SECRET (value: your client_secret, marked as secret), and REDDIT_AD_ACCOUNT_ID (value: your ads account ID from the Ads Manager URL). Now create a REST API Resource named Reddit Token specifically for the OAuth token endpoint. Base URL: https://www.reddit.com. In the Headers section, add Authorization with value Basic {{ btoa(config.REDDIT_CLIENT_ID + ':' + config.REDDIT_CLIENT_SECRET) }} — however, Retool does not support btoa() in Resource headers. Instead, pre-compute the Base64-encoded credentials string manually (or in a JavaScript query) and store it as a configuration variable REDDIT_BASIC_AUTH. The format is Base64Encode('client_id:client_secret'). Set the Authorization header to Basic {{ config.REDDIT_BASIC_AUTH }}. Create a query on this Resource: Method POST, Path /api/v1/access_token, Body type Form, with fields: grant_type = client_credentials, and optionally device_id = DO_NOT_TRACK_THIS_DEVICE. Also add the User-Agent header to the Resource: User-Agent: RetoolIntegration/1.0 by YourRedditUsername (Reddit's API requires a descriptive User-Agent). Run this query — it returns a JSON object with access_token (a 27+ character string) and expires_in (typically 3600 = one hour). Store the access_token in a Retool state variable or configuration variable for subsequent queries.

1// JavaScript query to compute Base64 credentials for Reddit OAuth
2// Run this once to get the value to store in a config variable
3const clientId = retoolContext.configVars.REDDIT_CLIENT_ID;
4const clientSecret = retoolContext.configVars.REDDIT_CLIENT_SECRET;
5const credentials = clientId + ':' + clientSecret;
6const encoded = btoa(credentials);
7return { basic_auth: 'Basic ' + encoded, raw: encoded };
8// Copy the 'raw' value and store it as REDDIT_BASIC_AUTH config variable

Create a second REST API Resource specifically for the Reddit Ads API. In the Resources tab, click Add Resource → REST API. Name it Reddit Ads API. Base URL: https://ads-api.reddit.com/api/v2. In the Headers section, add the Authorization header with value Bearer {{ config.REDDIT_ACCESS_TOKEN }} — this references a configuration variable where you will store the current access token retrieved in the previous step. After the token query runs, save its output to the configuration variable using a Retool JavaScript query: in a JS query, call utils.setState or reference getAccessToken.data.access_token and store it. Also add the User-Agent header matching what you used in the token request. Click Save on the Resource. Now create your first Ads API query: Method GET, Path /act_{{ config.REDDIT_AD_ACCOUNT_ID }}/campaigns — note the act_ prefix before the account ID is required by some Reddit API versions; check the documentation for the exact format. Add URL parameters: limit: 100, count: 100. This returns all campaigns for the account. Create a second query for campaign performance metrics — the reporting endpoint is at /act_{{ config.REDDIT_AD_ACCOUNT_ID }}/campaigns/{{ campaignsTable.selectedRow.id }}/insights or use the bulk reporting endpoint at /act_{{ config.REDDIT_AD_ACCOUNT_ID }}/insights with campaign_ids as a parameter. Check Reddit Ads API documentation for the exact endpoint paths and required fields parameter (similar to Meta's Insights API, Reddit requires you to specify which metrics to return).

1// JavaScript transformer for Reddit Ads campaign list
2const campaigns = data?.data || data?.campaigns || data || [];
3if (!Array.isArray(campaigns)) return [];
4
5return campaigns.map(campaign => ({
6  id: campaign.id || '',
7  name: campaign.name || '',
8  status: campaign.status || campaign.effective_status || 'unknown',
9  objective: campaign.objective || '',
10  daily_budget: campaign.daily_budget
11    ? `$${(parseInt(campaign.daily_budget) / 100).toFixed(2)}`
12    : campaign.total_budget
13    ? `$${(parseInt(campaign.total_budget) / 100).toFixed(2)} total`
14    : 'N/A',
15  start_time: campaign.start_time ? new Date(campaign.start_time).toLocaleDateString() : '',
16  end_time: campaign.end_time ? new Date(campaign.end_time).toLocaleDateString() : 'No end',
17  ads_manager_url: `https://ads.reddit.com/accounts/${retoolContext.configVars.REDDIT_AD_ACCOUNT_ID}/campaigns/${campaign.id}`
18}));

With the campaign list working, build the performance reporting layer. Create a query targeting Reddit's insights/reporting endpoint. The Reddit Ads API reporting endpoint is typically at /act_{account_id}/insights with the following URL parameters: campaign_ids (comma-separated campaign IDs from the campaigns list), date_range (start_date and end_date in YYYY-MM-DD format, or a preset like LAST_30_DAYS), fields (the metrics to retrieve — check Reddit Ads API documentation for exact field names, which may include spend, impressions, clicks, ctr, cpm, cpc, conversions, and view_through_conversions), and interval (DAY for daily breakdown, TOTAL for aggregate). Wire the date parameters to a DateRangePicker component in the app. Build the dashboard layout: add a DateRangePicker at the top, then two rows of Stat components showing: Total Spend, Total Impressions, Total Clicks, Blended CTR, Average CPM, and Total Conversions — all calculated from a JavaScript aggregation query on the insights data. Below the stats, add a Table bound to the campaign performance data. Configure the Table with columns for campaign name, spend, impressions, clicks, CTR, CPM, CPC, conversions, and status. Enable sort on all numeric columns. Add a line Chart showing daily spend over the selected date range for the top 5 campaigns by spend — filter the daily data in a JavaScript transformer before binding to the Chart. Add a second Chart as a bar chart comparing spend versus conversions for each campaign.

1// JavaScript transformer for Reddit Ads insights/reporting response
2const insights = data?.data || data?.insights || data || [];
3if (!Array.isArray(insights)) return [];
4
5return insights.map(row => {
6  const spend = parseFloat(row.spend || 0) / 1000000; // microdollars to dollars
7  const impressions = parseInt(row.impressions || 0);
8  const clicks = parseInt(row.clicks || 0);
9  const conversions = parseInt(row.conversions || row.total_conversions || 0);
10
11  return {
12    campaign_id: row.campaign_id || row.id || '',
13    campaign_name: row.campaign_name || row.name || '',
14    date: row.date || row.start_date || '',
15    spend: spend.toFixed(2),
16    spend_display: `$${spend.toFixed(2)}`,
17    impressions,
18    clicks,
19    ctr: impressions > 0
20      ? ((clicks / impressions) * 100).toFixed(3) + '%'
21      : '0%',
22    cpm: impressions > 0
23      ? `$${((spend / impressions) * 1000).toFixed(2)}`
24      : '$0',
25    cpc: clicks > 0
26      ? `$${(spend / clicks).toFixed(2)}`
27      : '$0',
28    conversions,
29    cpa: conversions > 0
30      ? `$${(spend / conversions).toFixed(2)}`
31      : 'N/A',
32    status: row.status || ''
33  };
34});

Add the subreddit targeting breakdown — Reddit's most unique feature. Create a query at /act_{{ config.REDDIT_AD_ACCOUNT_ID }}/ad_groups to retrieve all ad groups. A second query at /act_{{ config.REDDIT_AD_ACCOUNT_ID }}/ad_groups/{{ adGroupsTable.selectedRow.id }}/targeting retrieves the targeting configuration for a selected ad group, including the list of targeted subreddits. Display the subreddits in a List or Table component in a detail panel when an ad group is selected, showing each subreddit alongside the ad group's performance metrics joined by ad group ID. For token refresh automation, create a Retool Workflow: Trigger type Schedule → every 50 minutes. Add a Resource Query block targeting the Reddit Token Resource with the client credentials token exchange query. Add a second block (JavaScript) that updates the REDDIT_ACCESS_TOKEN configuration variable using the retool SDK or a REST call to Retool's Config Variables API. This workflow keeps the access token fresh automatically without manual intervention. For teams running complex multi-platform campaigns combining Reddit data with Facebook, Google, and TikTok Ads in unified dashboards, RapidDev can help architect a comprehensive cross-channel attribution Retool solution.

1// JavaScript query to aggregate period totals for Stat components
2const data = getInsights.data || [];
3
4const totalSpend = data.reduce((sum, row) => sum + parseFloat(row.spend || 0), 0);
5const totalImpressions = data.reduce((sum, row) => sum + parseInt(row.impressions || 0), 0);
6const totalClicks = data.reduce((sum, row) => sum + parseInt(row.clicks || 0), 0);
7const totalConversions = data.reduce((sum, row) => sum + parseInt(row.conversions || 0), 0);
8
9return {
10  total_spend: `$${totalSpend.toFixed(2)}`,
11  total_impressions: totalImpressions.toLocaleString(),
12  total_clicks: totalClicks.toLocaleString(),
13  blended_ctr: totalImpressions > 0
14    ? ((totalClicks / totalImpressions) * 100).toFixed(3) + '%'
15    : '0%',
16  average_cpm: totalImpressions > 0
17    ? `$${((totalSpend / totalImpressions) * 1000).toFixed(2)}`
18    : '$0',
19  total_conversions: totalConversions,
20  blended_cpa: totalConversions > 0
21    ? `$${(totalSpend / totalConversions).toFixed(2)}`
22    : 'N/A'
23};