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.

Channel ID: threads

Supported content types

Type	Supported
Feed post	✅
Story	-
Reel	-

Minimal example

Code
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.location_id	string	Tag a location on the post. See Location tagging.
threads.location	object	Alternative to location_id: the full search result { id, name, address, city, country }, so your app can show the place name without another lookup. Only id is required; location_id wins when both are given.

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.

Code
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.

• media_urls (or media_ids) is optional per part, up to 10 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:

  Code
  {
    "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.

Location tagging

Tag a physical place on a Threads post by passing threads.location_id. The tag shows on the post like a location tag in the Threads app.

Find an id with the locations search, using platform=threads. You can search by name or by coordinates (latitude + longitude):

Code
curl "https://api.omnisocials.com/v1/locations/search?platform=threads&q=Griffith%20Observatory" \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY"
# -> { "locations": [ { "id": "17841400000000000", "name": "Griffith Observatory",
#      "address": "2800 E Observatory Rd", "city": "Los Angeles", "country": "United States",
#      "latitude": 34.1184, "longitude": -118.3004 } ] }

Then create the post with the id:

Code
curl -X POST https://api.omnisocials.com/v1/posts/create \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": { "default": "Best view in the city 🔭" },
    "accounts": ["your-threads-account-id"],
    "threads": { "location_id": "17841400000000000" }
  }'

Rules:

• Threads location ids are NOT Facebook Place IDs. Never reuse an Instagram location_id here; always search with platform=threads.
• On a multi-post thread (thread_parts), the tag goes on the first post.
• On PATCH /posts/:id, threads.location_id: null (or threads.location: null) removes the tag.
• The connection must have the threads_location_tagging permission; without it, create/update/publish return a 400 naming the reconnect, and the search answers error.code = threads_reauth_required.
• Threads allows 500 location searches per account per rolling 24 hours.

The post object echoes the tag back as threads.location ({ id, name, address, city, country }, with the display fields as you stored them).

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.

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

Media requirements

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

Threads supports a single image, a single video, or a carousel of up to 10 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; max 1500 characters). 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