Skip to content

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.

Platform-specific data fields
FieldTypeRequiredValues and constraintsDescription
replyControlstringNoeveryone, accounts_you_follow, mentioned_onlyWho can reply to this thread. Defaults to "everyone" when omitted.
altTextstring[]No—Alt text for each image, in the same order as mediaItems. Strongly encouraged for accessibility.

Preserved from source contract

Threads publishing limits
LimitValue
Text length500 characters
Images per post1 (single) or 2–10 (carousel)
Videos per post1
Mixing video + imagesNot allowed in one post
GIFsNot supported
Video size1 GB max
Video duration5 minutes max

Preserved from source contract

Token lifecycle and reconnection
SituationToken behaviorAction
Posts go through at least once every 60 daysLong-lived 60-day token auto-refreshed via th_refresh_token before expiry, extended another 60 daysNo user intervention needed
User revokes access in Threads settings or refresh window lapsesNext post returns an authentication errorSurface a reconnect Threads prompt and repeat /v1/connect/threads

Preserved from source contract

Connect a Threads account
curl {{API_BASE_URL}}/v1/connect/threads \
  -H "x-access-key: YOUR_API_KEY"
Connect response
{
	"url": "https://threads.net/oauth/authorize?..."
}
Find the Threads account ID
curl "{{API_BASE_URL}}/v1/connect/integrations?platform=threads" \
  -H "x-access-key: YOUR_API_KEY"
Publish a text post
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
  }'
Publish response
{
	"success": true,
	"status": "published",
	"platforms": [
		{
			"platform": "threads",
			"success": true,
			"platformPostId": "17841401234567890",
			"platformPostUrl": "https://www.threads.net/@username/post/..."
		}
	]
}
Publish a single image
{
	"content": "A short example update.",
	"platforms": [{ "platform": "threads", "accountId": "abc123" }],
	"mediaItems": [
		{ "type": "image", "url": "https://cdn.example.com/photo.jpg" }
	]
}
Publish an image carousel
{
	"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" }
	]
}
Publish a video
{
	"content": "A short example update.",
	"platforms": [{ "platform": "threads", "accountId": "abc123" }],
	"mediaItems": [
		{ "type": "video", "url": "https://cdn.example.com/walkthrough.mp4" }
	]
}
Set reply restrictions
{
	"platformSpecificData": {
		"replyControl": "accounts_you_follow"
	}
}
Add image alt text
{
	"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"]
	}
}