Threads API

Schedule and automate Threads posts with SocialSyncerAPI — Text, images, videos, carousels, and thread sequences.

Quick Reference

Character limit: 500
Images per post: 10 (carousel)
Videos per post: 1
Image formats: JPEG, PNG, WebP, GIF
Image max size: 8 MB (auto-compressed)
Video formats: MP4, MOV
Video max size: 1 GB
Video max duration: 5 minutes
Post types: Text, Image, Video, Carousel, Thread sequence
Scheduling: Yes
Analytics: Limited

Before You Start

Threads has a 500 character limit. This is the #1 failure — users cross-posting from LinkedIn (3,000), Facebook (63,000), or Instagram (2,200) captions will fail. Use customContent to provide a shorter Threads version.

Threads is connected to your Instagram account. You must have an Instagram Business or Creator account with Threads enabled. Losing Instagram access means losing Threads.

Connected via Instagram authentication (same Facebook app)
If your Instagram account is restricted, Threads posting fails too
Rate limit: 250 API-published posts per 24-hour window

Quick Start

Post to Threads in under 60 seconds:

Python (httpx)

import httpx

resp = httpx.post(
    "https://api.socialsyncerapi.com/v1/posts",
    headers={"Authorization": "Bearer sk_your_api_key"},
    json={
        "content": "Sharing some thoughts on building in public",
        "platforms": [
            {"platform": "threads", "accountId": "YOUR_ACCOUNT_ID"}
        ],
        "publishNow": True
    }
)
print("Posted to Threads!", resp.json()["id"])

curl

curl -X POST https://api.socialsyncerapi.com/v1/posts \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Sharing some thoughts on building in public",
    "platforms": [
      {"platform": "threads", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'

Node.js (fetch)

const resp = await fetch("https://api.socialsyncerapi.com/v1/posts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    content: "Sharing some thoughts on building in public",
    platforms: [
      { platform: "threads", accountId: "YOUR_ACCOUNT_ID" }
    ],
    publishNow: true
  })
});
const data = await resp.json();
console.log("Posted to Threads!", data.id);

Content Types

Text Post

Threads is one of the few platforms that supports text-only posts — no media required. Up to 500 characters.

Text — Python

import httpx

resp = httpx.post(
    "https://api.socialsyncerapi.com/v1/posts",
    headers={"Authorization": "Bearer sk_your_api_key"},
    json={
        "content": "Hot take: the best API is the one with the best docs.",
        "platforms": [
            {"platform": "threads", "accountId": "YOUR_ACCOUNT_ID"}
        ],
        "publishNow": True
    }
)

Text — curl

curl -X POST https://api.socialsyncerapi.com/v1/posts \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hot take: the best API is the one with the best docs.",
    "platforms": [
      {"platform": "threads", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'

Text — Node.js

const resp = await fetch("https://api.socialsyncerapi.com/v1/posts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    content: "Hot take: the best API is the one with the best docs.",
    platforms: [
      { platform: "threads", accountId: "YOUR_ACCOUNT_ID" }
    ],
    publishNow: true
  })
});

Image Post

A single image with an optional caption.

Image — Python

import httpx

resp = httpx.post(
    "https://api.socialsyncerapi.com/v1/posts",
    headers={"Authorization": "Bearer sk_your_api_key"},
    json={
        "content": "New office setup is looking great",
        "mediaItems": [
            {"type": "image", "url": "https://cdn.example.com/office.jpg"}
        ],
        "platforms": [
            {"platform": "threads", "accountId": "YOUR_ACCOUNT_ID"}
        ],
        "publishNow": True
    }
)

Image — curl

curl -X POST https://api.socialsyncerapi.com/v1/posts \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "New office setup is looking great",
    "mediaItems": [
      {"type": "image", "url": "https://cdn.example.com/office.jpg"}
    ],
    "platforms": [
      {"platform": "threads", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'

Image — Node.js

const resp = await fetch("https://api.socialsyncerapi.com/v1/posts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    content: "New office setup is looking great",
    mediaItems: [
      { type: "image", url: "https://cdn.example.com/office.jpg" }
    ],
    platforms: [
      { platform: "threads", accountId: "YOUR_ACCOUNT_ID" }
    ],
    publishNow: true
  })
});

Video Post

A single video with an optional caption. Max 1 GB, up to 5 minutes long.

Video — Python

import httpx

resp = httpx.post(
    "https://api.socialsyncerapi.com/v1/posts",
    headers={"Authorization": "Bearer sk_your_api_key"},
    json={
        "content": "Behind the scenes of our latest product launch",
        "mediaItems": [
            {"type": "video", "url": "https://cdn.example.com/launch.mp4"}
        ],
        "platforms": [
            {"platform": "threads", "accountId": "YOUR_ACCOUNT_ID"}
        ],
        "publishNow": True
    }
)

Video — curl

curl -X POST https://api.socialsyncerapi.com/v1/posts \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Behind the scenes of our latest product launch",
    "mediaItems": [
      {"type": "video", "url": "https://cdn.example.com/launch.mp4"}
    ],
    "platforms": [
      {"platform": "threads", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'

Video — Node.js

const resp = await fetch("https://api.socialsyncerapi.com/v1/posts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    content: "Behind the scenes of our latest product launch",
    mediaItems: [
      { type: "video", url: "https://cdn.example.com/launch.mp4" }
    ],
    platforms: [
      { platform: "threads", accountId: "YOUR_ACCOUNT_ID" }
    ],
    publishNow: true
  })
});

Carousel

Up to 10 images in a single swipeable post.

Carousel — Python

import httpx

resp = httpx.post(
    "https://api.socialsyncerapi.com/v1/posts",
    headers={"Authorization": "Bearer sk_your_api_key"},
    json={
        "content": "Product launch day! Here are all the new features:",
        "mediaItems": [
            {"type": "image", "url": "https://cdn.example.com/feature1.jpg"},
            {"type": "image", "url": "https://cdn.example.com/feature2.jpg"},
            {"type": "image", "url": "https://cdn.example.com/feature3.jpg"}
        ],
        "platforms": [
            {"platform": "threads", "accountId": "YOUR_ACCOUNT_ID"}
        ],
        "publishNow": True
    }
)

Carousel — curl

curl -X POST https://api.socialsyncerapi.com/v1/posts \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Product launch day! Here are all the new features:",
    "mediaItems": [
      {"type": "image", "url": "https://cdn.example.com/feature1.jpg"},
      {"type": "image", "url": "https://cdn.example.com/feature2.jpg"},
      {"type": "image", "url": "https://cdn.example.com/feature3.jpg"}
    ],
    "platforms": [
      {"platform": "threads", "accountId": "YOUR_ACCOUNT_ID"}
    ],
    "publishNow": true
  }'

Carousel — Node.js

const resp = await fetch("https://api.socialsyncerapi.com/v1/posts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    content: "Product launch day! Here are all the new features:",
    mediaItems: [
      { type: "image", url: "https://cdn.example.com/feature1.jpg" },
      { type: "image", url: "https://cdn.example.com/feature2.jpg" },
      { type: "image", url: "https://cdn.example.com/feature3.jpg" }
    ],
    platforms: [
      { platform: "threads", accountId: "YOUR_ACCOUNT_ID" }
    ],
    publishNow: true
  })
});

Thread Sequence

Create connected posts (root + replies) using threadItems. The first item is the root post and subsequent items become replies in order. Each item can have its own text and media.

Note: When threadItems is provided, the top-level content field is used only for display and search purposes, it is NOT published. You must include your first post as threadItems[0].

Thread — Python

import httpx

resp = httpx.post(
    "https://api.socialsyncerapi.com/v1/posts",
    headers={"Authorization": "Bearer sk_your_api_key"},
    json={
        "platforms": [{
            "platform": "threads",
            "accountId": "YOUR_ACCOUNT_ID",
            "platformSpecificData": {
                "threadItems": [
                    {
                        "content": "Here is a thread about API design",
                        "mediaItems": [{"type": "image", "url": "https://cdn.example.com/cover.jpg"}]
                    },
                    {"content": "1/ First, let's talk about REST principles..."},
                    {
                        "content": "2/ Authentication is crucial. Here's what we recommend...",
                        "mediaItems": [{"type": "image", "url": "https://cdn.example.com/auth-diagram.jpg"}]
                    },
                    {"content": "3/ Finally, always version your API! /end"}
                ]
            }
        }],
        "publishNow": True
    }
)

Thread — curl

curl -X POST https://api.socialsyncerapi.com/v1/posts \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "platforms": [{
      "platform": "threads",
      "accountId": "YOUR_ACCOUNT_ID",
      "platformSpecificData": {
        "threadItems": [
          {
            "content": "Here is a thread about API design",
            "mediaItems": [{"type": "image", "url": "https://cdn.example.com/cover.jpg"}]
          },
          {"content": "1/ First, let'''s talk about REST principles..."},
          {
            "content": "2/ Authentication is crucial. Here'''s what we recommend...",
            "mediaItems": [{"type": "image", "url": "https://cdn.example.com/auth-diagram.jpg"}]
          },
          {"content": "3/ Finally, always version your API! /end"}
        ]
      }
    }],
    "publishNow": true
  }'

Thread — Node.js

const resp = await fetch("https://api.socialsyncerapi.com/v1/posts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    platforms: [{
      platform: "threads",
      accountId: "YOUR_ACCOUNT_ID",
      platformSpecificData: {
        threadItems: [
          {
            content: "Here is a thread about API design",
            mediaItems: [{ type: "image", url: "https://cdn.example.com/cover.jpg" }]
          },
          { content: "1/ First, let's talk about REST principles..." },
          {
            content: "2/ Authentication is crucial. Here's what we recommend...",
            mediaItems: [{ type: "image", url: "https://cdn.example.com/auth-diagram.jpg" }]
          },
          { content: "3/ Finally, always version your API! /end" }
        ]
      }
    }],
    publishNow: true
  })
});

Media Requirements

Images

Max images: 10 per post (carousel)
Formats: JPEG, PNG, WebP, GIF
Max file size: 8 MB per image (auto-compressed)
Recommended: 1080 x 1350 px (4:5 portrait)

Videos

Max videos: 1 per post
Formats: MP4, MOV
Max file size: 1 GB
Max duration: 5 minutes
Aspect ratio: 9:16 (vertical), 16:9 (landscape), 1:1 (square)
Resolution: 1080p recommended
Codec: H.264, AAC audio at 128 kbps

Platform-Specific Data

All fields go inside platformSpecificData on the Threads platform entry.

topic_tag — string — Topic tag for categorization/discoverability. 1–50 characters, cannot contain periods (.) or ampersands (&). Overrides auto-extraction from content hashtags.
threadItems — Array of objects — Complete sequence of posts in a thread. Each has: content (string) and mediaItems (optional array). First item becomes root post. When provided, top-level content is NOT published.

Constraints

Character limit: 500
Images per post: 10 (carousel)
Videos per post: 1
Video size: 1 GB max
Video duration: 5 minutes max
Image size: 8 MB (auto-compressed)
Daily post limit: 250 per 24-hour window

What You Can't Do

These features are not available through the Threads API:

Create polls
Use GIF search
Edit posts after publishing
See who liked or reposted
Create quote posts
Post new top-level comments (reply-only)
Like or unlike comments
Send DMs

Common Errors

"Param text must be at most 500 characters long." — Post exceeds the 500 character limit. Shorten text or use customContent.
"Media download has failed." — Threads cannot fetch media from URL. Use direct URLs. WebP may fail — use JPEG or PNG.
"Instagram account is restricted." — The linked Instagram account is restricted. Check your account status on Instagram.
"Publishing failed due to max retries reached" — Usually temporary. Wait a few minutes and retry.