Docs/API Reference/Threads

Threads API

Use the Crosspostify API to publish images, multi-image carousels, videos, and text posts directly to Meta's text-first social network.

Post Types

Image · Carousel · Video · Text

Character Limit

500 characters (longer text is cut)

Max Media

10 images per post

Audience

Public conversations & creators

Threads is Meta's fast-growing, text-based conversation app, heavily integrated with the Instagram ecosystem. It's a prime platform for rapid-fire discussions, developer build-in-public updates, and community engagement.

The Crosspostify Threads integration supports all four post types: single images, swipeable carousels (up to 10 images), videos (Threads allows up to 5 minutes), and standard text posts. Each request creates single posts; reply chains are not supported. Threads has a 500-character limit per post, and Crosspostify cuts longer captions to 500 characters.

This page covers everything specific to Threads when using the Crosspostify API. For general authentication, rate limits, and error handling, see the full API Reference.

Threads-Specific Parameters

When publishing to a Threads account, parameters like title are ignored, as Threads is a single-stream text and media platform. Your main focus will be the caption and media attachments.

accountId✓ AppliesRequired. Your Threads account ID from /social-accounts.

caption✓ AppliesThe post text. Max 500 characters (longer text is cut, no error). Supports hashtags, links, and emojis.

title✗ IgnoredNot rendered on Threads — omit this field.

link✗ IgnoredIgnored for Threads — put URLs in caption.

boardId✗ IgnoredPinterest only — ignored for Threads.

is_aigc✗ IgnoredTikTok, Instagram and Facebook only — ignored for Threads.

thumbnailTimestamp✗ IgnoredTikTok only — no custom video cover for Threads.

facebookFirstComment✗ IgnoredFacebook only — ignored for Threads.

textFormatPresetId✗ IgnoredFacebook text posts only — ignored for Threads.

tiktok / instagram / facebook✗ IgnoredSettings for those platforms — ignored for Threads.

500-character limit

Threads has a firm 500-character limit per post. Captions longer than 500 characters are cut to 500. No error is returned. Long URLs also count against this limit.

Supported Endpoints

Threads supports all four Crosspostify post types:

POST/post/imageImage Post

Publish a single image to Threads. The image is shown inline in the feed, perfect for sharing visual updates, charts, or memes alongside your text.

Image Post Notes

Threads decides how images are shown in the feed; portrait (4:5) and square (1:1) images usually work well.
Upload your image first via POST /media and pass the returned id as mediaId.
Crosspostify does not shrink images for Threads. Threads has its own image size limit, lower than the 20 MB Crosspostify accepts, so keep image files small.
Captions longer than 500 characters are cut (no error).
scheduledDate accepts any ISO 8601 date-time. Z or an offset (e.g. +01:00) is converted to UTC; no offset means UTC. It must be in the future.

Request Body

mediaIdstringrequired

The ID of the uploaded image file. Obtain this from POST /media.

scheduledDatestringoptional

ISO 8601 date-time in the future, e.g. 2030-01-15T10:00:00Z (offsets are converted to UTC). Omit to post immediately.

postsarrayrequired

Array of post objects. Include one object per Threads account.

posts[].accountIdstringrequired

The Threads account ID. Retrieve from GET /social-accounts.

posts[].captionstringoptional

Post text. Max 500 characters (longer text is cut, no error). URLs are auto-linked by Threads.

Response

202 Accepted. status is SCHEDULED when scheduledDate is set, otherwise QUEUED. The post is published afterwards; check the result with GET /posts?id=<id>.

{ "mediaId": "img_12345", "message": "Image post created successfully", "posts": [ { "id": "7f3c9a2e-1b4d-4c8e-9f60-2a5b7d1e3c48", "platform": "threads", "socialAccountId": "acc_threads_123", "status": "SCHEDULED" } ] }

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/image" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaId": "img_12345",
    "scheduledDate": "2030-01-15T10:00:00Z",
    "posts": [
      {
        "accountId": "acc_threads_123",
        "caption": "Just dropped the new design system. What do you think? 🧵👇 #design #ui"
      }
    ]
  }'

POST/post/imagesCarousel

Publish 1 to 10 images to Threads. With 2 or more images, users can horizontally swipe through a carousel, making this highly engaging for storytelling or photo dumps. A single image is posted as a normal image post.

Carousel Notes

Threads supports a maximum of 10 images per post. More returns 400 "Too many images" ("Threads supports a maximum of 10 images per post").
One image also works; it is posted as a normal image post.
Images appear in the exact order provided in your mediaIds array.
Crosspostify does not check aspect ratios for Threads; using the same aspect ratio for all images gives a smoother swipe.
scheduledDate accepts any ISO 8601 date-time. Z or an offset (e.g. +01:00) is converted to UTC; no offset means UTC. It must be in the future.

Request Body

mediaIdsarrayrequired

Ordered array of 1 to 10 image media IDs. More than 10 returns 400.

scheduledDatestringoptional

ISO 8601 date-time in the future, e.g. 2030-01-15T10:00:00Z (offsets are converted to UTC). Omit to post immediately.

postsarrayrequired

Array of post objects. Include one object per Threads account.

posts[].accountIdstringrequired

The Threads account ID. Retrieve from GET /social-accounts.

posts[].captionstringoptional

Shared caption for all images. Max 500 characters (longer text is cut, no error).

Response

202 Accepted. status is SCHEDULED when scheduledDate is set, otherwise QUEUED.

{ "mediaIds": ["img_001", "img_002", "img_003", "img_004"], "message": "Multiple images post created successfully", "posts": [ { "id": "7f3c9a2e-1b4d-4c8e-9f60-2a5b7d1e3c48", "platform": "threads", "socialAccountId": "acc_threads_123", "status": "SCHEDULED" } ] }

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/images" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaIds": ["img_001", "img_002", "img_003", "img_004"],
    "scheduledDate": "2030-01-15T10:00:00Z",
    "posts": [
      {
        "accountId": "acc_threads_123",
        "caption": "Behind the scenes from the studio session today. 📸 Which one is your favorite?"
      }
    ]
  }'

POST/post/videoVideo Post

Publish a native video to Threads. Threads accepts videos up to 5 minutes long, making it an excellent secondary distribution channel for TikToks, Reels, or Shorts.

Video Post Notes

Threads allows videos up to 5 minutes long. Crosspostify does not check the duration, only the 100 MB upload limit.
Portrait (9:16) videos are highly recommended, as they take up the most screen real estate on mobile devices.
Upload your video first via POST /media and pass the returned id as mediaId.
Captions longer than 500 characters are cut (no error).
scheduledDate accepts any ISO 8601 date-time. Z or an offset (e.g. +01:00) is converted to UTC; no offset means UTC. It must be in the future.

Request Body

mediaIdstringrequired

The ID of the uploaded video file. Obtain this from POST /media.

scheduledDatestringoptional

ISO 8601 date-time in the future, e.g. 2030-01-15T10:00:00Z (offsets are converted to UTC). Omit to post immediately.

postsarrayrequired

Array of post objects. Include one object per Threads account.

posts[].accountIdstringrequired

The Threads account ID. Retrieve from GET /social-accounts.

posts[].captionstringoptional

Post text alongside the video. Max 500 characters (longer text is cut, no error).

Response

202 Accepted. status is SCHEDULED when scheduledDate is set, otherwise QUEUED. Threads may still reject the video after this; GET /posts then shows status FAILED with an error.

{ "mediaId": "vid_12345", "message": "Video post created successfully", "posts": [ { "id": "7f3c9a2e-1b4d-4c8e-9f60-2a5b7d1e3c48", "platform": "threads", "socialAccountId": "acc_threads_123", "status": "SCHEDULED" } ] }

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/video" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaId": "vid_12345",
    "scheduledDate": "2030-01-15T10:00:00Z",
    "posts": [
      {
        "accountId": "acc_threads_123",
        "caption": "Quick walkthrough of the new feature we just shipped! Let me know if you hit any bugs. 🚀"
      }
    ]
  }'

POST/post/textText Post

Publish a standard text post to Threads. Text is the primary language of the platform, ideal for announcements, thoughts, links, and engaging with followers.

Text Post Notes

caption must not be empty. An empty or whitespace-only caption returns 400 "Missing caption".
500-character limit; longer captions are cut to 500 (no error).
Line breaks are supported and preserved in the final post.
URLs are automatically hyperlinked by Threads, making it a great platform for driving traffic. link is ignored; put URLs in the caption.
Threads handles hashtags and topic tags its own way; Crosspostify sends the caption as written.
textFormatPresetId (Facebook text backgrounds) is ignored for Threads.
scheduledDate accepts any ISO 8601 date-time. Z or an offset (e.g. +01:00) is converted to UTC; no offset means UTC. It must be in the future.

Request Body

scheduledDatestringoptional

ISO 8601 date-time in the future, e.g. 2030-01-15T10:00:00Z (offsets are converted to UTC). Omit to post immediately.

postsarrayrequired

Array of post objects. Include one object per Threads account.

posts[].accountIdstringrequired

The Threads account ID. Retrieve from GET /social-accounts.

posts[].captionstringrequired

The post text. Must not be empty or whitespace only (400 Missing caption). Max 500 characters (longer text is cut, no error).

Response

202 Accepted. With scheduledDate the message is "Text-only post scheduled successfully" and status is SCHEDULED; without it the message is "Text-only post created successfully" and status is QUEUED. There is no media key.

{ "message": "Text-only post scheduled successfully", "posts": [ { "id": "7f3c9a2e-1b4d-4c8e-9f60-2a5b7d1e3c48", "platform": "threads", "socialAccountId": "acc_threads_123", "status": "SCHEDULED" } ] }

Error: empty caption

{ "accountId": "acc_threads_123", "error": "Missing caption", "message": "Text-only posts need a caption" }

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/text" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduledDate": "2030-01-15T10:00:00Z",
    "posts": [
      {
        "accountId": "acc_threads_123",
        "caption": "Hot take: Threads is actually becoming the best place for developer discussions right now.\n\nThe signal-to-noise ratio has been surprisingly good lately. Anyone else feeling this way?"
      }
    ]
  }'

Content Guidelines

Threads is a conversation-first app. While highly visual posts can perform well, context and engaging captions are key. Content that sparks dialogue, asks questions, or shares timely insights usually performs best.

Image Requirements

Format: JPG, PNG or WEBP (converted to JPEG on upload)
Crosspostify accepts up to 20MB but does not shrink images for Threads
Threads has its own, lower image size limit — keep files small
Max 10 images per carousel post
Portrait 4:5 or square 1:1 usually work well

Video Requirements

Format: MP4 or MOV
Max file size: 100MB via Crosspostify
Max duration: 5 minutes (Threads limit, not checked by Crosspostify)
Vertical (9:16) video highly recommended

Text & Caption Tips

500-character limit; longer text is cut (no error)
Include a strong hook or question
URLs are active — great for driving traffic
Use hashtags sparingly; Threads handles topic tags its own way

Scheduling

Omit scheduledDate to post immediately
Any ISO 8601 time; offsets are converted to UTC, no offset = UTC
Must be in the future (past = 400); no minimum lead time
Published within about 1 minute of the scheduled time
Post when your specific audience is most active