Twitter Scheduling API
The Twitter Scheduling API lets you build Twitter/X scheduling into a product, automation, agency workflow, or AI system without maintaining your own scheduling infrastructure.
POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
Content-Type: application/json
{
"content": "A short example update.",
"platforms": [
{
"platform": "twitter",
"accountId": "tw_123"
}
],
"scheduledFor": "2026-09-10T09:00:00",
"timezone": "America/New_York"
}POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
Content-Type: application/json
You schedule tweets, threads, and polls for any future time, use timezone-aware delivery with IANA timezone support, and then reschedule, cancel, or list queued posts via API. OAuth is handled through the connected account, so no separate Twitter developer app is needed on your side.
Add Social Media to Your Product in Three Steps
One connection covers publishing, scheduling, analytics, comments, and messages through a shared interface. Begin by obtaining an API key for your application. Next, link accounts once and use that connection for the workflows above. Finally, expose multiple networks to end users without separately building each platform integration. Keeping setup in this order lets your team concentrate on content timing instead of platform plumbing.
Create a Scheduled Post
A single endpoint handles each format; only the format-specific fields change. For scheduling, call POST /v1/posts with content, a platforms entry for the linked Twitter account, an ISO 8601 scheduledFor value, and an IANA timezone. In the Create a scheduled Twitter post example, 2026-09-10T09:00:00 in America/New_York becomes 2026-09-10T13:00:00.000Z in the Scheduled response example. Verify status, postId, and per-platform success, and retain postId for later changes.
Timezone Handling and Exact-Time Delivery
Supplying scheduledFor places the item in a queue for that moment, so your own polling loop or cron job is unnecessary. An IANA timezone such as America/New_York means the time is interpreted locally, then converted and returned in UTC. Omitting timezone changes the interpretation to UTC. Choose based on how the time was entered: named zone for local intent, omission only for values already in UTC. Check the returned UTC instant against the intended local time.
Formats, Planned Content, and Cross-Posting
Threads, polls, images, videos, and GIFs follow the same scheduling path as a plain tweet because scheduledFor is added to the regular publishing payload. For a campaign spanning several days, submit separate requests, each carrying its own scheduledFor value. One request can also target Twitter, Instagram, LinkedIn, and other networks for a shared future moment. Before a batch, confirm every entry has the correct time and that media and platform options were included at submission.
Manage Queued Posts
Queued items can be reviewed, revised, moved, or stopped before they publish. PUT /v1/posts/scheduled/{postId} updates a still-queued item, including its text, media, destinations, platform-specific settings, and optionally its time. PATCH /v1/posts/scheduled/{postId} changes only the timing. DELETE /v1/posts/scheduled/{postId} stops the send and returns the item to draft. Confirm queued status before an update or move, and confirm draft status after a stop.
Failure Handling and Delivery Checks
When X is briefly unreachable at the due moment, delivery is retried automatically, removing the need for client-side retry code or a duplicate queue. Submission checks remain your responsibility. Ensure scheduledFor is a future ISO 8601 value, timezone is a valid IANA name when present, accountId points to the linked Twitter account, and the response shows scheduled status with per-platform success. Fix invalid inputs directly rather than expecting the queue to correct them.
| Field | Location | Type / example | Requiredness | Purpose |
|---|---|---|---|---|
| content | Request body | string: "Our launch goes live tomorrow morning." | Required | Post text to publish at the scheduled time. |
| platforms | Request body | array of { platform, accountId } | Required (min 1) | Target platforms and connected accounts. |
| platform | platforms[] | string: "twitter" | Required | Identifies Twitter/X as the target platform. |
| accountId | platforms[] | string: "tw_123" | Required | Identifies the connected Twitter account. |
| scheduledFor | Request body | ISO 8601 string: "2026-09-10T09:00:00" | Optional; required to schedule | Future publishing time for the queued post. |
| timezone | Request body | IANA timezone string: "America/New_York" | Optional; default UTC | Local timezone used to resolve scheduledFor. |
| success | Response body | boolean: true | Present in example | Overall request success flag. |
| status | Response body | string: "scheduled" | Present in example | Queue status of the created post. |
| postId | Response body | string: "post_xyz789" | Present in example | Identifier used by PUT, PATCH, and DELETE scheduled-post calls. |
| scheduledFor | Response body | UTC ISO 8601 string: "2026-09-10T13:00:00.000Z" | Present in example | Resolved UTC publishing time returned after timezone handling. |
Request requiredness aligned to supplied cross-page typed contract; response fields are as shown in the captured example, with no separate typed response contract supplied.
| Operation | Method and path | When to use it | Expected lifecycle effect |
|---|---|---|---|
| Create scheduled post | POST /v1/posts | Queue a new post with scheduledFor | Returns status scheduled with a postId. |
| Edit scheduled post | PUT /v1/posts/scheduled/{postId} | Change content, media, target platforms, platform-specific options, and optionally publishing time while still scheduled | Queued post is updated before publication. |
| Reschedule scheduled post | PATCH /v1/posts/scheduled/{postId} | Move a queued post to a new date or time | Publishing time changes; post remains queued. |
| Cancel scheduled post | DELETE /v1/posts/scheduled/{postId} | Cancel before publishing | Cancelled post is moved back to draft. |
| Transient failure at due time | Automatic retry (no client endpoint specified) | X is temporarily unavailable when the post is due | Transient publishing failures are retried automatically. |
Lifecycle effects are as captured in the source FAQ answers; response bodies for PUT, PATCH, and DELETE were not supplied.
| Decision | Use this option when | Check before sending |
|---|---|---|
| Scheduling with scheduledFor | The post must publish at a future time without client polling or cron | scheduledFor is a future ISO 8601 datetime and the returned UTC time matches the intended local time. |
| Immediate posting | The post should publish when the request is made | Confirm immediate delivery is acceptable; the captured contrast is scheduledFor versus publishNow. |
| timezone supplied | The user specifies a local time in a named IANA timezone | timezone is a valid IANA timezone such as America/New_York, Europe/London, or Asia/Tokyo. |
| timezone omitted | The supplied time is already intended as UTC | Confirm the value is UTC, because omitted timezone means the time is treated as UTC. |
Decision criteria summarize the captured scheduling versus immediate-posting and timezone behaviors; immediate-posting request shape beyond the scheduledFor contrast was not captured.
Frequently asked questions
How do I schedule a tweet through the API?
Send the request to POST /v1/posts, include scheduledFor for the future moment, and list the linked Twitter account inside platforms using its accountId. Adding an IANA timezone is optional; without it, the value is read as UTC.
Does the official X API have a scheduled publishing field?
A direct X create-post call sends the post at request time and does not expose scheduledFor or timezone controls. The scheduling layer described here sits in front of that flow, holding the item until its chosen moment.
How does timezone handling work?
Supply a recognized IANA name — for example America/New_York, Europe/London, or Asia/Tokyo — alongside the local wall-clock time. The service converts that to UTC and echoes the UTC instant back. Leaving timezone out means UTC interpretation.
Can I schedule Twitter threads, polls, images, videos, and GIFs?
Yes. Add scheduledFor to an otherwise normal publishing payload and the same format options apply, covering plain tweets as well as threads, polls, images, videos, and GIFs.
Can I edit a scheduled tweet before it goes live?
While the item remains queued, call PUT /v1/posts/scheduled/{postId}. That lets you revise text, attached media, destination platforms, platform-specific settings, and, if needed, the send time.
Can I reschedule or cancel a tweet after scheduling it?
PATCH /v1/posts/scheduled/{postId} shifts the send time, while DELETE /v1/posts/scheduled/{postId} stops the queued send. A stopped item returns to draft status instead of disappearing entirely.
What happens if X is temporarily unavailable when my tweet is due?
Brief delivery interruptions are retried on the service side. Clients therefore do not need separate retry machinery or an extra queue for due-time X delivery.
Do I need my own Twitter/X developer app?
No separate X developer application is required from you. The hosted connection manages OAuth and token renewal, and your code references the linked account through accountId.
How much does it cost to schedule a tweet?
Credit pricing for X scheduling is {{OWNER_X_CREDIT_PRICING}}. Confirm the current owner-supplied pricing before budgeting, including whether a URL in the body changes the charge.
Who is the Twitter/X Scheduling API for?
It suits product developers, SaaS teams, agencies, automation builders, and AI products that need to schedule social posts programmatically.
{
"success": true,
"status": "scheduled",
"postId": "post_xyz789",
"scheduledFor": "2026-09-10T13:00:00.000Z",
"platforms": [
{
"platform": "twitter",
"success": true
}
]
}PUT {{API_BASE_URL}}/v1/posts/scheduled/{postId}
PATCH {{API_BASE_URL}}/v1/posts/scheduled/{postId}
DELETE {{API_BASE_URL}}/v1/posts/scheduled/{postId}