X/Twitter
Mutation
Use the scheduleTweet mutation to schedule tweets to X/Twitter:
mutation ScheduleTweet($input: ScheduleTweetInput!) {
scheduleTweet(input: $input) {
success
errors {
field
message
}
post {
id
socialAccount {
id
username
}
publishingStatus
submissions {
id
text
order
postAt
gallery {
id
galleryMediaSet {
id
media {
id
url
mimeType
}
}
}
}
}
}
}
Input Parameters
ScheduleTweetInput
schedulingMode: QUEUE_NEXT when scheduling a new post, or the post is a draft.
See Drafts without a date.SPECIFIC_TIME, QUEUE_NEXT (default: SPECIFIC_TIME).
Only accepted when scheduling a new post. See Scheduling at the Next Open Slot.EVERYONE, FOLLOWING, MENTIONEDREADY_TO_PUBLISH, DRAFT (default: READY_TO_PUBLISH)TweetInputType
Each tweet in the thread supports these parameters:
id, name, or url. See Attaching Media.
Only supported when scheduling new posts, not when updating existing ones.hour, dayhour, dayExamples
Simple Tweet
Schedule a basic tweet with text only.
{
"input": {
"username": "myhandle",
"postAt": "2025-12-01T15:30:00Z",
"thread": [
{
"text": "Hello world! This is my first scheduled tweet 🚀",
"order": 0
}
]
}
}
Scheduling at the Next Open Slot
Instead of picking a time yourself, pass schedulingMode: QUEUE_NEXT and leave postAt out. Postpone puts the post in the next open slot on the account's Account Schedule, skipping any slot that already has a post on it.
{
"input": {
"username": "myhandle",
"schedulingMode": "QUEUE_NEXT",
"thread": [
{
"text": "This one goes out at my next open slot.",
"order": 0
}
]
}
}
The whole thread lands on that one slot, the same way an explicit postAt applies to every tweet in the thread.
The account needs a schedule set up for this to work, postAt and QUEUE_NEXT can't be combined, and updateScheduledTweet rejects schedulingMode outright. See Scheduling at the Next Open Slot for the full rules.
Tweet with Media URL
Schedule a tweet by uploading media from an external URL. Use this when you have a direct link to an image, video, or GIF that you want to attach. The media will be automatically downloaded and added to your Content Library.
{
"input": {
"username": "myhandle",
"postAt": "2025-12-01T15:30:00Z",
"thread": [
{
"text": "Check out this amazing sunset! 🌅",
"order": 0,
"media": [{ "url": "https://example.com/sunset.jpg" }]
}
]
}
}
Tweet with Content Library Media
Schedule a tweet using media already in your Content Library. Use this when you want to reuse media you've previously uploaded. Reference the file by its id, which every upload mutation returns.
{
"input": {
"username": "myhandle",
"postAt": "2025-12-01T15:30:00Z",
"thread": [
{
"text": "Sharing our company logo! 🏢",
"order": 0,
"media": [{ "id": "1042" }]
}
]
}
}
You can also reference the file by name. Names are matched case-insensitively and the first match wins, so prefer id when several files share a name.
{
"media": [{ "name": "company-logo.png" }]
}
Thread with Multiple Tweets
Schedule a multi-tweet thread.
{
"input": {
"username": "myhandle",
"postAt": "2025-12-01T15:30:00Z",
"replySettings": "FOLLOWING",
"thread": [
{
"text": "🧵 Thread about building great APIs (1/3)",
"order": 0
},
{
"text": "First, always design your API with the developer experience in mind. Clear documentation and consistent patterns make all the difference.",
"order": 1
},
{
"text": "Second, implement proper error handling and rate limiting. Your API consumers will thank you when things go wrong (and they will).",
"order": 2,
"final": true
}
]
}
}
Tweet with Poll
Schedule a tweet with an interactive poll.
{
"input": {
"username": "myhandle",
"postAt": "2025-12-01T15:30:00Z",
"thread": [
{
"text": "What's your favorite programming language? 💻",
"order": 0,
"poll": {
"choices": ["JavaScript", "Python", "Go", "Rust"],
"durationMinutes": 1440
}
}
]
}
}
Auto-Retweet Configuration
Schedule a tweet with automatic retweeting.
{
"input": {
"username": "myhandle",
"postAt": "2025-12-01T15:30:00Z",
"thread": [
{
"text": "Don't miss our latest blog post about API best practices! 📖",
"order": 0,
"repostAtAmount": 2,
"repostAtUnit": "hour",
"repostRepeatDays": 3,
"repostFromSocialAccount": {
"username": "mycompany"
}
}
]
}
}
Community Post
Schedule a tweet to a specific X/Twitter community.
{
"input": {
"username": "myhandle",
"postAt": "2025-12-01T15:30:00Z",
"communityId": "1234567890",
"thread": [
{
"text": "Excited to share this with the developer community! 🎉",
"order": 0
}
]
}
}
Response Types
Success Response
{
"data": {
"scheduleTweet": {
"success": true,
"errors": [],
"post": {
"id": "123",
"socialAccount": {
"id": "456",
"username": "myhandle"
},
"publishingStatus": "READY_TO_PUBLISH",
"submissions": [
{
"id": "789",
"text": "Hello world! This is my first scheduled tweet 🚀",
"order": 0,
"postAt": "2025-12-01T15:30:00Z",
"gallery": null,
"poll": null
}
]
}
}
}
}
Error Response
{
"data": {
"scheduleTweet": {
"success": false,
"errors": [
{
"field": "text",
"message": "You cannot schedule a Tweet longer than 280 characters."
}
],
"post": null
}
}
}
Updating a Post
To update an existing scheduled post, use the same input type with the corresponding update mutation and include the post id:
mutation UpdateScheduledTweet($input: ScheduleTweetInput!) {
updateScheduledTweet(input: $input) {
success
errors {
field
message
}
post {
id
}
}
}
Pass the id of the post you want to update in the input, along with the fields you want to change:
{
"input": {
"id": "12345",
"username": "myhandle",
"postAt": "2026-01-15T10:30:00Z",
"thread": [{"text": "Updated tweet text!", "order": 0}]
}
}
id field to specify which post to update. Only scheduled posts that have not been published yet can be updated.postAt is required on an update, so every update states the date the post goes out on — pass the date it already has to leave it where it is. A draft staying a draft is exempt, and a draft you're promoting to READY_TO_PUBLISH needs a date of your choosing; see Drafts without a date.
schedulingMode is not accepted on an update at all; see Scheduling at the Next Open Slot.
Validation Rules
- Text Length: 280 characters for regular accounts, 25,000 for verified accounts
- Media: Maximum 4 images/videos per tweet, GIFs limited to 15MB
- Video: Maximum 512MB file size, up to 2 minutes 20 seconds for regular accounts, up to 10 minutes for accounts with long video feature
- Polls: 2-4 options, each max 25 characters, duration 5 minutes to 7 days. Cannot be combined with media attachments.
- Threads: No hard limit on thread length
- Scheduling: Posts must be scheduled for future dates only
- Account Limits: Respects your plan's monthly tweet limits
Common Errors
The specified username is not connected to your Postpone account. Connect the account in your settings first.
The tweet text exceeds the maximum length. Regular accounts have a 280 character limit, verified accounts can post up to 25,000 characters.
The postAt timestamp must be in the future. Check your timezone settings.
A new tweet has to say when it goes out: pass a postAt, or schedulingMode: QUEUE_NEXT. Drafts are exempt: leave postAt off one and it is parked on a placeholder date about 30 days out.
schedulingMode isn't accepted on an update, so a postAt is the only way to say when the tweet goes out. You'll also see it when promoting a parked draft to publishingStatus: READY_TO_PUBLISH without giving it a date.
schedulingMode: QUEUE_NEXT needs an Account Schedule on the account you're posting from. Set one up, or pass an explicit postAt.
schedulingMode is only accepted by scheduleTweet. To move a tweet that is already scheduled, pass a postAt to updateScheduledTweet.
X/Twitter doesn't allow polls on tweets with images, videos, or GIFs. Choose either media or a poll.
You've reached your plan's tweet limit for the scheduled month. Upgrade your plan or schedule for a different month.