Skip to content

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 map for posting on Threads via API
FieldWhere it appearsRequired or optional in examplesType and valuesPurpose
contentPOST /v1/posts bodyRequired in examplesstringPost text; Threads limit 500 characters
mediaItemsPOST /v1/posts bodyOptional; omit for text-onlyarray of {type, url}Image or video attachments; type is image or video
platformsPOST /v1/posts bodyRequired in examplesarray of platform entriesPosting targets; add entries to cross-post
platformEach platforms entryRequired in examplesstring; threads in examplesSelects the target platform
accountIdEach platforms entryRequired in examplesstringConnected account id from integrations list
publishNowPOST /v1/posts bodyRequired for immediate posts in examplesboolean; true in examplesPublishes immediately
scheduledForPOST /v1/posts bodyRequired for scheduled posts in examplesstring date-timeScheduled publish time; used instead of publishNow in examples
timezonePOST /v1/posts bodyRequired with scheduledFor in examplesstring; e.g. America/New_YorkTimezone for scheduledFor
platformSpecificDataThreads platforms entryOptionalobjectThreads-specific options
altTextplatformSpecificDataOptionalarray of stringsAlt text per image, same order as mediaItems
replyControlplatformSpecificDataOptional; default everyoneenum: everyone, accounts_you_follow, mentioned_onlyRestricts who can reply
x-access-keyRequest headerRequiredstringAccess key authentication header
urlGET /v1/connect/threads responseReturned by connect endpointstringOAuth URL to redirect the user to
idGET /v1/connect/integrations response itemReturned by integrations endpointstringUse as accountId when posting
displayNameGET /v1/connect/integrations response itemReturned by integrations endpointstringThe @handle for the connected account
imageUrlGET /v1/connect/integrations response itemReturned by integrations endpointstringProfile image URL for the connected account

Requiredness is as shown in the source examples; full schema not supplied in source.

Threads limits
LimitValue
Text length500 characters
Images per post1 or 2-10 (carousel)
Videos per post1
Video size1 GB max
Video duration5 minutes max
GIFsNot supported

Source-stated Threads limits for this contract.

Failure matrix
FailureCheckFix
Post over 500 charactersCount content length before sendingShorten content; the API returns a clean error for over-limit posts
Carousel with 1 or more than 10 imagesCount image items in mediaItemsSend 1 image for a single image or 2-10 for a carousel
Video over 1 GB or 5 minutesCheck file size and duration before postingCompress or trim the video to fit the limits
GIF attachedCheck mediaItems type and file formatConvert or remove the GIF; GIFs are not supported
Wrong or missing accountIdCompare accountId with id from GET /v1/connect/integrations?platform=threadsUse the id of the intended connected Threads account
Auth error after revocation or token expiryCheck whether access was revoked in Threads settings and whether 60-day tokens need refreshPrompt the user to reconnect via /v1/connect/threads
Scheduled time in wrong timezoneVerify scheduledFor and timezone togetherSend 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.

Get the Threads OAuth URL
curl {{API_BASE_URL}}/v1/connect/threads \
  -H "x-access-key: YOUR_API_KEY"
Threads OAuth URL response
{
  "url": "https://threads.net/oauth/authorize?..."
}
Find the Threads accountId
curl "{{API_BASE_URL}}/v1/connect/integrations?platform=threads" \
  -H "x-access-key: YOUR_API_KEY"
Post text to Threads
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
  }'
Post a single image to Threads
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
  }'
Post an image carousel to Threads
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
  }'
Post a video to Threads
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
  }'
Post an image with altText
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
  }'
Post with replyControl
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
  }'
Schedule a Threads 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": "your-account-id" }
    ],
    "scheduledFor": "2026-08-01T10:00:00",
    "timezone": "America/New_York"
  }'
Cross-post to multiple platforms
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
  }'