2025 Growth Unified Hits Major Growth Milestones with 6.5x usage & 4.5x revenue growth
Unified.to
All articles

How to Get Your X Ads (Twitter Ads) API Key

May 29, 2026

The first thing worth clarifying: the X Ads API in 2026 is operational and not subject to the $42,000/month enterprise pricing that affected the general X API. When X restructured its developer tiers in 2023-2024, the company explicitly stated the Ads API would "continue to be available at no additional cost to approved Twitter API developers." That position has held through the pay-per-use migration of the general API in February 2026. The Ads API remains an approval-gated partner program — separate from general X API access, with its own application flow and review.

That said, X Ads is the most volatile of the paid-social APIs to build against in 2026. The Ads API itself is technically mature and versioned (v12 is current), but it sits inside a platform that's still going through pricing migrations, brand migrations (twitter.com → x.com hostnames), and field-level schema changes. April 29, 2026 brought a round of X Ads field availability changes that integrators had to adapt to. Engineers building on X Ads should plan for higher ongoing maintenance overhead than they'd see with Snapchat or Reddit.

This guide covers the 2026 process: registering for a developer account at developer.x.com, creating an app, applying for Ads API access, navigating the OAuth model (still primarily OAuth 1.0a for writes — genuinely unusual in 2026), and the X-specific patterns like Promoted Tweets and the Line Item hierarchy that don't exist on other paid-social platforms.

Key takeaways

  • The product is the X Ads API (formerly Twitter Ads API), current version v12, with the canonical base URL https://ads-api.x.com/12/.... Legacy ads-api.twitter.com hostnames may still resolve during the migration.
  • App registration happens at developer.x.com (no longer developer.twitter.com). Ads access requires a separate approval application on top of general developer registration.
  • Ads API access is not metered by the general X API pay-per-use model that launched in February 2026. Once approved, Ads calls don't carry the same per-credit cost as general v2 API endpoints — but you still operate inside the same developer billing console.
  • OAuth 1.0a is still primary for Ads write operations in 2026. This is genuinely unusual — every other paid-social platform has migrated to OAuth 2.0. Plan for OAuth 1.0a signature generation for campaign management.
  • OAuth 2.0 bearer tokens are supported for app-only read scenarios where the endpoint allows it.
  • There are no granular Ads OAuth scopes to request. Ads capabilities are inherited from your app's approval status and which ad accounts your tokens are linked to.
  • X's hierarchy uses different terminology: Account → Campaign → Line Item → Promoted Tweet / Media Creative. "Line Item" is X's term for what other platforms call Ad Group or Ad Squad.
  • The Promoted Tweet model is still the core paid-social mechanic — advertisers promote their own Tweets/Posts as ads. Similar in concept to TikTok's Spark Ads but mechanically simpler (no creator-generated authorization codes required for first-party content).

Before you start

You'll need:

  • An X account in good standing
  • A developer account at developer.x.com — separate from your regular X account, requiring agreement to the X Developer Agreement
  • A clear Ads-specific use case — campaign management, reporting, audience syncing, conversions tracking — that you'll describe in the Ads API access application
  • Patience for the approval process. Approval can take days to weeks depending on use case and review queue
  • An understanding that X Ads operates inside the broader X developer billing model — general API calls outside the Ads program are now metered per-credit, even if Ads-specific calls aren't

If you're building for a multi-tenant SaaS, plan for each customer's advertiser account to be linked to your app's approved Ads access. The approval is granted at the app level, but Ads operations resolve per-advertiser-account at request time.

Step-by-step: getting X Ads API credentials in 2026

1. Create a developer account

Go to developer.x.com and sign in with your X account. Apply for a developer account and complete the brief application describing your intended use. For Ads-specific use cases, mention this clearly — it's not a separate application yet, but it signals your direction.

2. Register your app

In the Developer Console, create a new app:

  • App name and description
  • Use case — specifically mention campaign management, reporting, audience syncing, or whichever Ads operation you'll perform
  • Callback URL for OAuth (e.g., https://your-app.com/oauth/callback)
  • App permissions — request Read and Write if you'll be managing campaigns; Read only if you're reporting only

After creating the app, retrieve from the Keys and tokens tab:

  • API Key (consumer key)
  • API Secret (consumer secret) — shown only once, save immediately
  • Bearer Token for OAuth 2.0 read-only scenarios
  • Access Token and Access Token Secret — generate these for OAuth 1.0a user-context calls

3. Apply for Ads API access

This is the critical step that distinguishes X Ads from general X API access. The standard developer keys do not grant Ads API access on their own.

From the X Ads API documentation or the Developer Console, locate the Ads API access request form. Fill in:

  • Your developer app details
  • Specific Ads-related use case (reporting, campaign management, conversions tracking, etc.)
  • Expected volume and the ad accounts you'll be working with
  • Business context — agency, in-house tool, SaaS product

Submit and wait for approval. Once approved, your existing app credentials gain Ads API capabilities — no new keys are issued. The same API Key, API Secret, and access tokens now work against ads-api.x.com endpoints.

4. Authenticate using OAuth 1.0a for writes

For Ads write operations (creating campaigns, line items, ads), you'll generate OAuth 1.0a signed requests. The signature requires:

  • Your API Key and API Secret (the consumer credentials)
  • The user's Access Token and Access Token Secret
  • A signed request including timestamp, nonce, and HMAC-SHA1 signature of the request

Most languages have OAuth 1.0a libraries (Twython, oauthlib, etc.) that handle the signature generation. Don't try to implement OAuth 1.0a signing by hand — it's a well-known footgun.

For OAuth 2.0 bearer tokens (read-only flows where supported), include Authorization: Bearer {bearer_token} in the request header.

5. Make authenticated Ads API calls

Every Ads API request includes the account_id in the path:

GET https://ads-api.x.com/12/accounts/{account_id}
GET https://ads-api.x.com/12/accounts/{account_id}/campaigns
GET https://ads-api.x.com/12/accounts/{account_id}/line_items
GET https://ads-api.x.com/12/accounts/{account_id}/promoted_tweets

The hierarchy resolves through account_id, campaign_id, line_item_id, and promoted_tweet_id (or media_creative_id, card_uri, etc., for other creative types).

The gotcha: X Ads has its own quirks

OAuth 1.0a is still the dominant pattern. This is genuinely unusual in 2026 — every other paid-social platform has migrated to OAuth 2.0. X Ads writes still rely on OAuth 1.0a user-context signatures. Engineers used to modern OAuth 2.0 flows often expect a refresh-token loop that doesn't apply here. OAuth 1.0a access tokens are long-lived and don't expire on a timer; they remain valid until revoked.

"Line Item" is what other platforms call "Ad Group." X's terminology is unique. If you're coming from Meta, Google, Pinterest, or TikTok, mentally map "Ad Group" / "Ad Set" / "Ad Squad" to "Line Item." The Ad Group level in X is where targeting, budget, schedule, placements, and bidding live — same role, different name.

The $42k pricing controversy did NOT affect Ads API access. A lot of mid-2024 commentary conflated the general X API price changes with Ads API access. They're separate programs. The general X API (v2 endpoints for posts, users, search, etc.) went through Basic/Pro/Enterprise tiering and is now on per-credit pay-per-use as of February 2026. Ads API stayed separate, approval-gated, and at no additional cost to approved Ads partners. If you've avoided X Ads because you assumed the $42k tier applied, it doesn't.

Branding migration is incomplete. Official documentation, status pages, and pricing pages now use developer.x.com and docs.x.com. But legacy paths, code examples in older docs, and some hostnames still say twitter.com. Both ads-api.x.com and ads-api.twitter.com may resolve. Use x.com hostnames for new code and treat any twitter.com references as likely legacy.

Field-level changes happen without major version bumps. April 29, 2026 brought a round of X Ads field availability changes — fields removed, renamed, or made conditionally available. Integrators had to update their parsing. This is a real maintenance overhead that's higher than other paid-social platforms.

Global reads have surprisingly tight rate limits. Most rate limits are reasonable (write endpoints around 450/min, account reads around 10,000 per 15-minute window), but global reads — GET endpoints without an account_id — are capped at only about 5 per 15-minute window. Use them sparingly.

Pixel and Conversions API are part of the Ads API umbrella. Unlike Pinterest (separate CAPI token) or TikTok (Events API uses a separate long-lived Pixel token), X's Pixel and Conversions API are reachable under the same Ads API host and OAuth flow. Server-side conversion events use the same auth pattern as campaign management.

Security and credential handling

Store all credentials in a proper secret manager. API Key, API Secret, Bearer Token, Access Token, Access Token Secret — all are sensitive. AWS Secrets Manager, Azure Key Vault, GCP Secret Manager. Never commit them.

OAuth 1.0a access tokens don't refresh on a timer. They remain valid until explicitly revoked. This means re-authorization isn't a routine maintenance task — but it also means tokens that are compromised stay compromised until you rotate them.

Rotate API Keys after suspected exposure. Regenerate in the Developer Console. Any previously-issued bearer tokens or signatures based on the old secret will stop working — coordinate rotation with your deployment.

Use least-privilege app permissions. Request Read-only at the app level if your integration is reporting only. Read-and-Write is required for campaign management but signals broader capability during the Ads access review.

Rate limit defensively. With per-category limits varying widely — global reads at 5/15min vs analytics at 60,000/window — design your client around the tightest limit you'll touch. Centralized request pacing matters more than per-tenant throttling.

Monitor field-change announcements. X publishes API change notices that integrators need to track. Set up monitoring of the X Developer Platform status page and ads-related forum announcements; field changes have happened mid-year without major version bumps.

Is there an API-key alternative?

For most Ads operations: no. OAuth 1.0a user-context signatures (or OAuth 2.0 bearer tokens for read-only flows) are the auth mechanism. The "API Key" terminology in X's developer console refers to the consumer key — half of the OAuth 1.0a credential pair, not a standalone static key for direct API access.

Frequently asked questions

Is the X Ads API affected by the $42k/month enterprise pricing? No. The $42k pricing controversy was about the general X API (v2 endpoints for posts, users, search, etc.), not the Ads API. X explicitly stated Ads API access remains "at no additional cost to approved Twitter API developers." That position has held through the 2026 pay-per-use migration of the general API. Ads access is approval-gated, not metered per-call.

Why is X still using OAuth 1.0a in 2026? OAuth 1.0a has been part of X's developer surface since the Twitter era and remains operational. There's no published deprecation timeline for OAuth 1.0a on Ads writes. OAuth 2.0 bearer tokens are supported for read-only flows where allowed, but writes — campaign creation, line item updates, ad management — still rely on OAuth 1.0a signed requests. Plan for OAuth 1.0a tooling.

How does X Ads compare to Snapchat, Reddit, and TikTok? Snapchat is the most open (no tier model, available to all developers since 2018). Reddit Ads uses informal allow-list approval but is stable and being invested in as a growth surface. TikTok is the most gated (sandbox-to-production review, business verification, data-security compliance check). X Ads sits in the middle — approval-gated but not as restrictive as TikTok, less stable than Snapchat or Reddit due to ongoing platform-wide changes. For a multi-platform paid-social integration, expect X Ads to require the most ongoing maintenance overhead due to field changes and branding migrations.

What's a Promoted Tweet and is it the same as TikTok Spark Ads? A Promoted Tweet is an organic Tweet/Post that an advertiser pays to amplify to a broader audience. The advertiser typically owns the Tweet — they're promoting their own content, not third-party content. TikTok's Spark Ads are conceptually similar but mechanically different: Spark Ads boost organic content posted by independent creators, which requires a creator-generated authorization code. X's Promoted Tweets don't require an authorization handshake when the advertiser is the post author. Both serve the same advertiser goal (paying to amplify organic-feeling content), but the mechanics differ.

Why are my global GET requests being rate-limited so quickly? X's rate limits are aggressive for GET endpoints called without an account_id — sometimes as low as 5 requests per 15-minute window. These are intended for discovery and metadata, not iteration. If you're hitting global reads frequently, restructure your client to use account-scoped endpoints where possible (which have much higher limits) or cache aggressively at the global-read layer.

Where Unified fits

Unified.to provides a single API across X Ads (Twitter Ads), TikTok Ads, Snapchat, Pinterest Ads, Reddit Ads, Meta Ads, LinkedIn Ads, Google Ads, Microsoft Advertising, Amazon Advertising, Google Campaign Manager 360, Google Display & Video 360, and 3 other advertising integrations — 15 in total — covering campaigns, ad groups, ads, creatives, targeting, and reporting through a normalized data model.

For X Ads specifically, Unified handles OAuth 1.0a signature generation, the Account → Campaign → Line Item → Promoted Tweet hierarchy, refresh-token-equivalent behavior (OAuth 1.0a tokens don't expire on a timer but do need re-authorization on revocation), and the v12 endpoint structure behind a single authorization step. Real X Ads objects map to Unified's normalized models: ads_organization, ads_campaign, ads_group (X's Line Item), ads_ad, and ads_creative with full CRUD, plus ads_promoted for Promoted Tweets specifically — a normalized object unique to platforms that support the boost-organic-content pattern. ads_report and ads_target handle reporting and targeting. Vendor-specific endpoints — including the Pixel and Conversions API for server-side conversion tracking, the more advanced bidding configurations, and X-specific creative types like Cards and Conversation Cards — are available through pass-through access.

If you're evaluating whether to build X Ads integration directly or use a unified API, the question is whether the ongoing maintenance — OAuth 1.0a signature handling (genuinely different from every other modern platform), branding migration cleanup, periodic field-availability changes, and integrating across all the other ad platforms with their different auth models — is something your team should own, or something to abstract behind a single connection.

→ Start your 30-day free trial

→ Book a demo

All articles