X Publish

Overview

Publishes a post to X (formerly Twitter) on behalf of a connected eranol.com account. Optionally attaches up to 4 images, and can be published immediately or scheduled for a future time.

Before this endpoint can be used, the target account must have connected X via Dashboard → Social Media → Connect (OAuth 2.0). Calls for an account with no active X connection return a 400 error.

Endpoint

https://eranol.com/api/v1/social/x/publish

Pricing note

X charges us per post — about $0.015 for a plain post, or $0.20 if the post text contains a URL. Pricing here follows that split:

• 1 credit for a post with no URL in the text
• 20 credits for a post whose text contains a URL

Posting a URL also requires the account to have purchased credits at least once — accounts running only on trial/free credits get a 403 if they try to post a link. This keeps the endpoint's economics sane: plain posts are cheap enough to be open to everyone, link posts cost us more so they're gated to paying customers.

Request body

Field	Type	Required	Notes
text	string	Yes	Post text. Max 280 characters by default. Accounts with an X Premium/Blue subscription can post up to ~25,000 characters — see Long-form posts below
media_urls	string[]	No	Up to 4 image URLs. Each URL must be hosted on eranol.com or www.eranol.com — external URLs are rejected
scheduled_for	string	No	ISO 8601 timestamp in the future. When set, the post is queued and published later instead of immediately — see Scheduling below

Long-form posts (Premium/Blue accounts)

If text is longer than 280 characters, the connected X account must have an active Premium/Blue subscription. This is checked live against X's API at request time (not cached), so a downgrade or upgrade takes effect immediately. If the account isn't eligible, the request is rejected with a 400 before anything is posted. X's own limits for its subscription tiers are the final authority — a request that passes our check can still be rejected by X itself if the account isn't entitled to post that length.

Long-form posting does not change the credit cost by itself — cost is based purely on whether text contains a URL, regardless of length.

Scheduling

Pass scheduled_for as a future ISO timestamp to queue the post instead of publishing it right away. Scheduled posts:

• Are charged credits immediately, at the time of scheduling (this guarantees funds are available when the post actually fires)
• Return 202 Accepted instead of 200, with a different response shape (see below)
• Are published automatically by a background dispatcher at the scheduled time, using the same publish logic as an immediate post
• If the account's Premium/Blue status changes between scheduling and the scheduled time, X's own limits at publish time are what apply

Example request

{
  "text": "Just shipped a new feature 🚀",
  "media_urls": ["https://www.eranol.com/uploads/screenshot.png"]
}

Example request — scheduled

{
  "text": "Announcing this next week 📅",
  "scheduled_for": "2026-09-01T15:00:00Z"
}

Example response

{
  "success": true,
  "tweet_id": "1234567890123456789",
  "post_url": "https://x.com/i/web/status/1234567890123456789",
  "log_id": "b7e1c2a4-..."
}

Example response — scheduled

{
  "success": true,
  "scheduled": true,
  "scheduled_post_id": "a1b2c3d4-...",
  "scheduled_for": "2026-09-01T15:00:00.000Z"
}

Errors

Status	Meaning
400	Missing/invalid text, text too long (over 25,000 characters), invalid media_urls host, invalid/past scheduled_for, the account has no connected X account, or text exceeds 280 characters without an eligible Premium/Blue subscription
401	X rejected the request — the connection's token may need to be refreshed by reconnecting via the dashboard
402	Insufficient credits
403	The post text contains a URL, but the account has never purchased credits (trial/free credits alone don't cover link posts)
502	X's API returned an error, or one of the media_urls couldn't be fetched or uploaded (e.g. duplicate post, rate limited) — no credits are charged on failure

---

What changed vs. the previous version of this doc

1. Long-form posts (new). text is no longer capped at a flat 280 characters. Accounts with X Premium/Blue can post up to ~25,000 characters; the API checks the connected account's live subscription status (not cached) whenever text exceeds 280.
2. scheduled_for field (new). Optional ISO timestamp to queue a post for later instead of publishing immediately. Returns 202 with a distinct response shape (scheduled_post_id, scheduled_for — no tweet_id/post_url until it actually fires). Credits are charged at scheduling time, not at publish time.
3. Pricing is no longer a flat 20 credits. Actual cost is 1 credit if the post text has no URL, 20 credits if it does — mirroring X's own $0.015 vs $0.20 cost split. Most posts will now cost 1 credit, not 20.
4. New 403 error. Posting a URL requires the account to have purchased credits at least once; trial-only accounts get blocked with 403 instead of being silently charged more than their trial credits are worth. This gate does not apply to plain (URL-free) posts — those are open to everyone.
5. 502 scope widened. Now also covers failures fetching or uploading the media_urls themselves, not just errors from X's tweet-creation call.
6. Unchanged, confirmed correct: endpoint path, media_urls host restriction (eranol.com/www.eranol.com only), 4-image cap, images-only (no video/GIF support), 401/402 meanings, and the success response field names (tweet_id, post_url, log_id) for immediate posts.