> ## Documentation Index > Fetch the complete documentation index at: https://docs.social-api.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Base URL: https://api.social-api.ai/v1. Send your API key in the Authorization header: Authorization: Bearer . > Every error response from /v1 is JSON: { "error": { "code", "message", "meta" (optional) }, "request_id" }. Branch on error.code; use error.message only for logs. > A 429 response carries a Retry-After header, in seconds, when the limit has a known wait. > Paginated list endpoints return next_cursor, at the top level or inside pagination (see /guides/pagination). Pass it as the cursor query parameter to get the next page. An absent or empty next_cursor means you have the last page. > Treat every ID as an opaque string: do not parse it or assume a format. > Support differs by platform and by operation. Check /platforms/overview before assuming an operation works on a platform. An unsupported operation returns 501 with error.code resource.not_supported. # Threads API > Connect Threads accounts to publish text, image, video, and carousel posts, read and moderate replies, and read mentions and insights through one API. 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](/guides/platform-credentials). ## 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](#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](/platforms/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.` error code, where `` 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](#webhook-events) | The cross-platform matrix is on [Platforms](/platforms/overview). ## Connect an account Connect with `POST /v1/accounts/connect` and `"platform": "threads"`. The shared flow, request fields, and result are in [Connect accounts](/guides/connect-accounts), and the redirect parameters are in [Redirect parameters](/guides/connect-accounts#redirect-parameters). ```bash theme={null} 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): ```json theme={null} { "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](/guides/connect-accounts#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](/guides/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](/guides/mentions). ```bash theme={null} curl "https://api.social-api.ai/v1/accounts/acc_01HZ9X3Q4R5M6N7P8V2K0W1J/mentions?limit=20" \ -H "Authorization: Bearer $SOCAPI_KEY" ``` Response (HTTP 200): ```json theme={null} { "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: ```bash theme={null} 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.` error code on the list, where `` 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: ```bash theme={null} 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: ```bash theme={null} 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`: ```json theme={null} { "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](/guides/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`. ```bash theme={null} 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): ```json theme={null} { "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](/guides/webhook-events). | Event | When it fires | | - | - | | `comment.received` | A person replies to one of your posts | | `mention.received` | Another account mentions yours. See [Mentions](#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](/guides/permissions) you did not remove yourself (`change` is `permissions_reduced`) | | `post.published`, `post.partial`, `post.failed` | A post to this account finished: see [Delivery](/guides/delivery) | Every `post.*` event in [Webhook events](/guides/webhook-events#posts) 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](/guides/rate-limits#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](/guides/plans#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](/guides/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.` error code, where `` 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.` error code, where `` is Meta's error code. A beta scope is added when the account connects: reconnect the account to add one granted later. ## Related * [Threads publishing](/platforms/threads/publishing): fields, media rules, and quirks for publishing * [Connect accounts](/guides/connect-accounts): the shared connect flow * [Platforms](/platforms/overview): the capability matrix * [Errors](/guides/errors): every error code This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.