Threads API - SocialAPI

The Threads API in SocialAPI connects Threads accounts. It publishes text, image, video, and carousel posts, reads, answers, and moderates replies, reads mentions and insights, and, in beta, looks up public profiles. Threads has no direct messages in the API. SocialAPI’s own Meta Threads app connects the account, so you register nothing: see Platform apps.

At a glance

Field	Value
Platform slug	`threads`
Auth	OAuth 2.0 (Meta Threads)
Platform API	Threads API (Meta)
Status	Available. Profile discovery is in beta

Capabilities

An unsupported call returns 501 resource.not_supported. A Beta row depends on a Threads scope that Meta has not granted to SocialAPI’s app for every account: see Beta scopes. Reply moderation, mentions, and insights need a scope that an account connected before 2026-10-17 does not hold: reconnect such an account to use them.

Feature	Status	Condition
Publish text, image, video, carousel	Yes	See Threads publishing
Reply chains with `segments`	No	A Threads target publishes the first post only and ignores `segments`
Schedule a post	Yes	`scheduled_at` on the post
First comment on a post	No	`first_comment` is not published on Threads
Update a published post	No	`PATCH /v1/posts/{pid}` returns `409 post.state_invalid` for a published post. A `draft`, `scheduled`, or `failed` post can be edited before it publishes. To correct it, delete the post and publish a new one
Delete a published post	Yes
List posts	Yes	Text posts, images, videos, carousels
List replies	Yes	Replies to a post, and replies to a reply
Reply to a reply	Yes
Delete a reply	Conditional	Only replies your account wrote. `can_delete` is `true` on every reply, including other accounts’ replies, and deleting another account’s reply fails
Hide, unhide a reply	Yes	Only replies from other accounts (`can_hide` is `false` on your own replies). Needs the `threads_manage_replies` scope. Without it the call returns `403` with a `platform.threads.<code>` error code, where `<code>` is Meta’s error code
Like a reply	No	`501 resource.not_supported`
Private reply	No	`501 resource.not_supported`
DMs	No	Threads has no messaging API. `501 resource.not_supported`
Reviews	No	`GET /v1/inbox/reviews/{account_id}` returns `422 account.platform_unsupported`
Mentions	Yes	Needs `threads_manage_mentions`. List, reply, and the `mention.received` event
Insights	Yes	Needs `threads_manage_insights`. Post-level and account-level metrics. Without it, `likes` and `comments` in the `metrics` of a Threads post stay `0`
Profile discovery	Beta	Needs `threads_profile_discovery`. Public profile lookup by exact username
Automations	No	Automations run on Instagram and Facebook accounts only. `422 automation.platform_unsupported`
Webhook events	Yes	See Webhook events

The cross-platform matrix is on Platforms.

Connect an account

Connect with POST /v1/accounts/connect and "platform": "threads". The shared flow, request fields, and result are in Connect accounts, and the redirect parameters are in Redirect parameters.

curl -X POST https://api.social-api.ai/v1/accounts/connect \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "threads",
    "redirect_uri": "https://app.example.com/oauth/callback",
    "state": "session_abc123"
  }'

Response (HTTP 202):

{
  "auth_url": "https://www.threads.com/oauth/authorize?client_id=...&state=...",
  "state": "4a8f2c1e9b3d7f06a5c2e8b4d1f3a7e2",
  "message": "Open this link to connect your threads account. Once you've authorized, the account will be connected automatically."
}

A Threads access token lasts about 60 days. SocialAPI refreshes it. If a call returns 401 platform.threads.auth, the person revoked access or the refresh failed: reconnect the account. See Reconnect an account.

Replies

List the replies to a post with GET /v1/inbox/comments/{postId}, where postId is the post’s platform ID. Reply and delete work as described in Comments. Threads calls a comment a reply.

Hide and unhide: only replies from other accounts. They need the scope threads_manage_replies.
Delete: only replies your account wrote, and it works without threads_manage_replies. A reply from another account cannot be deleted: hide it instead.
A like and a private reply return 501 resource.not_supported.

Mentions

A mention is a public Threads post that tags your account. GET /v1/accounts/{id}/mentions lists mentions, and POST /v1/accounts/{id}/mentions/reply replies to one. The mention.received event delivers a mention as it happens, and the list returns the same mention with the same id, so you can match them. Details are in Mentions.

curl "https://api.social-api.ai/v1/accounts/acc_01HZ9X3Q4R5M6N7P8V2K0W1J/mentions?limit=20" \
  -H "Authorization: Bearer $SOCAPI_KEY"

Response (HTTP 200):

{
  "data": [
    {
      "id": "sapi_mnt_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U1I",
      "platform": "threads",
      "type": "mention",
      "author": { "username": "janesmith" },
      "content": { "text": "Great thread, @acmecorp" },
      "metadata": null,
      "received_at": "2026-10-13T14:35:00Z",
      "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
      "platform_post_id": "18012345678901234",
      "permalink": "https://www.threads.com/@janesmith/post/DAbCdEfGhIj"
    }
  ],
  "count": 1
}

Parameter	Description
`since`	An RFC 3339 timestamp. Only mentions after it are returned. A `since` before 2023-07-05T07:00:00Z is treated as 2023-07-05T07:00:00Z
`limit`	Mentions in the response, 1 to 100. The default is 20
`cursor`	Ignored on Threads. The list is 1 page and never returns `next_cursor`: raise `limit` or move `since` to reach other mentions

Reply to a mention:

curl -X POST "https://api.social-api.ai/v1/accounts/acc_01HZ9X3Q4R5M6N7P8V2K0W1J/mentions/reply" \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"media_id": "sapi_mnt_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U1I", "text": "Thanks for the mention!"}'

media_id is the id from the list response. An account connected without threads_manage_mentions gets 403 with a platform.threads.<code> error code on the list, where <code> is Meta’s error code. Reconnect the account to add the scope.

Insights

GET /v1/platforms/threads/insights returns post-level or account-level metrics. It needs threads_manage_insights. Post-level metrics for one post:

curl "https://api.social-api.ai/v1/platforms/threads/insights?account_id=acc_01HZ9X3Q4R5M6N7P8V2K0W1J&level=media&post_id=17895695668004550" \
  -H "Authorization: Bearer $SOCAPI_KEY"

Account-level metrics over a window:

curl "https://api.social-api.ai/v1/platforms/threads/insights?account_id=acc_01HZ9X3Q4R5M6N7P8V2K0W1J&level=account&since=1760000000" \
  -H "Authorization: Bearer $SOCAPI_KEY"

Response (HTTP 200) for level=account:

{
  "data": {
    "metrics": {
      "followers_count": { "value": 1280 },
      "clicks": { "value": 47 },
      "views": {
        "values": [
          { "end_time": "2026-10-11T07:00:00Z", "value": 910 },
          { "end_time": "2026-10-12T07:00:00Z", "value": 1204 }
        ]
      }
    }
  }
}

Each metric comes back as a scalar (value), a dated series (values), or, for follower_demographics, a breakdown. Account-level views is a series, follower_demographics is a breakdown, and the other account-level metrics are scalars.

Level	Metrics
`media`	`views`, `likes`, `replies`, `reposts`, `quotes`, `shares`
`account`	`views`, `likes`, `replies`, `reposts`, `quotes`, `clicks`, `followers_count`, `follower_demographics`

Parameter	Required	Description
`account_id`	Yes	The connected Threads account
`level`	Yes	`media` or `account`
`post_id`	At `level=media`	The post’s platform ID
`metric`	No	Comma-separated metric names from the table above. Default: every metric valid for the `level` except `follower_demographics`
`breakdown`	With `follower_demographics`	`country`, `city`, `age`, or `gender`. Valid only with `follower_demographics`
`since`	No	Unix timestamp in seconds, not earlier than `1712991600` (2024-04-13). Not accepted at `level=media`
`until`	No	Unix timestamp in seconds, not earlier than `1712991600` (2024-04-13). Not accepted at `level=media`

follower_demographics needs exactly one breakdown and rejects since and until.
follower_demographics on an account with fewer than 100 followers returns 422 platform.threads.801.
follower_demographics returns breakdown, a list of { "dimension", "value" } rows, for example { "dimension": "US", "value": 540 } with breakdown=country. dimension is a country code, a city, an age range, or a gender, matching the breakdown you sent.
Metrics for a new post appear after a delay, and a deleted post returns nothing. Both return an empty result, not an error.

The 400 codes for these parameters are in Errors.

Profile discovery

GET /v1/platforms/threads/profile-lookup returns the public profile for an exact username. A leading @ is optional. It needs threads_profile_discovery.

curl "https://api.social-api.ai/v1/platforms/threads/profile-lookup?account_id=acc_01HZ9X3Q4R5M6N7P8V2K0W1J&username=meta" \
  -H "Authorization: Bearer $SOCAPI_KEY"

Response (HTTP 200):

{
  "data": {
    "username": "meta",
    "name": "Meta",
    "profile_picture_url": "https://scontent.cdninstagram.com/v/t51.2885-19/meta.jpg",
    "biography": "Giving people the power to build community.",
    "follower_count": 5400000,
    "likes_count": 12800000,
    "quotes_count": 41000,
    "reposts_count": 96000,
    "views_count": 310000000,
    "is_verified": true
  }
}

The lookup matches the exact username. There is no prefix or fuzzy search.
Only profiles with 100 or more followers are discoverable.
404 resource.not_found means the username is not discoverable. Threads gives the same answer when the account does not exist, has fewer than 100 followers, or is outside the access tier, so the three cases look the same.
Threads allows 1,000 lookups per user per rolling 24 hours. More returns 429 platform.threads.rate_limit.

Webhook events

Threads accounts emit these events to your webhook endpoints. Payloads are in Webhook events.

Event	When it fires
`comment.received`	A person replies to one of your posts
`mention.received`	Another account mentions yours. See Mentions
`account.connected`	You finished connecting or reconnecting the account
`account.disconnected`	The person revoked access to the account on Threads, or SocialAPI flagged the account for reconnection (`reconnect_required: true`, see `reason`)
`account.updated`	The account lost permissions you did not remove yourself (`change` is `permissions_reduced`)
`post.published`, `post.partial`, `post.failed`	A post to this account finished: see Delivery

Every post.* event in Webhook events is emitted for this platform.

Limits

Limit	Value
Post text	500 characters and 1 hashtag
Carousel	2 to 20 items
Image	8 MB: JPEG, PNG, GIF, or WebP
Video	1 GB: MP4 or QuickTime
Links in a post	5 unique links
Posts	250 per 24 hours and 25 per hour for each account: see Posting velocity caps
Replies	1,000 per rolling 24 hours, set by Threads
Threads’ own rate limit	`429 platform.threads.rate_limit`. Credit rules: see when a credit comes back

GET /v1/accounts/{id}/limits returns posts_remaining, posts_total, replies_remaining, and replies_total.

Scopes

SocialAPI’s Meta Threads app requests these scopes at connect. You apply for no app review. Each scope belongs to the account permissions in the last column, and the consent screen asks for the scopes of the permissions you selected. threads_basic is always requested.

Scope	Used for	Permissions
`threads_basic`	Profile and posts	Every account
`threads_content_publish`	Publish posts and replies	`posts.write`, `comments.write`
`threads_delete`	Delete posts and replies	`posts.write`, `comments.write`
`threads_read_replies`	Read replies	`comments.read`
`threads_manage_mentions`	Mentions	`comments.read`
`threads_manage_replies`	Hide and unhide replies, `reply_control` on a post	`comments.write`
`threads_manage_insights`	Insights, and the like and reply counts on posts	`analytics.read`

Threads asks for publishing and deleting as 1 pair of scopes shared by posts.write and comments.write, so the consent screen can show more than you selected. The account stays limited to the permissions you selected. threads_manage_mentions, threads_manage_replies, and threads_manage_insights are requested since 2026-10-17. An account connected before that date does not hold them: a call that needs one returns 403 with a platform.threads.<code> error code, where <code> is Meta’s error code. Reconnect the account to add them.

Beta scopes

These further scopes are requested only for accounts enrolled in the beta:

Scope	Used for	Permissions
`threads_profile_discovery`	Profile discovery	Every account
`threads_location_tagging`	`location_id` on a post	`posts.write`
`threads_share_to_instagram`	`crossreshare_to_ig` on a post	`posts.write`
`threads_keyword_search`	Requested with `threads_profile_discovery`. No SocialAPI endpoint uses it	Every account

Until Meta grants a scope for every account, a call that needs it from an account without it returns 403 with a platform.threads.<code> error code, where <code> is Meta’s error code. A beta scope is added when the account connects: reconnect the account to add one granted later.

Threads publishing: fields, media rules, and quirks for publishing
Connect accounts: the shared connect flow
Platforms: the capability matrix
Errors: every error code

​At a glance

​Capabilities

​Connect an account

​Replies

​Mentions

​Insights

​Profile discovery

​Webhook events

​Limits

​Scopes

​Beta scopes

​Related