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.
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
}POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
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.
| Field | Location | Type / example | Requiredness in captured examples | Notes |
|---|---|---|---|---|
| content | Request body | string | Present in both captured requests | Post text; text posts support up to 500 characters. |
| platforms | Request body | array | Present in both captured requests | Text example uses objects; cross-post hero example uses strings. Both shapes preserved as captured; typed contract requires objects. |
| platforms[].platform | Request body | string, e.g. "threads" | Present in text example | Target platform for the entry. |
| platforms[].accountId | Request body | string, e.g. "th_123" | Present in text example | Connected account that publishes the post. |
| publishNow | Request body | boolean, e.g. true | Present in text example | Use for immediate publication. |
| scheduledFor | Request body | string, ISO 8601 datetime | Described in FAQ answer | Use for scheduled publication in the same /v1/posts request. |
| timezone | Request body | string, IANA timezone | Described in FAQ answer | Separate optional field for the scheduled time; defaults to UTC per cross-page contract. |
| platforms[].platformSpecificData.replyControl | Request body | enum: everyone | accounts_you_follow | mentioned_only | Described in FAQ answer | Inside the Threads platforms[] entry; controls who can reply to the post. |
| Media upload / container fields | Request body | Not captured | Not captured — do not invent | Full image, carousel, and video schemas were not captured in source text. |
| success | 202 response body | boolean, e.g. true | Present in captured response | Overall result flag. |
| status | 202 response body | string, e.g. "published" | Present in captured response | Post status. |
| postId | 202 response body | string, e.g. "post_abc123" | Present in captured response | Identifier for the created post. |
| platforms[].platformPostUrl | 202 response body | string URL | Present in captured response | Per-platform URL of the published post. |
Verified captured fields only; missing media fields are not invented.
| Format / rule | Limit | Failure check | Action on failure |
|---|---|---|---|
| Text post length | Up to 500 characters | Content exceeds 500 characters | Shorten content and send a new request. |
| Threads carousel | 2–10 images | Fewer than 2 or more than 10 images in a carousel | Adjust image count to 2–10, or use a single-image post with one image. |
| Mixed media | Video cannot be mixed with images in the same post | Request contains both video and images | Split into separate posts or remove one media type. |
| Video count | One video per post | More than one video attached | Keep one video and move the rest to another post. |
| Video size | Maximum 1 GB | Video file exceeds 1 GB | Compress or replace the video. |
| Video duration | Maximum five minutes | Video exceeds five minutes | Trim the video. |
| GIF media | GIFs are not supported | GIF attached as media | Convert 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.
202
{
"success": true,
"status": "published",
"postId": "post_abc123",
"platforms": [
{
"platform": "threads",
"success": true,
"platformPostUrl": "https://www.threads.net/@username/post/..."
}
]
}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>"
}