Threads Scheduling API
This Threads Scheduling API reference is for builders who need future-dated Threads publishing without operating a queue themselves.
POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
Content-Type: application/json
{
"content": "A short example update.",
"platforms": [
{
"platform": "threads",
"accountId": "th_123"
}
],
"scheduledFor": "2026-09-15T09:00:00",
"timezone": "Europe/London"
}POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
Content-Type: application/json
A request carries the post content, a scheduledFor timestamp, and optionally an IANA timezone for local-time interpretation; a successful reply identifies the queued item and gives its publishing moment in UTC. The pages below cover the captured request and response, field meanings, timezone conversion, supported content types, and pre-launch checks for a calendar built on the API.
Build Threads scheduling into your product, agency workflow, automation, or AI system without maintaining your own publishing queue
Reach for this API when an application must commit to a Threads publishing moment without building and running its own queue, retry logic, or timezone conversion. The essential flow is compact: submit a post carrying a future scheduledFor, optionally identify the IANA timezone in which that value is expressed, then retain the returned postId together with the UTC scheduledFor for display and later management. Formats, limits, rescheduling, cancellation, and calendar listing all extend that one creation call.
Captured contract: POST {{API_BASE_URL}}/v1/posts
Scheduling in the captured contract goes through a single endpoint: POST {{API_BASE_URL}}/v1/posts. The Text request and 202 response shown below keep their captured structure, with only the origin swapped for {{API_BASE_URL}} ahead of the unchanged /v1/posts path. Use the request fields as your build checklist: content holds the post text, platforms identifies the Threads destination, scheduledFor holds the intended publishing moment, and timezone holds the IANA timezone when that moment is local. A 202 reply whose status is scheduled indicates queuing rather than immediate publication; its scheduledFor gives the resolved UTC publishing moment, which your calendar and user interface should show next to the original local time.
Field map and timezone handling
Timezone interpretation is where scheduling most often drifts by hours, so make the choice explicit on each request. Supplying an IANA timezone such as Europe/London means scheduledFor is read in that zone, and the reply gives the equivalent UTC moment — in the worked example, 2026-09-15T09:00:00 in Europe/London becomes 2026-09-15T08:00:00.000Z. Omitting timezone means scheduledFor is read as UTC. Before sending, confirm three points: the timezone string is a valid IANA name rather than an abbreviation, the local moment you intend is the one you encoded, and the UTC moment in the reply agrees with your own conversion for that date, daylight-saving changes included.
Requests and responses by format
One endpoint serves every format, with only the fields needed for a given publishing format changing. Text posts are fully specified by the captured example. Single-image posts, image carousels, and videos are also schedulable, and a cross-platform request may pair Threads with other supported platforms, with all destinations in that request sharing one scheduledFor and one timezone. Since only the Text request and response are captured in full, avoid assuming media field names or cross-platform response shapes beyond what is shown; verify those schemas before building media or multi-platform scheduling.
Queue lifecycle: calendar, reschedule, and cancel
Build a calendar by creating each post with its own scheduledFor value, then listing scheduled posts when a week or month view needs rendering. Queued items can then be edited, moved to a different publishing moment, or withdrawn before publication without recreating the content. The captured source describes these lifecycle actions functionally but does not provide their exact endpoint paths, methods, parameters, or response contracts, so implement them only after those contracts are confirmed; meanwhile, model your data around the postId returned at creation so queued items can be tracked, moved, or removed. Build a content calendar by giving each planned post its own scheduledFor value. The Threads API uses that scheduled workflow separately from immediate publishing.
Media and text limits, reply controls, and alt text
Check content before queuing it, because a post that fails at publication time is harder to repair than one rejected at creation. Copy is capped at 500 characters. For attachments, pick one pattern per post: a lone image, a carousel holding 2 to 10 images, or a single video no larger than 1 GB and no longer than 5 minutes. Still images and video cannot share a post, and GIF attachments are not accepted. Reply controls can restrict who may respond — everyone, accounts you follow, or mentioned accounts — and attached images can carry alt text, although the exact field names and enum values for those options are not captured in the source and must be confirmed before use.
Implementation and verification checklist
Before treating scheduling as production-ready, run a verification checklist against the preserved contract. Confirm that a future scheduledFor with an IANA timezone returns 202 with status scheduled and a UTC scheduledFor matching your own conversion, that omitting timezone is handled as UTC, that each platform entry in the response reports success, and that the postId you store is the identifier your calendar, reschedule, and cancel flows will use. Also verify the media and text limits above at creation time, confirm the still-unspecified reschedule, list, edit, and cancel contracts, and check behavior for edge cases the source does not state, such as past timestamps, before you expose scheduling to end users.
| Field | Location | Type as shown | Requiredness | Notes |
|---|---|---|---|---|
| content | Request body | string | Shown in captured Text example | Post text; Threads limit is 500 characters. |
| platforms | Request body | array of objects | Shown in captured Text example | Targets for the post; cross-platform requests share one scheduledFor and timezone. |
| platforms[].platform | Request body | string | Shown in captured Text example | Example value: "threads". |
| platforms[].accountId | Request body | string | Shown in captured Text example; FAQ describes it as the Threads account identifier | Example value: "th_123". |
| scheduledFor | Request body | string (ISO 8601) | Required for scheduling per FAQ | Example: "2026-09-15T09:00:00". Interpreted in timezone when supplied, otherwise as UTC. |
| timezone | Request body | string (IANA timezone) | Optional per FAQ | Example: "Europe/London". If omitted, scheduledFor is treated as UTC. |
| success | 202 response body | boolean | Shown in captured response | Example: true. |
| status | 202 response body | string | Shown in captured response | Example: "scheduled". |
| postId | 202 response body | string | Shown in captured response | Example: "post_xyz789". Use to track the queued post. |
| scheduledFor | 202 response body | string (UTC) | Shown in captured response | Resolved publishing time in UTC, e.g. "2026-09-15T08:00:00.000Z". |
| platforms[].success | 202 response body | boolean | Shown in captured response | Per-target result; example shows true for threads. |
Requiredness is shown only where the captured example and FAQ state it; the source does not publish a full schema, so do not treat unstated requiredness as confirmed.
| Case | scheduledFor sent | timezone sent | Interpretation | Response scheduledFor |
|---|---|---|---|---|
| IANA timezone supplied | "2026-09-15T09:00:00" | "Europe/London" | Local time in Europe/London | "2026-09-15T08:00:00.000Z" (UTC) |
| Timezone omitted | ISO 8601 value | — | Treated as UTC | Resolved publishing time in UTC |
Derived from the captured Europe/London example and the FAQ rule for omitted timezone.
| Format | Scheduling support | Contract status | Key constraints |
|---|---|---|---|
| Text | Supported | Fully captured example | Up to 500 characters. |
| Single image | Supported | Schema not captured | One image per post. |
| Image carousel | Supported | Schema not captured | 2–10 images. |
| Video | Supported | Schema not captured | One video; up to 1 GB and 5 minutes. |
| Cross-platform | Supported | Schema not captured | Every target shares the same scheduledFor and timezone. |
Only the Text format has a fully captured request/response; other formats are supported per source but their field schemas are not captured.
| Check | Expected behavior | Status in source |
|---|---|---|
| Mixing images and video in one post | Not permitted | Stated in FAQ |
| GIF attachment | Not supported | Stated in FAQ |
| Carousel with fewer than 2 or more than 10 images | Outside stated limits | Stated in FAQ (2–10) |
| Video over 1 GB or 5 minutes | Outside stated limits | Stated in FAQ |
| Text over 500 characters | Outside stated limit | Stated in FAQ |
| Cancel after publication | Cancel is described as before publication | Stated in FAQ |
| Past scheduledFor value | Not stated | Gap — verify before publication |
| Reschedule/list/edit/cancel endpoint contracts | Described functionally only | Gap — exact paths, methods and parameters not captured |
Rows marked not stated must be verified before publication; do not invent behavior for them.
Frequently asked questions
How do I schedule a Threads post?
Create the post through /v1/posts, naming the Threads account in accountId and giving scheduledFor as an ISO 8601 timestamp. Include an IANA timezone if that timestamp is meant to be read as local time.
How does timezone handling work?
Supply an IANA zone name, for example Europe/London, together with scheduledFor. Leaving timezone out means the timestamp is read as UTC, and the reply carries the resolved moment back in UTC.
What Threads content can I schedule?
Four kinds of content are covered: text alone, a single image, a set of images arranged as a carousel, and a video.
What are the Threads media limits?
Use a single attachment approach for each post. A still-image post holds one picture, a carousel holds 2 to 10 pictures, and a video post holds one clip no larger than 1 GB and no longer than 5 minutes. Still pictures and moving footage cannot share a post, and GIF files are not accepted.
How much text can a Threads post contain?
Keep the copy within 500 characters.
Can I control who can reply to a scheduled Threads post?
Reply scope can be narrowed to all users, to accounts you follow, or to accounts mentioned in the post. Images can also carry alt text, though the precise field names for those options still need confirmation from the full schema.
Can I edit, reschedule, or cancel a scheduled Threads post?
A queued item can be revised, shifted to another time, or withdrawn, provided the action happens before it goes live.
Who is the Threads Scheduling API for?
It suits teams building programmatic scheduling into software: product developers, SaaS operators, agencies, automation builders, and AI-focused products.
{
"success": true,
"status": "scheduled",
"postId": "post_xyz789",
"scheduledFor": "2026-09-15T08:00:00.000Z",
"platforms": [
{
"platform": "threads",
"success": true
}
]
}