Schedule Tweet API

POST scheduled/create schedules a tweet from the account behind your registered twitterapis session to post at a future instant. execute_at is epoch SECONDS, not milliseconds, and must be in the future. It returns ok, scheduled_tweet_id and the execute_at you sent, for $0.0016 a call. The post goes out unless you delete it first.

curl -X POST "https://example.com/scheduled/create" \  -H "Content-Type: application/json" \  -d '{    "text": "The Q1 changelog is live.",    "execute_at": "1829752200"  }'

{  "ok": true,  "scheduled_tweet_id": "2086650228950683649",  "execute_at": 1829752200}

{  "error": "bad_request",  "message": "Missing or malformed parameter. Fix the request before retrying."}

{  "error": "unauthorized",  "message": "The API key is missing, malformed, or revoked. Check the Authorization header."}

{  "error": "insufficient_credits",  "message": "Your balance is exhausted. Top up your credits to continue."}

{  "error": "forbidden",  "message": "The acting account is not authorized for this write action, or has no logged-in session."}

{  "error": "not_found",  "message": "The resource does not exist, for example a deleted tweet or a private account."}

{  "error": "rate_limited",  "message": "Too many requests. Back off and retry with exponential backoff."}

{  "error": "server_error",  "message": "Something failed on our side. Retry with backoff; if it persists, contact support."}

Pricing

When to use

Use scheduled/create when the post should go out on its own at a known time and no human will be there to press send. Use draft/create when a person still has to approve the wording, because a draft never posts by itself, and tweet/create when it should go out now.

Notes

• THIS POSTS PUBLICLY at execute_at unless you delete it first with scheduled/delete. It is not a draft.
• execute_at is epoch SECONDS. Date.now() in JavaScript returns MILLISECONDS, which is where a wrong unit usually comes from; divide by 1000. A millisecond value is refused with a message naming the unit, never silently scheduled.
• execute_at must be strictly in the future. A past or present instant is refused with 400.
• Needs a session for the account you are acting as: either register one once (POST /customer/session), or pass per-call inline credentials as x-auth-token and x-ct0 request headers, which let a single API key act as many accounts. Returns 409 session_required if neither is supplied, 401 session_dead when the session has expired.

Related endpoints

• List Scheduled Tweets: List the posts queued to publish on your own account.
• Cancel Scheduled Tweet: Cancel a scheduled tweet before it posts.
• Create Draft Tweet: Save a private draft on your own account. Nothing is posted.
• Create Tweet: Post a tweet as your registered account: text, media, reply, or quote.

FAQ

Is execute_at in seconds or milliseconds?

Seconds, on the way in and on the way out. A value that looks like milliseconds is rejected with a 400 naming the unit, so a wrong unit fails loudly instead of scheduling a post tens of thousands of years away.

How do I cancel a scheduled post?

Call scheduled/delete with the scheduled_tweet_id this call returned, or with an id from scheduled/list. Cancel it before execute_at; once it has posted it is an ordinary tweet and tweet/delete is what removes it.

Is this the same as saving a draft?

No, and it is the difference that matters most here. A draft never posts by itself. A scheduled post goes out publicly at its execute_at whether or not anyone is watching, unless it is deleted first.