> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Threads API

> Options for posting using the Threads API

<Info>
  Threads publishing fetches media from your URL via Meta's server-side crawler.
  If you see Ayrshare error code 379 — especially alongside an Instagram error 440 or 138 in the same
  publish — see [Meta Media Crawler Blocked](/help-center/technical-support/meta_media_crawler_blocked).
</Info>

## Posting to Threads

JSON for a basic post with a link and image using the Threads API:

```json Threads Post theme={"system"}
{
  "post": "The best Threads post ever #best #awesome https://www.threads.net", // empty string is allowed
  "mediaUrls": ["https://img.ayrshare.com/012/gb.jpg"],
  "platforms": ["threads"]
}
```

The Threads API has the following requirements and restrictions:

<ul class="custom-bullets">
  <li>
    Threads will automatically preview the link in the post unless there is an image or video
    included. In the above example the image will show. Removing the image will cause the link
    preview to show.
  </li>

  <li>Threads profiles are limited to 250 API-published posts within a 24-hour moving period.</li>
  <li>Threads only allows 1 hashtag per post.</li>
  <li>@mention Threads users will receive a notification.</li>
  <li>Maximum 500 post characters.</li>

  <li>
    Multi-image/videos posts are supported and sent as a carousel. You may send up to 20 videos and
    images.
  </li>

  <li>
    Threads does not support deletes via an API. Deletes must occur manually using the Threads app.
  </li>

  <li>
    If your video doesn't end in a known video extension such as mp4, please use the `isVideo`
    parameter. See the [/post endpoint](/apis/post/post) for details.
  </li>

  <li>
    Threads also supports sending media without post text. If you do not want post text included
    send an empty String `post: ""`.
  </li>

  <li>
    See [Threads Media Guidelines](/media-guidelines/threads) and [Threads
    Authorization](/dashboard/connect-social-accounts/threads) for more information.
  </li>
</ul>

## Threads Options

You can set additional options for a post by using the `threadsOptions` parameter.

```json Threads Options theme={"system"}
{
  "threadsOptions": {
    "allowCountries": ["US", "CA"],
    "thread": true,
    "threadNumber": true,
    "mediaUrls": ["https://img.ayrshare.com/012/gb.jpg"] // used when sending as a thread of threads
  }
}
```

Threads options are optional fields that can be used to control the post.

<ParamField body="allowCountries" type="array of strings">
  Restrict posts to specific countries using country codes. Use [country codes](/iso-codes/country).

  Only available if Meta has enabled geo restrictions for your account.

  See [Threads Geo Restrictions](/apis/post/social-networks/threads#geo-restrictions) for more information.
</ParamField>

<ParamField body="thread" type="boolean" default={false}>
  Break long posts into a connected thread series with optional numbering and media.

  See [Thread](/apis/post/social-networks/threads#thread) for more information.
</ParamField>

<ParamField body="threadNumber" type="boolean" default={false}>
  Automatically add numbers at the end of each thread in the format of 1/n.

  Requires `thread: true`.
</ParamField>

<ParamField body="mediaUrls" type="array of strings">
  Add media objects to a thread of threads. One media object will be added to each thread in order.

  Use `null` to skip media for a specific thread. Use objects with multiple URLs for multiple media per thread.

  See [Thread Media](/apis/post/social-networks/threads#thread-media) for more information.
</ParamField>

## Adding line breaks or rich text to an Threads post

Threads line breaks can be added to a post with a special [new line character](/apis/post/post#line-breaks).

Rich text, such as bold or italic lettering, can be added to a Threads post with a few [html elements](/apis/post/overview#rich-text-posts).

## Carousel of Images and Videos

You can post multiple images or videos to Threads as a carousel; up to a combined total of 20 images or videos may be use in a carousel. Just add your additional images or videos to the `mediaUrls` array and the carousel will automatically be created.

```json theme={"system"}
"mediaUrls": ["https://url.com/image.jpg", "https://url.com/video.mp4" ...];  // Max 20 images or videos
```

Video URLs must end in a known extension such as mp4.

## Character Limits

Please see [Threads Character Limits](/help-center/technical-support/character_limits#threads-character-limits) for more information.

## Geo Restrictions

You can restrict a post to a specific country or countries by using the `allowCountries` array.

```json theme={"system"}
{
  "threadsOptions": {
    "allowCountries": ["US", "CA"]
  }
}
```

<ul class="custom-bullets">
  <li>
    `allowCountries`: An array of country codes to allow. See [country codes](/iso-codes/country).
  </li>
</ul>

<Warning>
  Geo restrictions (geo-gating) on Threads are only available if Meta has enabled this feature for your account.

  Meta decides which Threads accounts are eligible for geo restrictions based on factors such as account verification, follower count, or content creator status.
  If your account is eligible, you will see the geographic settings (globe icon) in the post composer when creating a new Threads post.

  You can check if a user profile is eligible for Threads geo restrictions by checking the `isEligibleForGeoRestrictions` property in the [/user](/apis/user/profile-details) endpoint.
</Warning>

## Threads Mentions

Mention another Threads handle by adding @handle in the post text. For example:

```json theme={"system"}
{
  "post": "The best social media API @Ayrshare ever!",
  "mediaUrls": ["https://images.com"],
  "platforms": ["threads"]
}
```

<Warning>
  The @mentioned user will be notified of the mention. Please review the [important
  rules](/testing/post-verification#mentions) on mentions.
</Warning>

If the quota has been reached, an error message will be returned.

## Thread

A Threads thread, also known as a threadstorm, is a connected series of posts on Threads that allows you to share longer ideas beyond a single post's character limit, appearing as one continuous narrative when viewed together.

### Posting a Thread

A Threads thread can be posted via the API. A thread is a post broken up into a set of reply posts associated together in Threads. You can either automatically break up the post or specify the [thread breaks](/apis/post/social-networks/threads#thread-breaks) in the post text.

```json Threads Thread theme={"system"}
{
  "threadsOptions": {
    "thread": true,        // required for threadstorm
    "threadNumber": true,  // optional to add numbers to each thread
    "mediaUrls": ["https://site.com/image1.png", "https://site.com/image2.png", ...]  // optional one media object is added to a thread in order
  }
}
```

<ul class="custom-bullets">
  <li>
    `thread: true` to automatically break apart the post text into threads based on line breaks.
  </li>

  <li>
    `threadNumber: true` to automatically add numbers at the end of threads in the format of 1/n.
    For example, the 2nd of 5 threads will have appended: 2/5
  </li>

  <li>
    `mediaUrls: [array of urls]` to add each media object, an image or video, to a thread in order.
    Only one media object will be added to a thread in order.
  </li>
</ul>

#### Thread Media

##### Skip Media

Skip media for a thread by using `null` in the array. For example:

`["https://site.com/image1.png", null, "https://site.com/image2.png"]`

This will place image1 on the first post, no image on the second post, and image2 on the third post.

##### Multiple Media

Multiple media objects can be added to a single post within a thread by adding an object `{}` with the media URLs in the `mediaUrls` array. Any unique object keys can be used. For example:

```json Threads Thread with Multiple Media URLs theme={"system"}
{
  "threadsOptions": {
    "thread": true,
    "threadNumber": true,
    "mediaUrls": [
      "https://img.ayrshare.com/random/photo-1.jpg",
      {
        "1": "https://img.ayrshare.com/random/photo-2.jpg",
        "2": "https://img.ayrshare.com/random/photo-3.jpg"
      },
      "https://img.ayrshare.com/random/photo-4.jpg"
    ]
  }
}
```

In this example, the first post will contain photo-1.jpg, the second post photo-2.jpg and photo-3.jpg, and the third post photo-4.jpg.

#### Thread Breaks

Ayrshare automatically breaks up the post text into appropriate length posts (> 500 characters) for Threads. When creating threads, we prioritize keeping complete sentences in one post when possible. If a sentence won't fit, we split between sentences. For very long sentences, we split between words. In rare cases where a word is too long, we split the word itself.

You may also manually add paragraphs with `\n\n` to the post text to indicate a unique thread should be created. If you have `\n\n` in the post text, we will not automatically break the post into threads.

For example:

```json Example Threads Thread theme={"system"}
{
  "post": "This is post 1\n\nThis is post 2.",
  "platforms": ["threads"],
  "threadsOptions": {
    "thread": true
  }
}
```

will result in two posts in the thread.

If you want to add paragraphs, but not break into posts, use `\u2063\n\u2063\n`.

```json Threads Thread with Paragraphs theme={"system"}
{
  "post": "This is paragraph 1\u2063\n\u2063\nThis is paragraph 2.",
  "platforms": ["threads"],
  "threadsOptions": {
    "thread": true
  }
}
```

will result in one post with two paragraphs since the post is below 500 characters.

### Delete a Thread

Threads does not support deletes via an API. Deletes must occur manually using the Threads app.