Threads API
The Threads API lets developers publish text, images, image carousels, and videos to Threads through a single documented contract. It is built on Meta's Threads Graph API, with OAuth, long-lived token exchange, and the two-phase container and publish flow handled behind the API. For API and OAuth purposes, Threads operates independently from Facebook and Instagram, despite sharing Meta as parent company.
Overview and scope
Threads operates as a distinct Meta product, with API and OAuth handling that differs from Facebook and Instagram. Publishing through the Threads Graph API uses a two-phase container and publish flow internally, and that flow is handled for you so you can focus on the request fields. The consent screen for a new connection lists threads_basic and threads_content_publish, and you should confirm both scopes are shown before sending a user through authorization.
Quick start: connect, find accountId, publish
Start by requesting a connection URL for Threads and sending the user to the returned url. After the user confirms authorization, the callback creates one integration tied to that Threads account. Then list integrations filtered to platform=threads and find the entry whose id you will use as accountId; the same entry provides displayName as the user's @handle, imageUrl, and platformUserId as the Threads user id. Check that the handle matches the intended account before publishing, because accountId is the identifier that binds every later post to that integration. The worked examples titled Connect a Threads account, Connect response, and Find the Threads account ID show the exact requests and response shape.
Publishing a post and reading the response
To publish, send a POST request with content, a platforms array containing platform threads and the accountId, and publishNow set to true for immediate publication. A successful response reports success true and status published at the top level, and per-platform entries carry platformPostId and platformPostUrl so you can store the published identifier and link. If the response does not show success for threads, treat the post as not published and inspect the error before retrying, rather than assuming the platformPostId exists. The examples titled Publish a text post and Publish response show the full request and response contract.
Features by media type
Text-only posts need only content, up to 500 characters. For a single image, attach one image entry in mediaItems and put the caption in content. For an image carousel, attach 2 to 10 image entries in mediaItems; the multi-step container build runs for you, with each image becoming a child container, then a parent CAROUSEL container, then publish. For video, attach one video entry in mediaItems and the content becomes the caption. The examples titled Publish a single image, Publish an image carousel, and Publish a video show each mediaItems shape.
Reply restrictions and image alt text
Use platformSpecificData.replyControl to limit who can reply, choosing everyone, accounts_you_follow, or mentioned_only, with everyone as the default when the field is omitted. For image accessibility, pass platformSpecificData.altText as a string array in the same order as mediaItems, one entry per image, and keep the ordering aligned when you reorder media. The examples titled Set reply restrictions and Add image alt text show both fields in context.
Tokens and reconnection
Threads issues long-lived 60-day user tokens. Before expiry, th_refresh_token is called automatically, adding another 60 days. Publishing at least once within each 60-day period keeps the integration active without user action. When access is revoked in Threads settings, or the refresh window has passed, the following publish attempt fails with an authentication error. In that case, show a reconnect prompt and direct the user back through /v1/connect/threads. Build that prompt into your error handling now, because the failure only appears on the next publish attempt.
| Field | Type | Required | Values and constraints | Description |
|---|---|---|---|---|
| replyControl | string | No | everyone, accounts_you_follow, mentioned_only | Who can reply to this thread. Defaults to "everyone" when omitted. |
| altText | string[] | No | — | Alt text for each image, in the same order as mediaItems. Strongly encouraged for accessibility. |
Preserved from source contract
| Limit | Value |
|---|---|
| Text length | 500 characters |
| Images per post | 1 (single) or 2–10 (carousel) |
| Videos per post | 1 |
| Mixing video + images | Not allowed in one post |
| GIFs | Not supported |
| Video size | 1 GB max |
| Video duration | 5 minutes max |
Preserved from source contract
| Situation | Token behavior | Action |
|---|---|---|
| Posts go through at least once every 60 days | Long-lived 60-day token auto-refreshed via th_refresh_token before expiry, extended another 60 days | No user intervention needed |
| User revokes access in Threads settings or refresh window lapses | Next post returns an authentication error | Surface a reconnect Threads prompt and repeat /v1/connect/threads |
Preserved from source contract
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": "abc123" }
],
"publishNow": true
}'{
"success": true,
"status": "published",
"platforms": [
{
"platform": "threads",
"success": true,
"platformPostId": "17841401234567890",
"platformPostUrl": "https://www.threads.net/@username/post/..."
}
]
}{
"content": "A short example update.",
"platforms": [{ "platform": "threads", "accountId": "abc123" }],
"mediaItems": [
{ "type": "image", "url": "https://cdn.example.com/photo.jpg" }
]
}{
"content": "A short example update.",
"platforms": [{ "platform": "threads", "accountId": "abc123" }],
"mediaItems": [
{ "type": "image", "url": "https://cdn.example.com/1.jpg" },
{ "type": "image", "url": "https://cdn.example.com/2.jpg" },
{ "type": "image", "url": "https://cdn.example.com/3.jpg" }
]
}{
"content": "A short example update.",
"platforms": [{ "platform": "threads", "accountId": "abc123" }],
"mediaItems": [
{ "type": "video", "url": "https://cdn.example.com/walkthrough.mp4" }
]
}{
"platformSpecificData": {
"replyControl": "accounts_you_follow"
}
}{
"mediaItems": [
{ "type": "image", "url": "https://cdn.example.com/sunset.jpg" },
{ "type": "image", "url": "https://cdn.example.com/coast.jpg" }
],
"platformSpecificData": {
"altText": ["Pink sunset over the bay", "Rocky coast at low tide"]
}
}