API Reference

X Ads API

The X Ads API requires an approval application and OAuth 1.0a request signing - not OAuth 2.0 Bearer tokens like the posting API. Zernio wraps the signing, the approval, and the Campaign → Line Item → Promoted Tweet hierarchy behind one REST endpoint.

Get API Key Full Documentation

Quick Start

1.
Get API Key
Sign up for free and get your API key in seconds.
2.
Connect Account
Use our OAuth flow to connect X Ads accounts.
3.
Start Posting
Make API calls to post content to X Ads.

Create a Standalone X Campaign

JavaScript

const response = await fetch('https://zernio.com/api/v1/ads/create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    platform: 'xads',
    accountId: 'acc_xads_123',
    adAccountId: '18ce54d4x5t',
    name: 'Q2 Product Awareness',
    goal: 'awareness',
    budget: { amount: 75, type: 'daily' },
    schedule: { startDate: '2026-04-20', endDate: '2026-06-20' },
    creative: {
      tweetText: 'Ship faster with platform engineering done right.',
      imageUrl: 'https://cdn.example.com/q2.jpg',
      websiteCard: {
        url: 'https://example.com/platform',
        title: 'Internal Developer Platforms'
      }
    },
    targeting: {
      locations: ['US'],
      languages: ['en']
    }
  })
});

console.log((await response.json()).ad.platformAdId);

X Ads Endpoints

POST/v1/ads/create

Create a Campaign → Line Item → Promoted Tweet hierarchy

POST/v1/ads/boost

Promote an existing tweet as a Promoted Tweet

GET/v1/ads/{id}

Get campaign/line-item/ad details and current spend

PUT/v1/ads/{id}

Update status, budget, or schedule

GET/v1/ads/{id}/analytics

Spend, impressions, engagements, video views, link clicks, CPM, CPE

GET/v1/ads/campaigns

List all campaigns across connected X ad accounts

View full API reference →

Media Requirements

Type	Format	Max Size	Notes
Image	JPEG, PNG, GIF, WebP	5 MB	Recommended 1200x675 (16:9)
Video	MP4, MOV	1 GB	0.5-140 sec, H.264 + AAC
Tweet text	UTF-8	280 chars	Standard X tweet limit
Website Card	URL + text	70 char title	Landing page card with image

Zernio automatically transcodes and optimizes media for X Ads's requirements.

API Limits

X Ads API uses per-app and per-account rate limits. Zernio pools across customers and handles 429 responses. OAuth 1.0a signature computation happens at our edge - you never compute HMAC-SHA1 yourself.

Zernio handles all rate limiting automatically. We queue and retry requests as needed.

Features

✓Campaign → Line Item → Promoted Tweet hierarchy
✓Awareness, engagement, video view, website-click, app-install objectives
✓Promote any tweet from a connected X account
✓Location and language targeting
✓OAuth 1.0a request signing handled
✓X Ads API approval application handled
✓Real-time spend, CPE, CPM, CPV, link-click metrics

Response Example

Promote an Existing Tweet

cURL

curl -X POST "https://zernio.com/api/v1/ads/boost" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "postId": "POST_ID",
    "accountId": "ACCOUNT_ID",
    "adAccountId": "18ce54d4x5t",
    "platform": "xads",
    "name": "Boost launch tweet",
    "goal": "engagement",
    "budget": { "amount": 50, "type": "daily" },
    "schedule": { "startDate": "2026-04-20", "endDate": "2026-04-27" }
  }'

Start building with X Ads API

Free tier available · No credit card required · 99.97% uptime

Get Free API Key Read Documentation →