Twitter/X API

Schedule and automate Twitter/X posts with RelayAPI — tweets, threads, polls, images, videos, GIFs, and reply settings.

Quick Reference

Before You Start

Quick Start

Post a tweet immediately:

import Relay from '@relayapi/sdk';

const client = new Relay();
const post = await client.posts.create({
  content: 'Hello from RelayAPI!',
  targets: ['twitter'],
  scheduled_at: 'now',
});

console.log(post.id); // post_abc123

Content Types

Text Tweet

Simple text-only tweet. RelayAPI enforces a 280-character limit.

const post = await client.posts.create({
  content: 'Just shipped a new feature! Check it out.',
  targets: ['twitter'],
  scheduled_at: 'now',
});

Tweet with Images

Up to 4 images per tweet. Cannot mix images and videos. Cannot mix images and GIFs.

const post = await client.posts.create({
  content: 'Check out these photos!',
  targets: ['twitter'],
  media: [
    { url: 'https://cdn.example.com/photo1.jpg', type: 'image' },
    { url: 'https://cdn.example.com/photo2.jpg', type: 'image' },
  ],
  scheduled_at: 'now',
});

Tweet with Video

Single video per tweet. MP4 or MOV, up to 512 MB, max 140 seconds.

const post = await client.posts.create({
  content: 'Watch this!',
  targets: ['twitter'],
  media: [
    { url: 'https://cdn.example.com/video.mp4', type: 'video' },
  ],
  scheduled_at: 'now',
});

Tweet with GIF

1 GIF per tweet (consumes all 4 image slots). Max 15 MB, 1280 x 1080 px. Auto-plays in timeline.

const post = await client.posts.create({
  content: 'Check this out!',
  targets: ['twitter'],
  media: [
    { url: 'https://cdn.example.com/animation.gif', type: 'gif' },
  ],
  scheduled_at: 'now',
});

Thread (Multi-Tweet)

Create Twitter threads with multiple connected tweets using target_options.twitter.thread. Each item becomes a reply to the previous tweet and can have its own content and media.

const post = await client.posts.create({
  targets: ['twitter'],
  scheduled_at: 'now',
  target_options: {
    twitter: {
      thread: [
        { content: '1/ Starting a thread about API design...' },
        { content: '2/ First, always use proper HTTP methods.' },
        {
          content: '3/ Second, version your APIs from day one.',
          media: [{ url: 'https://cdn.example.com/diagram.png', type: 'image' }],
        },
        { content: '4/ Finally, document everything! /end' },
      ],
    },
  },
});

Reply to Tweet

Reply to an existing tweet using reply_to. Provide the tweet ID of the tweet you want to reply to.

const post = await client.posts.create({
  content: "Great point! Here's my take...",
  targets: ['twitter'],
  scheduled_at: 'now',
  target_options: {
    twitter: {
      reply_to: '1748391029384756102',
    },
  },
});

Reply Settings

Control who can reply to your tweet using reply_settings.

const post = await client.posts.create({
  content: 'Important announcement for our followers.',
  targets: ['twitter'],
  scheduled_at: 'now',
  target_options: {
    twitter: {
      reply_settings: 'following',
    },
  },
});

Poll

Create a tweet with a poll using target_options.twitter.poll. Polls support 2-4 options (each up to 25 characters) and a duration from 5 minutes to 7 days.

const post = await client.posts.create({
  content: 'What should we build next?',
  targets: ['twitter'],
  scheduled_at: 'now',
  target_options: {
    twitter: {
      poll: {
        options: ['Dark mode', 'New analytics', 'More integrations'],
        duration_minutes: 1440,
      },
    },
  },
});

Media Requirements

Images

Aspect Ratios

GIFs

Videos

Recommended Video Specs

target_options Fields

All fields go inside target_options.twitter on your post request.

await client.posts.create({
  content: 'Field update from the launch site',
  targets: ['twitter'],
  scheduled_at: 'now',
  media: [{ url: imageURL, type: 'image' }],
  target_options: {
    twitter: {
      place_id: '01a9a39529b27f36',
      sensitive_media_warning: {
        adult_content: false,
        graphic_violence: false,
        other: true,
      },
    },
  },
});

Character Counting

Twitter uses weighted character counting:

• URLs always count as 23 characters regardless of actual length (t.co shortening)
• Emojis count as 2 characters each
• All other characters count as 1

Common Errors

Known Quirks

• Duplicate tweets are rejected — even very similar content gets blocked. Modify text meaningfully between posts.
• URLs always count as 23 characters regardless of actual length due to t.co shortening.
• Cannot mix images and videos in the same tweet.
• Cannot mix images and GIFs in the same tweet.
• GIF consumes all 4 image slots — you cannot attach a GIF alongside other images.
• No Premium long-form path — RelayAPI validates every X post and thread item against 280 characters.
• Rate limit — approximately 300 tweets per 3-hour window for creation.
• Thread replies must be posted sequentially since each reply needs the parent tweet ID.
• Emojis count as 2 characters — a tweet with 140 emojis uses all 280 characters.
• Polls cannot have media or threads — polls are mutually exclusive with media attachments and thread items.

Published edits and social actions

RelayAPI can edit a published X Post's text, edit an owned reply, hide/unhide a reply, and like/unlike a Post. An X edit creates a replacement Post ID; RelayAPI updates the target and retains the old ID in edit history. Every action requires an idempotency key and produces a durable operation. See Published Edits and Social Actions for the typed SDK calls, exact action matrix, and unknown-outcome handling.

Automations

X (Twitter) is a Tier 1 automation platform with tier-gated webhooks (Pay-per-Use: 3 DM conversation subs + 1 webhook).

Triggers

Send nodes

Base: https://api.x.com/2.