At a glance
Capabilities
Connecting
auth_url. After they authorize, SocialAPI exchanges the code with Threads and redirects the user to your redirect_uri with the connection result. See OAuth flows for the redirect parameters.
Reading samples
List posts
List comments on a post
Beta endpoints
These are live for beta accounts and gated on scopes still pending Meta App Review. See Beta scopes pending review.Insights
Post-level metrics for one post:views is a series; the rest are scalars.
since and until:
Profile discovery
Look up a public profile by exact username. A leading@ is optional.
404 means the username is not discoverable. Meta returns the same response whether the account does not exist, has fewer than 100 followers, or falls outside the access tier, so the three cases cannot be told apart.
Mentions
Mentions use the standard mentions routes, which now cover Threads:Publishing
Create a Threads post with optional platform-specific fields:Limitations and gotchas
- Moderation. Hide, unhide, and delete are supported. Unsupported moderation actions return
501. - No post updates. Threads does not support editing published posts. Use delete and re-create if needed.
- Publishing. Supports text posts, single images, single videos, and carousel posts.
- Mentions have two paths. The webhook delivers mentions in near real time but carries no message text: Meta’s payload has only the post id, the mentioning username, and the media id. The polling endpoint returns the text. Use polling where the text matters, and the webhook to know when to poll.
- Insight metric sets differ by level. Post-level metrics are
views,likes,replies,reposts,quotes, andshares. Account-level metrics are those five minusshares, plusclicks,followers_count, andfollower_demographics.sharesis post-only andclicksis account-only. follower_demographicsis fussy. It needs exactly onebreakdown(country,city,age, orgender), it rejectssinceanduntil, and Meta returns nothing unless the account has 100 or more followers.- Insights lag publishing. Metrics for a new post can take a few minutes to appear, and deleted posts return nothing. Both come back as an empty result rather than an error.
- Insight date range floor. Insight queries reject timestamps before
1712991600(2024-04-13). Mentions use a different floor,1688540400. - Profile discovery is exact-match only. There is no fuzzy or prefix search, only profiles with 100 or more followers are discoverable, and the budget is 1000 lookups per user per rolling 24 hours.
- Token refresh. Threads tokens can expire. SocialAPI handles refresh automatically. If you receive
401withcode: "platform.threads.auth", reconnect the account.
Permissions
SocialAPI’s managed Meta Threads App already requests these scopes on your behalf:threads_basic, threads_content_publish, threads_read_replies, threads_delete. You don’t need to apply for any platform app review. See Platform credentials.
Beta scopes pending review
Four further scopes are submitted to Meta but not yet granted:threads_manage_replies, threads_manage_insights, threads_manage_mentions, and threads_profile_discovery.
The endpoints behind them are built and documented, and they are requested only for accounts enrolled in the beta. Until Meta grants a scope, calls that depend on it return an upstream authorization error for any account outside our app’s tester roster. Nothing you need to do: the scopes are added to your connection automatically once approval lands.