How to Integrate Bolt.new with Twitter (X) Ads

X Ads API access is not available automatically — you must apply and be approved. The approval process has tightened significantly since 2023 and requires a legitimate advertising use case. Start at developer.x.com. Sign in with your X account and create a Developer Project if you do not have one. Inside the project, create an App. Give it a clear, descriptive name that reflects your advertising use case (e.g., 'MyCompany Ads Dashboard'). Under the app's settings, look for 'Ads API access' or 'Advanced access' and click to apply. The application asks about your use case — be specific and honest about building an ad analytics dashboard for your own or your clients' accounts. X also requires that your X Ads account has actual spending history. A brand-new ads account with no spend is unlikely to be approved. If your ads account is new, make a small test campaign spend before applying. Once your app is created and Ads API access is approved, navigate to the app's 'Keys and Tokens' section. You need four credentials: API Key (also called Consumer Key), API Key Secret (Consumer Secret), Access Token, and Access Token Secret. The API Key and Secret identify your app. The Access Token and Secret represent the X account that will be making API calls — generate these by clicking 'Generate' under Access Token. Note the Ads Account ID (format: `18ce54xxxx`) from your X Ads dashboard at ads.x.com — it appears in the URL when you are in Ads Manager. Add all five values to your Bolt project's .env file.

1// lib/twitter-ads.ts
2import { TwitterApi } from 'twitter-api-v2';
3
4const ADS_API_BASE = 'https://ads-api.x.com/12';
5
6export function getTwitterAdsClient(): TwitterApi {
7  const apiKey = process.env.TWITTER_API_KEY;
8  const apiSecret = process.env.TWITTER_API_SECRET;
9  const accessToken = process.env.TWITTER_ACCESS_TOKEN;
10  const accessSecret = process.env.TWITTER_ACCESS_SECRET;
11
12  if (!apiKey || !apiSecret || !accessToken || !accessSecret) {
13    throw new Error(
14      'Missing Twitter OAuth credentials. Set TWITTER_API_KEY, TWITTER_API_SECRET, ' +
15      'TWITTER_ACCESS_TOKEN, and TWITTER_ACCESS_SECRET in .env'
16    );
17  }
18
19  return new TwitterApi({
20    appKey: apiKey,
21    appSecret: apiSecret,
22    accessToken: accessToken,
23    accessSecret: accessSecret,
24  });
25}
26
27export async function twitterAdsGet<T = unknown>(endpoint: string, params?: Record<string, string>): Promise<T> {
28  const accountId = process.env.TWITTER_ADS_ACCOUNT_ID;
29  if (!accountId) throw new Error('TWITTER_ADS_ACCOUNT_ID is not configured');
30
31  const client = getTwitterAdsClient();
32
33  const url = new URL(`${ADS_API_BASE}/accounts/${accountId}/${endpoint}`);
34  if (params) {
35    Object.entries(params).forEach(([key, value]) => url.searchParams.set(key, value));
36  }
37
38  // Use the underlying OAuth1 client for raw requests
39  const response = await client.v1.get(url.toString()) as T;
40  return response;
41}

X Ads API organizes advertising into Campaigns, Line Items (equivalent to ad groups), and Promoted Tweets. Performance statistics are available through the `/stats/accounts/{account_id}` endpoint rather than embedded in campaign objects, which means you make separate calls for metadata and metrics. To list campaigns, call `GET /12/accounts/{account_id}/campaigns` with query parameters for filtering. The response includes campaign name, objective, status (ACTIVE, PAUSED, DRAFT, DELETED), budget type, and total budget. Active campaigns are filtered with `funding_instrument_ids` or by checking `entity_status=ACTIVE`. For performance statistics, call `GET /12/stats/accounts/{account_id}` with required parameters: `entity=CAMPAIGN`, `entity_ids` (comma-separated list of campaign IDs), `start_time` and `end_time` in ISO 8601 format, `placement=ALL_ON_TWITTER`, and `metric_groups=ENGAGEMENT,BILLING`. This endpoint returns an array of stat objects per campaign ID per day or as a total depending on the `granularity` parameter (DAY, TOTAL). Key metrics in the ENGAGEMENT metric group: `impressions`, `engagements`, `clicks`, `retweets`, `likes`, `replies`, `follows`, `url_clicks`, `app_clicks`, `card_engagements`. The BILLING group contains `billed_charge_local_micro` (spend in microdollars — divide by 1,000,000 for dollars), `billed_engagements`, and `billed_follows`. A performance nuance unique to X: promoted tweets receive both paid metric tracking and organic metric spillover. When your promoted tweet goes viral after someone retweets it organically, those organic impressions are tracked separately as `organic_impressions`. Surfacing this earned media value — how much organic reach your paid campaign generated — is a compelling dashboard feature that X Ads natively provides and Facebook does not.

1// app/api/twitter/campaigns/route.ts
2import { NextResponse } from 'next/server';
3import { twitterAdsGet } from '@/lib/twitter-ads';
4
5interface XCampaign {
6  id: string;
7  name: string;
8  entity_status: string;
9  objective: string;
10  total_budget_amount_local_micro?: number;
11}
12
13interface XStatEntry {
14  id: string;
15  id_data: Array<{
16    segment?: unknown;
17    metrics: {
18      impressions: number[];
19      engagements: number[];
20      clicks: number[];
21      url_clicks: number[];
22      retweets: number[];
23      likes: number[];
24      replies: number[];
25      billed_charge_local_micro: number[];
26    };
27  }>;
28}
29
30function sum(arr?: number[]): number {
31  if (!arr || arr.length === 0) return 0;
32  return arr.reduce((a, b) => a + b, 0);
33}
34
35export async function GET(request: Request) {
36  const { searchParams } = new URL(request.url);
37  const endDate = new Date();
38  const startDate = new Date(endDate.getTime() - 30 * 24 * 60 * 60 * 1000);
39  const startTime = searchParams.get('startTime') || startDate.toISOString();
40  const endTime = searchParams.get('endTime') || endDate.toISOString();
41
42  try {
43    const campaignsData = await twitterAdsGet<{ data: XCampaign[] }>('campaigns', {
44      count: '100',
45      with_deleted: 'false',
46    });
47
48    const campaigns = campaignsData.data || [];
49    if (campaigns.length === 0) {
50      return NextResponse.json({ campaigns: [], totals: {} });
51    }
52
53    const campaignIds = campaigns.map((c) => c.id).join(',');
54
55    const statsData = await twitterAdsGet<{ data: XStatEntry[] }>(
56      `../../stats/accounts/${process.env.TWITTER_ADS_ACCOUNT_ID}`,
57      {
58        entity: 'CAMPAIGN',
59        entity_ids: campaignIds,
60        start_time: startTime,
61        end_time: endTime,
62        placement: 'ALL_ON_TWITTER',
63        metric_groups: 'ENGAGEMENT,BILLING',
64        granularity: 'TOTAL',
65      }
66    );
67
68    const statsMap = new Map<string, XStatEntry>();
69    (statsData.data || []).forEach((s) => statsMap.set(s.id, s));
70
71    const result = campaigns.map((campaign) => {
72      const stat = statsMap.get(campaign.id);
73      const metrics = stat?.id_data?.[0]?.metrics;
74
75      const spendMicro = sum(metrics?.billed_charge_local_micro);
76
77      return {
78        id: campaign.id,
79        name: campaign.name,
80        status: campaign.entity_status,
81        objective: campaign.objective,
82        totalBudget: campaign.total_budget_amount_local_micro
83          ? campaign.total_budget_amount_local_micro / 1_000_000
84          : null,
85        impressions: sum(metrics?.impressions),
86        engagements: sum(metrics?.engagements),
87        clicks: sum(metrics?.url_clicks),
88        retweets: sum(metrics?.retweets),
89        likes: sum(metrics?.likes),
90        replies: sum(metrics?.replies),
91        spend: spendMicro / 1_000_000,
92        cpe: spendMicro > 0 && sum(metrics?.engagements) > 0
93          ? (spendMicro / 1_000_000) / sum(metrics.engagements)
94          : null,
95      };
96    });
97
98    result.sort((a, b) => b.spend - a.spend);
99
100    const totals = result.reduce(
101      (acc, c) => ({
102        spend: acc.spend + c.spend,
103        impressions: acc.impressions + c.impressions,
104        engagements: acc.engagements + c.engagements,
105        clicks: acc.clicks + c.clicks,
106      }),
107      { spend: 0, impressions: 0, engagements: 0, clicks: 0 }
108    );
109
110    return NextResponse.json({ campaigns: result, totals });
111  } catch (err) {
112    const message = err instanceof Error ? err.message : 'Failed to fetch X Ads campaigns';
113    return NextResponse.json({ error: message }, { status: 500 });
114  }
115}

An X Ads dashboard has unique metrics to surface compared to Facebook or Google Ads dashboards. Beyond the standard impressions, clicks, and spend columns, X Ads provides detailed engagement breakdowns: URL clicks, app clicks, retweets, likes, replies, and follows. The most valuable X-specific metric for most advertisers is cost-per-engagement (CPE) — how much each meaningful interaction cost — rather than just cost-per-click. For the dashboard layout, consider three sections: a summary header with total spend, total impressions, total engagements, and average engagement rate (engagements divided by impressions, expressed as a percentage); a campaign table with sortable columns; and optionally an engagement breakdown card showing the distribution of engagement types (what percentage of total engagements were URL clicks vs. retweets vs. likes). X Ads campaign objectives have specific names: TWEET_ENGAGEMENTS (maximize interactions), WEBSITE_CLICKS (drive traffic), APP_INSTALLS, VIDEO_VIEWS, FOLLOWERS (grow account), REACH, and PREROLL_VIEWS. Map these to readable display names in your UI. The engagement rate benchmark on X varies by industry and campaign type. Tweet engagement campaigns typically achieve 1-3% engagement rates; website click campaigns prioritize URL click rate over broader engagement. Display the metric most relevant to the campaign objective — highlight URL click rate for WEBSITE_CLICKS campaigns and total engagement rate for TWEET_ENGAGEMENTS campaigns. For date range selection, build presets that map to ISO 8601 datetime strings as X Ads API requires full datetime strings (not just date strings like Reddit's API). Use the JavaScript Date object to generate properly formatted start_time and end_time values.

During development in Bolt's WebContainer, all outbound calls to X's Ads API work correctly — OAuth 1.0a request signing happens server-side in the Next.js API route, and the signed requests go out over HTTPS to X's servers. The WebContainer limitation does not affect the X Ads integration because OAuth 1.0a does not require a redirect callback. All four credentials are stored in .env and used directly without any authorization flow. This means the full X Ads integration — reading campaigns, fetching stats, displaying a dashboard — can be tested entirely in Bolt's WebContainer preview without deploying. There is no incoming webhook or OAuth callback that would require a public URL. To deploy, connect Netlify via Settings → Applications → Connect Netlify, or click Publish in Bolt to deploy to Bolt Cloud. After deployment, add environment variables in your hosting dashboard: `TWITTER_API_KEY`, `TWITTER_API_SECRET`, `TWITTER_ACCESS_TOKEN`, `TWITTER_ACCESS_SECRET`, and `TWITTER_ADS_ACCOUNT_ID`. These should not have the `NEXT_PUBLIC_` prefix — they are server-side only credentials that must never appear in client JavaScript bundles. Note about X API access tiers and future changes: X's API pricing and access tiers have changed multiple times since 2023 and may continue to change. The Basic tier ($100/month as of early 2026) provides enough rate limits for a single-account analytics dashboard. The Pro tier is needed for higher-volume applications. Before investing significant development time, verify the current access tier requirements at developer.x.com to ensure the API access level you have matches your application's needs.

1# Production environment variables — add in Netlify or Bolt Cloud
2# All four credentials are required for OAuth 1.0a request signing
3# Do NOT add NEXT_PUBLIC_ prefix — these must stay server-side only
4
5TWITTER_API_KEY=your_api_key
6TWITTER_API_SECRET=your_api_secret
7TWITTER_ACCESS_TOKEN=your_access_token
8TWITTER_ACCESS_SECRET=your_access_token_secret
9TWITTER_ADS_ACCOUNT_ID=18ce54your_account_id