Copy page

Platforms

Threads API: posting reference

Threads is supported via Meta's Threads API. Only accounts linked to a Threads profile can be connected. The account must be a public profile.

For an overview and use cases, see Threads API.

Channel ID: threads

Supported content types

Type	Supported
Feed post	✅
Story	-
Reel	-

Minimal example

Terminal
curl -X POST https://api.omnisocials.com/v1/posts/create \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": { "default": "Thought of the day 💭" },
    "accounts": ["your-threads-account-id"]
  }'

Text-only posts are supported. Media is optional.

Platform-specific options

Field	Type	Description
threads.thread_parts	array	Publish as a chained thread instead of a single post. See Posting threads.
threads.poll	object	Attach a poll; the post text is the question. See Polls.

Threads has no required option fields. The default create-post body is sufficient for a single post.

Posting threads

To publish a thread (a chain of connected posts), pass threads.thread_parts. Each part becomes its own post, published as a reply to the previous one from the same account.

Terminal
curl -X POST https://api.omnisocials.com/v1/posts/create \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accounts": ["your-threads-account-id"],
    "content": { "default": "" },
    "threads": {
      "thread_parts": [
        { "text": "1/3: a thread on Threads 🧵" },
        { "text": "2/3: every part is its own post, replying to the one before it" },
        { "text": "3/3: and the whole chain is scheduled in one call" }
      ]
    }
  }'

Rules:

• 2 to 25 parts. For a single post, omit thread_parts and use content.threads (or content.default) instead.

• Each text is required, non-empty, and ≤ 500 characters. Parts that exceed the limit are rejected with a 400.

• Threads allows up to 5 unique links in a post, and every part is its own post. A part (or a single post) with more links is rejected with a 400 before anything publishes.

• media_urls (or media_ids) is optional per part, up to 20 items per part. A part with several items publishes as a carousel, and images and videos can be mixed in the same part, exactly like a single Threads post. Any entry can be an object with alt text:

  JSON
  {
    "threads": {
      "thread_parts": [
        {
          "text": "Photo dump from the trip 📷",
          "media_urls": [
            { "url": "https://example.com/1.jpg", "alt": "Sunrise over the harbour" },
            "https://example.com/2.jpg"
          ]
        },
        { "text": "More to come tomorrow." }
      ]
    }
  }

• When content.threads is provided alongside thread_parts, thread_parts wins: the first part is the post's caption.

• The first part's URL becomes the post's Threads URL. If a later part fails, POST /posts/:id/retry resumes from the first unpublished part instead of re-posting the ones that already landed.

To convert a thread back into a single post on update, send threads.thread_parts: null to PATCH /posts/:id.

Polls

Pass threads.poll to attach a poll. The post text is the question.

Terminal
curl -X POST https://api.omnisocials.com/v1/posts/create \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": { "threads": "Which channel do you schedule first?" },
    "accounts": ["your-threads-account-id"],
    "threads": {
      "poll": { "options": ["Threads", "Bluesky", "Mastodon"] }
    }
  }'

Rules:

• 2 to 4 options, each 1 to 25 characters and different from the others.
• There is no duration field: Threads closes the poll 24 hours after the post is published.
• A poll can't carry media: a request with a poll and media on Threads is refused with 400 validation_error.
• On a thread (thread_parts), the poll goes on the first post.
• GET /posts/:id returns the poll under threads.poll. On PATCH /posts/:id, threads.poll: null removes it.
• Poll results come back in analytics under metrics.poll.

Social Inbox

Replies people leave on your Threads posts, and posts that mention you, land in the Social Inbox. You can reply (published as a native Threads reply) and hide or unhide replies on your own posts via POST /inbox/messages/{id}/hide.

• Conversation types: comment (replies on your posts, grouped per root post) and mention. Threads has no DM API.
• Replies need the Threads reply permission on the connection; otherwise the reply returns 401 reauth_required.
• Only incoming top-level replies on your posts can be hidden; nested replies return 400 not_hideable.
• Replies can't be deleted from OmniSocials.

See the Social Inbox guide for endpoints, payloads, and error handling.

Media requirements

Media	Requirement
Image	JPEG, PNG, or WebP. Max 8 MB. Up to 20 per post.
Video	MP4 or MOV, up to 5 minutes, max 1 GB

Threads supports a single image, a single video, or a carousel of up to 20 items per post. Carousel items can mix images and videos.

Alt text. Threads delivers per-media alt text natively. Pass it by using an object entry instead of a bare string: { "url": "https://example.com/bike.jpg", "alt": "A red bicycle leaning against a brick wall" } in media_urls (or { "id": "...", "alt": "..." } in media_ids, including per-part thread media; we accept up to 1500 characters and send the first 1,000, the most Threads takes). It is sent as the media container's alt_text on images and videos, single posts and carousel items alike.

Limitations

• Threads enforces a 500 character limit per post (and per part of a thread)
• Posting a reply to an arbitrary post is not supported; thread_parts only chains replies to your own previous part, and the Social Inbox replies to replies on your posts and to mentions
• Private Threads accounts cannot be connected
• Location tags are not available on Threads yet: Meta has not approved the location permission for OmniSocials. A post with threads.location_id is rejected with a 400.
• Topic tags, reply controls and quote posts are not supported