Docs/API Reference/Threads

Threads API

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

Post Types

Image · Carousel · Video · Text

Character Limit

500 characters

Max Media

10 items 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 native post types: single images, swipeable carousels (up to 10 images), videos (up to 5 minutes), and standard text posts. Threads enforces a 500-character limit per post.

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 thread text. Max 500 characters. Supports hashtags, links, and emojis.

title✗ IgnoredNot rendered on Threads — omit this field.

boardId✗ IgnoredPinterest only — ignored for Threads.

is_aigc✗ IgnoredTikTok only — ignored for Threads.

facebookFirstComment✗ IgnoredFacebook only — ignored for Threads.

textFormatPresetId✗ IgnoredFacebook only — ignored for Threads.

500-character limit

Threads enforces a firm 500-character limit per post. Crosspostify will return a validation error if your caption exceeds this limit. Long URLs also count against this limit.

Supported Endpoints

Threads fully supports all four Crosspostify post types:

POST/post/imageImage Post

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

Image Post Notes

Images appear uncropped in the feed. Portrait (4:5) and square (1:1) perform best.
Upload your image first via POST /media and use the returned mediaId
Caption counts toward the 500-character limit.
All datetime values must be in UTC timezone (ISO 8601 format with Z suffix).

Request Body

mediaIdstringrequired

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

scheduledDatestringoptional

Schedule the post for a future time (ISO 8601 with 'Z' suffix). 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. URLs are auto-linked by Threads.

Response

{ "success": true, "data": { "postId": "post_threads_001", "status": "SCHEDULED", "scheduledDate": "2025-06-01T14:00:00Z", "accounts": [ { "accountId": "acc_threads_123", "platform": "threads", "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": "2025-06-01T14:00:00Z",
    "posts": [
      {
        "accountId": "acc_threads_123",
        "caption": "Just dropped the new design system. What do you think? 🧵👇 #design #ui"
      }
    ]
  }'

POST/post/imagesCarousel

Publish an image carousel to Threads. Users can horizontally swipe through up to 10 images, making this highly engaging for storytelling or photo dumps.

Carousel Notes

Threads supports a maximum of 10 images per post.
Images appear in the exact order provided in your mediaIds array.
The platform favors identical aspect ratios across all images in a carousel for a smooth swiping experience.

Request Body

mediaIdsarrayrequired

Ordered array of image media IDs. Maximum 10 images.

scheduledDatestringoptional

Schedule the post for a future time (ISO 8601 with 'Z' suffix). 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.

Response

{ "success": true, "data": { "postId": "post_threads_002", "status": "SCHEDULED", "scheduledDate": "2025-06-01T14:00:00Z", "mediaCount": 4, "accounts": [ { "accountId": "acc_threads_123", "platform": "threads", "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": "2025-06-01T14:00:00Z",
    "posts": [
      {
        "accountId": "acc_threads_123",
        "caption": "Behind the scenes from today\'s studio session. 📸 Which one is your favorite?"
      }
    ]
  }'

POST/post/videoVideo Post

Publish a native video to Threads. Videos up to 5 minutes long are supported, making Threads an excellent secondary distribution channel for TikToks, Reels, or Shorts.

Video Post Notes

Videos can be up to 5 minutes long.
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 use the returned mediaId.

Request Body

mediaIdstringrequired

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

scheduledDatestringoptional

Schedule the post for a future time (ISO 8601 with 'Z' suffix). 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.

Response

{ "success": true, "data": { "postId": "post_threads_003", "status": "PROCESSING", "scheduledDate": "2025-06-01T14:00:00Z", "videoDuration": 45, "accounts": [ { "accountId": "acc_threads_123", "platform": "threads", "status": "PROCESSING" } ] } }

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": "2025-06-01T14: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

Strict 500-character limit.
Line breaks are supported and preserved in the final post.
URLs are automatically hyperlinked by Threads, making it a great platform for driving traffic.
Hashtags are fully supported and will convert into clickable tags.

Request Body

scheduledDatestringoptional

Schedule the post for a future time (ISO 8601 with 'Z' suffix). 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. Max 500 characters. Required for text posts.

Response

{ "success": true, "data": { "postId": "post_threads_004", "status": "SCHEDULED", "scheduledDate": "2025-06-01T14:00:00Z", "accounts": [ { "accountId": "acc_threads_123", "platform": "threads", "status": "SCHEDULED" } ] } }

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": "2025-06-01T14: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
Max file size: 20MB per image
Max 10 images per carousel post
Recommended format: 4:5 or 1:1

Video Requirements

Format: MP4 recommended
Max file size: 100MB via Crosspostify
Max duration: 5 minutes
Vertical (9:16) video highly recommended

Text & Caption Tips

Strict 500-character limit
Include a strong hook or question
URLs are active — great for driving traffic
Use hashtags sparingly for discoverability

Scheduling

Minimum lead time: ~10 minutes ahead
All times must be UTC (ISO 8601 + Z)
Omit scheduledDate to post immediately
Post when your specific audience is most active