Skip to content

Threads Posting API

This Threads Posting API guide shows how a product, automation, agency workflow, or AI system can publish to Threads through a single POST /v1/posts route, without directly maintaining Meta's publishing flow.

Text post request — POST /v1/posts
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"
    }
  ],
  "publishNow": true
}
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

Text, images, carousels, and videos share that endpoint, with only the fields relevant to the selected format changing. The pages below map the captured fields, walk through text and cross-post examples, and distinguish confirmed limits from media fields absent from the captured contract.

Threads Posting API — what it publishes and when to use it

A product, automation, agency workflow, or AI system can add Threads publishing through one endpoint rather than maintaining Meta's publishing flow directly. Text, images, carousels, and videos all go through the same route, reply permissions can be set per post, and Threads accounts connect via Threads OAuth. Getting started follows three steps: obtain an API key, integrate once so publishing, scheduling, analytics, comments, and messaging share the same API, and reach major platforms without maintaining each integration separately. Before sending, decide between immediate delivery with publishNow and queued delivery with scheduledFor, and confirm the accountId for the Threads account that will publish.

Input contract and field map for POST /v1/posts

Every Threads publish in this contract uses POST /v1/posts. The captured text request sends content as a string, platforms as an array of objects containing platform and accountId, and publishNow set to true for immediate publication. The response for that example is a 202 with success, status set to published, a postId, and a per-platform entry containing platform, success, and platformPostUrl. A separate captured cross-post example sends content with platforms as a plain string array, so treat the two platform shapes as distinct captured examples rather than assuming they are interchangeable; the string-array shape is a captured hero example only, while the typed contract requires platforms[] objects with platform and accountId. For scheduled publishing, use scheduledFor as an ISO 8601 datetime string in the same /v1/posts request, with timezone as the separate optional IANA timezone field. For reply control, use platformSpecificData.replyControl inside the Threads entry in platforms[] with one of the exact enum values everyone, accounts_you_follow, or mentioned_only. Fields for media upload and media containers were not captured in the source text, so do not invent media field names; see the input contract table for what is verified and what is missing.

Worked examples by format: text, image, carousel, video, schedule, cross-post

For a text post, send content, a platforms entry with platform set to threads and the target accountId, and publishNow set to true. The worked example in the text post request code example follows that shape exactly, and the text post response code example shows the corresponding 202 response with platformPostUrl. For a cross-post, the captured example sends content with platforms set to ["twitter", "linkedin"], which shows how the same endpoint can target multiple platforms in a single request; this string-array shape is a captured hero example only and differs from the typed platforms[] object contract, so do not treat it as a valid typed-contract request. The scheduled post with reply control code example shows scheduledFor together with platformSpecificData.replyControl set to everyone inside the Threads platforms[] entry. Image, carousel, and video requests use the same endpoint, but their full media field schemas were not captured, so this page does not invent media fields for those formats. When you implement those formats, validate the format rules in the limits table before sending, and check the per-platform success and platformPostUrl values in the response rather than assuming every target succeeded.

Limits and failure matrix

Text posts may contain at most 500 characters, so count characters before sending and treat an over-limit post as a failure to fix in your composer rather than retrying unchanged. A Threads carousel needs between two and ten images, a post built around one image uses just that image, and a post must not combine video with images. For video, allow a lone video in a post, keep the file at or below 1 GB, keep the runtime at or below five minutes, and do not use GIF media. Enforce those Threads video limits during validation: reject a second video, reject a file over 1 GB, reject a duration over five minutes, and reject GIF media. If a request fails one of these checks, change the media or text and send a new request; do not resend the same payload expecting a different result.

Reply control, scheduling and OAuth decision criteria

Choose publishNow when the content should be published immediately, and choose scheduledFor when the post should be queued for a future date, time, and timezone. Choose replyControl deliberately: everyone allows the widest replies, accounts_you_follow limits replies to accounts the publisher follows, and mentioned_only limits replies to mentioned accounts. For authentication, Threads OAuth can produce the Threads OAuth URL and then manage the callback, the token exchange, storage, and refresh, so most teams do not need to build the OAuth flow themselves. If your team needs its own Meta app, use a Bring Your Own OAuth App flow instead. The decision is therefore between managed OAuth for the standard flow and Bring Your Own OAuth App when you need your own Meta app, and between publishNow for immediate delivery and scheduledFor for queued delivery.

Input contract for POST /v1/posts — verified captured fields and missing fields
FieldLocationType / exampleRequiredness in captured examplesNotes
contentRequest bodystringPresent in both captured requestsPost text; text posts support up to 500 characters.
platformsRequest bodyarrayPresent in both captured requestsText example uses objects; cross-post hero example uses strings. Both shapes preserved as captured; typed contract requires objects.
platforms[].platformRequest bodystring, e.g. "threads"Present in text exampleTarget platform for the entry.
platforms[].accountIdRequest bodystring, e.g. "th_123"Present in text exampleConnected account that publishes the post.
publishNowRequest bodyboolean, e.g. truePresent in text exampleUse for immediate publication.
scheduledForRequest bodystring, ISO 8601 datetimeDescribed in FAQ answerUse for scheduled publication in the same /v1/posts request.
timezoneRequest bodystring, IANA timezoneDescribed in FAQ answerSeparate optional field for the scheduled time; defaults to UTC per cross-page contract.
platforms[].platformSpecificData.replyControlRequest bodyenum: everyone | accounts_you_follow | mentioned_onlyDescribed in FAQ answerInside the Threads platforms[] entry; controls who can reply to the post.
Media upload / container fieldsRequest bodyNot capturedNot captured — do not inventFull image, carousel, and video schemas were not captured in source text.
success202 response bodyboolean, e.g. truePresent in captured responseOverall result flag.
status202 response bodystring, e.g. "published"Present in captured responsePost status.
postId202 response bodystring, e.g. "post_abc123"Present in captured responseIdentifier for the created post.
platforms[].platformPostUrl202 response bodystring URLPresent in captured responsePer-platform URL of the published post.

Verified captured fields only; missing media fields are not invented.

Limits and failure matrix
Format / ruleLimitFailure checkAction on failure
Text post lengthUp to 500 charactersContent exceeds 500 charactersShorten content and send a new request.
Threads carousel2–10 imagesFewer than 2 or more than 10 images in a carouselAdjust image count to 2–10, or use a single-image post with one image.
Mixed mediaVideo cannot be mixed with images in the same postRequest contains both video and imagesSplit into separate posts or remove one media type.
Video countOne video per postMore than one video attachedKeep one video and move the rest to another post.
Video sizeMaximum 1 GBVideo file exceeds 1 GBCompress or replace the video.
Video durationMaximum five minutesVideo exceeds five minutesTrim the video.
GIF mediaGIFs are not supportedGIF attached as mediaConvert to a supported format or remove it.

Limits as captured in source FAQ answers.

Frequently asked questions

What can I publish to Threads with the Threads Posting API?

Plain text, a lone image, a carousel made of several images, and video are all supported. Text-only posts may contain no more than 500 characters.

How many images can I add to a Threads carousel?

Carousels require a minimum of two images and accept up to ten. A post built around one image is handled separately, and combining video with images in one post is not allowed.

What are the Threads video limits?

Only a single video may be attached. Keep the file at or below 1 GB and the runtime at or below five minutes. GIF files are not accepted.

Can I control who replies to a Threads post?

Place platformSpecificData.replyControl on the Threads object inside platforms[] and pick everyone, accounts_you_follow, or mentioned_only, depending on how narrowly you want responses limited.

Can I schedule Threads posts?

Yes. Include scheduledFor holding an ISO 8601 datetime in the POST /v1/posts payload, and add timezone with an IANA timezone value when you need one.

Does the Threads Posting API support Threads comments and replies?

Yes. The companion comments feature lets you fetch replies attached to a Threads post and send responses to them.

Do I need to build the Threads OAuth flow myself?

You do not have to construct it yourself. The managed option produces the Threads OAuth URL, then manages the callback, the token exchange, storage, and refresh. A Bring Your Own OAuth App option exists if you want to supply your own Meta app.

What can I build with the Threads Posting API?

Agency dashboards, SaaS publishing tools and automated content-repurposing systems can use it for Threads. AI-assisted workflows can call the same posting contract.

Text post response — 202
202

{
  "success": true,
  "status": "published",
  "postId": "post_abc123",
  "platforms": [
    {
      "platform": "threads",
      "success": true,
      "platformPostUrl": "https://www.threads.net/@username/post/..."
    }
  ]
}
Scheduled post with reply control — POST /v1/posts
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",
      "platformSpecificData": {
        "replyControl": "everyone"
      }
    }
  ],
  "scheduledFor": "<ISO_8601_DATETIME_PLACEHOLDER>",
  "timezone": "<IANA_TIMEZONE_PLACEHOLDER>"
}