How to post on Threads via API
If you want to post on Threads via API, you need a reliable way to connect a Threads account, send text and media in the right shape, and handle scheduling and limits without rebuilding the underlying publishing flow for every post. This guide walks through the full Threads API workflow: getting an access key, connecting with Threads OAuth, finding the accountId, and posting text, images, carousels, and video with the exact request fields used in the examples.
What you need before you post on Threads via API
Before you write any posting code, confirm three prerequisites: an account with an access key, a Threads account you are authorised to post from, and a way to store the accountId you will send with each request. The access key is sent on every request in the x-access-key header, so keep it server-side and out of client code. If a request fails with an authentication error, check the header name and value first before changing the payload.
Get your API key and connect with Threads OAuth
Step 1 is to get your API key from the Access Keys page in the dashboard and copy it for use as YOUR_API_KEY in the examples. Step 2 is to connect your Threads account through Threads OAuth. Request the OAuth URL, redirect the user to that URL, and let them authorise threads_basic and threads_content_publish. The token exchange and storage of the long-lived credential happen after authorisation, so your application does not need to handle the raw Threads token exchange itself. You can also connect directly from the integrations dashboard without writing code, which is useful for testing before you automate the flow.
Find your accountId
Step 3 is to find your account ID. List integrations filtered to platform=threads and look for the entry whose id you will use as accountId when posting, alongside displayName for the handle and imageUrl for the profile image. Save the id per user or per workspace, because the same content can be posted from different connected accounts and the accountId is what selects the target. If the list is empty, the connection step has not completed; if the wrong account appears, check that you filtered by platform=threads and that the user connected the intended Threads profile.
Post text to Threads
Step 4 is to post to Threads with POST /v1/posts. Send content for the post text, a platforms array with one entry for Threads containing platform set to threads and accountId set to the id you found, and publishNow set to true for immediate publishing. Threads caps posts at 500 characters, and the API returns a clean error if you exceed that limit, so validate length in your own code as well and show the user a clear message before sending. The worked text example is shown in the code example titled Post text to Threads.
Images, carousels, and video with mediaItems
For a single image, add mediaItems with one item whose type is image and whose url is shown in the examples as a CDN URL. For an image carousel, add 2 to 10 image items in mediaItems and the multi-step container build is handled for you; do not send a single image and expect carousel behaviour, and do not send more than 10 images in one post. For video, add one mediaItems item whose type is video, keeping the file within the limits in the limits table below. GIFs are not supported, so convert or remove animated GIFs before posting rather than sending them and expecting a fallback.
Add altText for images
Alt text is passed per image in the same order as mediaItems, inside platformSpecificData.altText on the Threads platform entry. Keep the order aligned: the first altText entry describes the first mediaItems image, the second describes the second, and so on. Write alt text that describes the image content rather than repeating the caption, and check the ordering whenever you reorder mediaItems in code, because a mismatch will attach the wrong description to the wrong image.
Set replyControl
Reply controls restrict who can reply to a post. Set replyControl inside platformSpecificData on the Threads platform entry. The available values are everyone, which is the default, accounts_you_follow, and mentioned_only. Choose the setting that matches the conversation you want: everyone for open discussion, accounts_you_follow for a more limited audience, and mentioned_only when replies should be limited to people mentioned in the post. If you omit replyControl, expect the default behaviour rather than an error.
Schedule with scheduledFor and timezone
To schedule instead of publishing immediately, the source examples swap publishNow for scheduledFor plus a timezone. Send scheduledFor as the intended local date and time and timezone as the IANA timezone name, for example America/New_York, so the scheduled time is interpreted correctly. The examples do not show sending publishNow and scheduledFor together, so follow the shown pattern of using one publishing mode per request. After scheduling, confirm the scheduled time matches what the user selected in the chosen timezone.
Cross-post with multiple platforms entries
Cross-posting uses the same POST /v1/posts request with more entries in the platforms array. Add one entry per platform and accountId, and the post goes to all of them at once, with each platform adapted to its own rules. Keep in mind that a limit that applies to Threads, such as 500 characters, may not apply to another platform in the same request, so validate the content against the strictest target in the array before sending.
60-day tokens and revoked access
Threads credentials in this contract are described as lasting 60 days, with renewal handled ahead of expiry. Under that description, activity at least once inside each 60-day window keeps the connection usable. A different situation arises when the user withdraws permission inside Threads: a later publishing attempt then fails with an authentication problem. Your app should respond to that failure by offering a fresh connection step, sending the user back through the connect endpoint at /v1/connect/threads. Planning for expiry and for withdrawal in advance prevents a working integration from appearing broken without explanation.
Field map, limits, and failure checks
Use the field map and failure matrix below as a pre-flight checklist. Confirm content length, mediaItems count and type, video size and duration, GIF handling, accountId, publishing mode, and token status before you send. Most failures in this workflow are predictable: an over-length post, an unsupported media type, a video over the size or duration cap, a missing or wrong accountId, or an expired or revoked token. Checking those items in order will resolve the majority of errors without changing the request shape.
| Field | Where it appears | Required or optional in examples | Type and values | Purpose |
|---|---|---|---|---|
| content | POST /v1/posts body | Required in examples | string | Post text; Threads limit 500 characters |
| mediaItems | POST /v1/posts body | Optional; omit for text-only | array of {type, url} | Image or video attachments; type is image or video |
| platforms | POST /v1/posts body | Required in examples | array of platform entries | Posting targets; add entries to cross-post |
| platform | Each platforms entry | Required in examples | string; threads in examples | Selects the target platform |
| accountId | Each platforms entry | Required in examples | string | Connected account id from integrations list |
| publishNow | POST /v1/posts body | Required for immediate posts in examples | boolean; true in examples | Publishes immediately |
| scheduledFor | POST /v1/posts body | Required for scheduled posts in examples | string date-time | Scheduled publish time; used instead of publishNow in examples |
| timezone | POST /v1/posts body | Required with scheduledFor in examples | string; e.g. America/New_York | Timezone for scheduledFor |
| platformSpecificData | Threads platforms entry | Optional | object | Threads-specific options |
| altText | platformSpecificData | Optional | array of strings | Alt text per image, same order as mediaItems |
| replyControl | platformSpecificData | Optional; default everyone | enum: everyone, accounts_you_follow, mentioned_only | Restricts who can reply |
| x-access-key | Request header | Required | string | Access key authentication header |
| url | GET /v1/connect/threads response | Returned by connect endpoint | string | OAuth URL to redirect the user to |
| id | GET /v1/connect/integrations response item | Returned by integrations endpoint | string | Use as accountId when posting |
| displayName | GET /v1/connect/integrations response item | Returned by integrations endpoint | string | The @handle for the connected account |
| imageUrl | GET /v1/connect/integrations response item | Returned by integrations endpoint | string | Profile image URL for the connected account |
Requiredness is as shown in the source examples; full schema not supplied in source.
| Limit | Value |
|---|---|
| Text length | 500 characters |
| Images per post | 1 or 2-10 (carousel) |
| Videos per post | 1 |
| Video size | 1 GB max |
| Video duration | 5 minutes max |
| GIFs | Not supported |
Source-stated Threads limits for this contract.
| Failure | Check | Fix |
|---|---|---|
| Post over 500 characters | Count content length before sending | Shorten content; the API returns a clean error for over-limit posts |
| Carousel with 1 or more than 10 images | Count image items in mediaItems | Send 1 image for a single image or 2-10 for a carousel |
| Video over 1 GB or 5 minutes | Check file size and duration before posting | Compress or trim the video to fit the limits |
| GIF attached | Check mediaItems type and file format | Convert or remove the GIF; GIFs are not supported |
| Wrong or missing accountId | Compare accountId with id from GET /v1/connect/integrations?platform=threads | Use the id of the intended connected Threads account |
| Auth error after revocation or token expiry | Check whether access was revoked in Threads settings and whether 60-day tokens need refresh | Prompt the user to reconnect via /v1/connect/threads |
| Scheduled time in wrong timezone | Verify scheduledFor and timezone together | Send scheduledFor with the correct IANA timezone name |
Failure handling is derived from source-stated limits and token behaviour; exact status codes and error bodies were not supplied in source.
curl {{API_BASE_URL}}/v1/connect/threads \
-H "x-access-key: YOUR_API_KEY"{
"url": "https://threads.net/oauth/authorize?..."
}curl "{{API_BASE_URL}}/v1/connect/integrations?platform=threads" \
-H "x-access-key: YOUR_API_KEY"curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"platforms": [
{ "platform": "threads", "accountId": "your-account-id" }
],
"publishNow": true
}'curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"mediaItems": [
{ "type": "image", "url": "https://your-cdn.com/photo.jpg" }
],
"platforms": [
{ "platform": "threads", "accountId": "your-account-id" }
],
"publishNow": true
}'curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"mediaItems": [
{ "type": "image", "url": "https://your-cdn.com/1.jpg" },
{ "type": "image", "url": "https://your-cdn.com/2.jpg" },
{ "type": "image", "url": "https://your-cdn.com/3.jpg" }
],
"platforms": [
{ "platform": "threads", "accountId": "your-account-id" }
],
"publishNow": true
}'curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"mediaItems": [
{ "type": "video", "url": "https://your-cdn.com/walkthrough.mp4" }
],
"platforms": [
{ "platform": "threads", "accountId": "your-account-id" }
],
"publishNow": true
}'curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"mediaItems": [
{ "type": "image", "url": "https://your-cdn.com/sunset.jpg" }
],
"platforms": [
{
"platform": "threads",
"accountId": "your-account-id",
"platformSpecificData": {
"altText": ["Pink sunset over the bay with silhouetted boats"]
}
}
],
"publishNow": true
}'curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"platforms": [
{
"platform": "threads",
"accountId": "your-account-id",
"platformSpecificData": {
"replyControl": "accounts_you_follow"
}
}
],
"publishNow": true
}'curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"platforms": [
{ "platform": "threads", "accountId": "your-account-id" }
],
"scheduledFor": "2026-08-01T10:00:00",
"timezone": "America/New_York"
}'curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"platforms": [
{ "platform": "threads", "accountId": "acc_th_123" },
{ "platform": "twitter", "accountId": "acc_tw_456" },
{ "platform": "linkedin", "accountId": "acc_li_789" }
],
"publishNow": true
}'