Skip to content

Threads Scheduling API

This Threads Scheduling API reference is for builders who need future-dated Threads publishing without operating a queue themselves.

Schedule a Threads text post — request
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"
}
Illustrative request
Example line 1

POST {{API_BASE_URL}}/v1/posts

Illustrative request
Example line 2

x-access-key: YOUR_API_KEY

Illustrative request
Example line 3

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.

POST /v1/posts field map (captured Text contract)
FieldLocationType as shownRequirednessNotes
contentRequest bodystringShown in captured Text examplePost text; Threads limit is 500 characters.
platformsRequest bodyarray of objectsShown in captured Text exampleTargets for the post; cross-platform requests share one scheduledFor and timezone.
platforms[].platformRequest bodystringShown in captured Text exampleExample value: "threads".
platforms[].accountIdRequest bodystringShown in captured Text example; FAQ describes it as the Threads account identifierExample value: "th_123".
scheduledForRequest bodystring (ISO 8601)Required for scheduling per FAQExample: "2026-09-15T09:00:00". Interpreted in timezone when supplied, otherwise as UTC.
timezoneRequest bodystring (IANA timezone)Optional per FAQExample: "Europe/London". If omitted, scheduledFor is treated as UTC.
success202 response bodybooleanShown in captured responseExample: true.
status202 response bodystringShown in captured responseExample: "scheduled".
postId202 response bodystringShown in captured responseExample: "post_xyz789". Use to track the queued post.
scheduledFor202 response bodystring (UTC)Shown in captured responseResolved publishing time in UTC, e.g. "2026-09-15T08:00:00.000Z".
platforms[].success202 response bodybooleanShown in captured responsePer-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.

Timezone decision table
CasescheduledFor senttimezone sentInterpretationResponse scheduledFor
IANA timezone supplied"2026-09-15T09:00:00""Europe/London"Local time in Europe/London"2026-09-15T08:00:00.000Z" (UTC)
Timezone omittedISO 8601 value—Treated as UTCResolved publishing time in UTC

Derived from the captured Europe/London example and the FAQ rule for omitted timezone.

Content-format comparison
FormatScheduling supportContract statusKey constraints
TextSupportedFully captured exampleUp to 500 characters.
Single imageSupportedSchema not capturedOne image per post.
Image carouselSupportedSchema not captured2–10 images.
VideoSupportedSchema not capturedOne video; up to 1 GB and 5 minutes.
Cross-platformSupportedSchema not capturedEvery 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.

Failure and edge-case matrix
CheckExpected behaviorStatus in source
Mixing images and video in one postNot permittedStated in FAQ
GIF attachmentNot supportedStated in FAQ
Carousel with fewer than 2 or more than 10 imagesOutside stated limitsStated in FAQ (2–10)
Video over 1 GB or 5 minutesOutside stated limitsStated in FAQ
Text over 500 charactersOutside stated limitStated in FAQ
Cancel after publicationCancel is described as before publicationStated in FAQ
Past scheduledFor valueNot statedGap — verify before publication
Reschedule/list/edit/cancel endpoint contractsDescribed functionally onlyGap — 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.

Schedule a Threads text post — 202 response
{
    "success": true,
    "status": "scheduled",
    "postId": "post_xyz789",
    "scheduledFor": "2026-09-15T08:00:00.000Z",
    "platforms": [
      {
        "platform": "threads",
        "success": true
      }
    ]
}