How to Integrate Retool with Twitter (X) Ads

Twitter Ads API access requires two separate approvals: a Twitter Developer account with an approved app, and specific Ads API product access. In the Twitter Developer Portal (developer.twitter.com), sign in and navigate to your project and app settings. If you do not have a developer app, create one by clicking Create Project and then Create App. In the app settings, navigate to the Keys and Tokens tab. Under Consumer Keys, you will find the API Key (consumer key) and API Secret Key (consumer secret). Under Authentication Tokens, generate an Access Token and Secret — click Generate under Access Token and Secret, and copy both values immediately. These four credentials (consumer key, consumer secret, access token, access token secret) are all required for OAuth 1.0a request signing. Next, apply for Ads API access: in the developer portal, navigate to Products → Twitter Ads API and submit an application. Twitter reviews Ads API applications and approves them manually — approval typically takes 1-5 business days. Once approved, your app can access the Ads API endpoints. Note your Twitter Ads account ID: in Twitter Ads Manager, the account ID appears in the URL as a hexadecimal string (https://ads.twitter.com/accounts/XXXXXXXXXX). This account ID is required as a path parameter in most Ads API endpoints (e.g., /11/accounts/{account_id}/campaigns).

Retool's native REST API Resource does not generate OAuth 1.0a HMAC-SHA1 signatures automatically. OAuth 1.0a requires computing a signature for each individual request using the request method, URL, all parameters, and all four credentials — this must happen at request time, not at Resource configuration time. The recommended approach is to use a Retool Workflow as a lightweight proxy that generates the OAuth signature and forwards the request to Twitter. Navigate to Retool Workflows and create a new Workflow named Twitter Ads Proxy. Add a Webhook trigger — copy the generated webhook URL and API key. In the Workflow, add a JavaScript Code block. In the code block, write the OAuth 1.0a signature generation logic: build the signature base string from the HTTP method, encoded URL, and sorted encoded parameters (including oauth_consumer_key, oauth_nonce, oauth_signature_method, oauth_timestamp, oauth_token, oauth_version), compute the HMAC-SHA1 signature using the consumer secret and access token secret as the signing key, and build the Authorization header with all OAuth parameters. Then use Retool's built-in HTTP fetch in the JavaScript block to call Twitter's Ads API with the generated Authorization header and return the response to the Workflow caller. In your Retool app, instead of calling the Twitter API directly, create a REST API Resource pointing to the Retool Workflow webhook URL, passing the target Twitter endpoint and parameters as the request body. The Workflow handles signing and proxying. Store all four Twitter credentials as Retool configuration variables marked as secret.

1// JavaScript Code block in Retool Workflow
2// Generates OAuth 1.0a signature and proxies request to Twitter Ads API
3// Input from webhook: { method, path, params }
4
5const crypto = require('crypto');
6
7// Credentials from Retool config vars (access via retoolContext in Workflow)
8const CONSUMER_KEY = retoolContext.configVars.TWITTER_CONSUMER_KEY;
9const CONSUMER_SECRET = retoolContext.configVars.TWITTER_CONSUMER_SECRET;
10const ACCESS_TOKEN = retoolContext.configVars.TWITTER_ACCESS_TOKEN;
11const ACCESS_SECRET = retoolContext.configVars.TWITTER_ACCESS_SECRET;
12
13const method = trigger.data.method || 'GET';
14const twitterPath = trigger.data.path;
15const queryParams = trigger.data.params || {};
16
17const BASE_URL = `https://ads-api.twitter.com/12${twitterPath}`;
18
19// Generate OAuth 1.0a signature
20const timestamp = Math.floor(Date.now() / 1000).toString();
21const nonce = crypto.randomBytes(16).toString('hex');
22
23const oauthParams = {
24  oauth_consumer_key: CONSUMER_KEY,
25  oauth_nonce: nonce,
26  oauth_signature_method: 'HMAC-SHA1',
27  oauth_timestamp: timestamp,
28  oauth_token: ACCESS_TOKEN,
29  oauth_version: '1.0'
30};
31
32// Combine all params for signature base string
33const allParams = { ...queryParams, ...oauthParams };
34const sortedParams = Object.keys(allParams).sort().map(k =>
35  `${encodeURIComponent(k)}=${encodeURIComponent(allParams[k])}`
36).join('&');
37
38const signatureBase = [
39  method.toUpperCase(),
40  encodeURIComponent(BASE_URL),
41  encodeURIComponent(sortedParams)
42].join('&');
43
44const signingKey = `${encodeURIComponent(CONSUMER_SECRET)}&${encodeURIComponent(ACCESS_SECRET)}`;
45const signature = crypto.createHmac('sha1', signingKey).update(signatureBase).digest('base64');
46
47// Build Authorization header
48oauthParams.oauth_signature = signature;
49const authHeader = 'OAuth ' + Object.keys(oauthParams)
50  .map(k => `${encodeURIComponent(k)}="${encodeURIComponent(oauthParams[k])}"`)
51  .join(', ');
52
53// Build query string
54const queryString = Object.keys(queryParams).length
55  ? '?' + Object.keys(queryParams).map(k =>
56      `${encodeURIComponent(k)}=${encodeURIComponent(queryParams[k])}`
57    ).join('&')
58  : '';
59
60// Proxy request to Twitter
61const response = await fetch(`${BASE_URL}${queryString}`, {
62  method: method,
63  headers: {
64    'Authorization': authHeader,
65    'Content-Type': 'application/json'
66  }
67});
68
69const responseData = await response.json();
70return responseData;

With the OAuth proxy Workflow in place, configure a Retool REST API Resource to call the Workflow. Navigate to Resources → Add Resource → REST API. Name it Twitter Ads (via proxy). Set the Base URL to your Retool Workflow webhook URL (e.g., https://retool.com/api/workflow/WORKFLOW_ID/startTrigger). In the Headers, add the Workflow API key authentication: header name X-Workflow-Api-Key with value {{ config.RETOOL_WORKFLOW_KEY }}. Create a RETOOL_WORKFLOW_KEY configuration variable with the Workflow's API key. Store all four Twitter credentials as configuration variables: TWITTER_CONSUMER_KEY, TWITTER_CONSUMER_SECRET, TWITTER_ACCESS_TOKEN, TWITTER_ACCESS_SECRET — all marked as secret. Now create queries in the Retool app. Create a query targeting the Twitter Ads proxy Resource with Method POST (sending instructions to the Workflow). Set Path to / (the Workflow webhook base). Set Body type to JSON with the following structure: { "method": "GET", "path": "/accounts/{{ retoolContext.configVars.TWITTER_ADS_ACCOUNT_ID }}/campaigns", "params": { "count": "200" } }. The Workflow receives this, signs the request, calls Twitter, and returns the response. Create a second similar query for analytics. The Twitter Ads API returns campaigns as a data array with id, name, status, budget_optimization, created_at, and associated daily_budget_amount_local_micro (budget in micro-dollars — divide by 1,000,000 for display).

1// Query body for fetching campaigns via OAuth proxy Workflow
2// Method: POST, targeting the Retool Workflow webhook
3{
4  "method": "GET",
5  "path": "/accounts/{{ retoolContext.configVars.TWITTER_ADS_ACCOUNT_ID }}/campaigns",
6  "params": {
7    "count": "200",
8    "with_deleted": "false"
9  }
10}
11
12// Query body for fetching line items (ad groups) for a campaign
13{
14  "method": "GET",
15  "path": "/accounts/{{ retoolContext.configVars.TWITTER_ADS_ACCOUNT_ID }}/line_items",
16  "params": {
17    "campaign_ids": "{{ campaignsTable.selectedRow.id || '' }}",
18    "count": "200"
19  }
20}

Twitter Ads analytics requires a separate endpoint with different parameters than campaign listing queries. Create a query through the proxy Workflow with Body: { "method": "GET", "path": "/stats/accounts/{{ retoolContext.configVars.TWITTER_ADS_ACCOUNT_ID }}", "params": { "entity": "CAMPAIGN", "entity_ids": "{{ campaignIds.join(',') }}", "metric_groups": "ENGAGEMENT,BILLING", "granularity": "DAY", "start_time": "{{ formatDate(dateRangePicker.value[0], 'YYYY-MM-DD') }}", "end_time": "{{ formatDate(dateRangePicker.value[1], 'YYYY-MM-DD') }}", "placement": "ALL_ON_TWITTER" } }. The entity_ids parameter accepts a comma-separated list of campaign IDs — build this from the campaigns query response. The metric_groups parameter selects which metric categories to return: ENGAGEMENT (impressions, clicks, engagements, follows), BILLING (billed_charge_local_micro for spend), VIDEO (video views, completions). The granularity parameter controls aggregation: DAY for daily breakdown, TOTAL for period totals. The response is a data array where each element contains id_data with nested metrics per day. Add a JavaScript transformer to flatten this nested structure into a flat array of campaign-day records suitable for Table and Chart display. This transformer must handle Twitter's nested response where metrics are arrays of values corresponding to the time series.

1// JavaScript transformer for Twitter Ads Analytics API response
2// Twitter returns metrics as arrays aligned to the time series
3const analyticsData = data.data || [];
4
5const results = [];
6
7analyticsData.forEach(campaignMetrics => {
8  const campaignId = campaignMetrics.id;
9  const idData = campaignMetrics.id_data || [];
10
11  idData.forEach(dayData => {
12    const metrics = dayData.metrics || {};
13    const billedCharges = metrics.billed_charge_local_micro || [];
14    const impressions = metrics.impressions || [];
15    const clicks = metrics.clicks || [];
16    const engagements = metrics.engagements || [];
17
18    // Each metrics field is an array; values at same index correspond to same day
19    const days = billedCharges.length;
20    for (let i = 0; i < days; i++) {
21      const spend = (billedCharges[i] || 0) / 1000000; // Convert micro-dollars
22      const imp = impressions[i] || 0;
23      const clk = clicks[i] || 0;
24      const eng = engagements[i] || 0;
25
26      results.push({
27        campaign_id: campaignId,
28        day_index: i,
29        spend: spend.toFixed(2),
30        spend_display: `$${spend.toFixed(2)}`,
31        impressions: imp,
32        clicks: clk,
33        engagements: eng,
34        ctr: imp > 0 ? ((clk / imp) * 100).toFixed(2) + '%' : '0%',
35        cpm: imp > 0 ? `$${(spend / imp * 1000).toFixed(2)}` : '$0',
36        engagement_rate: imp > 0 ? ((eng / imp) * 100).toFixed(2) + '%' : '0%'
37      });
38    }
39  });
40});
41
42return results;

Assemble the performance dashboard in Retool. Add a DateRangePicker component at the top defaulting to the last 7 days. Add a Stat row showing period totals — compute these in a JavaScript query that sums the analytics array: total spend, total impressions, total engagements, and blended engagement rate. Drag a Table and bind it to the campaigns list from the campaigns query, joining campaign names with analytics totals using campaign_id as the join key. Configure Table columns: Campaign Name, Status, Daily Budget, Period Spend, Impressions, Engagements, Engagement Rate. Add conditional formatting: highlight campaigns where spend is 0 (paused or not spending). Add a Line Chart below the Table bound to the analytics data with date on X axis and spend on Y axis — this shows the daily spend trend across all campaigns. For creative-level analysis, add a second query at entity type PROMOTED_TWEET to get individual tweet performance. Join tweet IDs with tweet text by querying the Twitter v2 API (separate Resource with Bearer token auth, which is simpler) for tweet objects. Display tweet text, impressions, engagements, and engagement rate in a secondary Table. For complex multi-platform advertising operations platforms integrating Twitter, Meta, Google, TikTok, and custom attribution in Retool, RapidDev's team can architect comprehensive paid media operations solutions.

1// JavaScript query: join campaign metadata with analytics totals
2const campaigns = getCampaigns.data?.data || [];
3const analytics = getAnalytics.data || [];
4
5// Aggregate analytics by campaign_id
6const byCampaign = {};
7analytics.forEach(row => {
8  const id = row.campaign_id;
9  if (!bycampaign[id]) {
10    byCampaign[id] = { spend: 0, impressions: 0, clicks: 0, engagements: 0 };
11  }
12  byampaign[id].spend += parseFloat(row.spend || 0);
13  byC[id].impressions += parseInt(row.impressions || 0);
14  byC[id].clicks += parseInt(row.clicks || 0);
15  byCampaign[id].engagements += parseInt(row.engagements || 0);
16});
17
18return campaigns.map(c => {
19  const stats = byCampaign[c.id] || {};
20  const budget = c.daily_budget_amount_local_micro
21    ? `$${(c.daily_budget_amount_local_micro / 1000000).toFixed(2)}`
22    : 'Campaign Budget';
23  return {
24    id: c.id,
25    name: c.name,
26    status: c.status || c.entity_status || '',
27    daily_budget: budget,
28    spend: (stats.spend || 0).toFixed(2),
29    spend_display: `$${(stats.spend || 0).toFixed(2)}`,
30    impressions: stats.impressions || 0,
31    engagements: stats.engagements || 0,
32    engagement_rate: stats.impressions > 0
33      ? ((stats.engagements / stats.impressions) * 100).toFixed(2) + '%'
34      : '0%'
35  };
36});