Threads tool

The Threads tool lets an agent manage a Threads (by Meta) account — publish text/image/video/carousel posts and replies, read the profile, threads, replies, conversations and mentions, search Threads, moderate replies, view insights, and delete posts. 16 actions behind one credential: a Threads user access token.

Connect Threads

Threads tokens come from the Threads API (a Meta app with the Threads use case), not the regular Facebook Graph:

1. In developers.facebook.com, create/open an app and add the Threads API use case.
2. Add the Threads testers (your Threads account) and accept the invite in the Threads app (Settings → Account → Website permissions).
3. Generate a user access token with the scopes you need.
4. Copy the token — it starts with TH… — and paste it into the Threads Access Token field. Stored encrypted, never shown again.

Scope checklist

• threads_basic (required), threads_content_publish (to post).
• Optional: threads_manage_replies, threads_manage_insights, threads_read_replies, threads_manage_mentions, threads_keyword_search, threads_delete, threads_location_tagging.

Actions (16)

• Publish — publish (auto-detects text / image / video / carousel from text / image_urls / video_url), reply (same + reply_to_id).
• Read — get_profile, list_threads (+ since/until/limit), get_thread (id), list_replies (id), get_conversation (id), list_user_replies, get_mentions.
• Search — keyword_search (q, search_type TOP/RECENT), location_search (q) → location ids for tagging.
• Moderate — manage_reply (id, hide) — needs threads_manage_replies; you can hide others' replies, not your own.
• Insights — get_post_insights (id, metric), get_user_insights (metric, since/until).
• Utility — get_publishing_limit, delete_post (id).

Publishing guide

• Media must be public — image_urls / video_url must be reachable by Meta's servers; some hosts block it, so use a CDN/public URL. Publishing is async under the hood (containers are processed then published — the tool polls); large videos take longer.
• Carousel — pass several image_urls; a single one is an image post.
• reply_control — who can reply: everyone / accounts_you_follow / mentioned_only.
• Extras — alt_text (accessibility), link_attachment (link preview on a text post), quote_post_id (quote a post), topic_tag (one per post, no #), location_id (from location_search).

Common recipes

• Post an update — publish with text (add image_urls for media).
• Reply to a mention — get_mentions → reply with reply_to_id.
• Find what's trending on a keyword — keyword_search (search_type: TOP).
• Check post performance — get_post_insights for a post id.

Behaviors & gotchas

• manage_reply moderates others' replies — "Cannot Hide Own Reply" is expected, not a setup error.
• Publishing limit is per-account (e.g. 250/day) — check with get_publishing_limit.
• It's a tool, not a Threads channel — the agent posts/reads on demand; there's no inbound "DM the bot on Threads" path.

Errors & limits

Threads returns the Meta envelope {error:{message, type, code, error_user_title, error_user_msg}} — the error_user_title / error_user_msg are the human-readable bits (e.g. "Cannot Hide Own Reply", "Media download has failed"):

• 400 — bad media/params.
• 401 / code 190 — token invalid or expired; regenerate it.
• 403 — missing scope (regenerate the token with the scope added).

Classification & lifecycle

This is a read and write tool, and it can delete posts and hide replies. If you run it on an autonomous bot, set its safety classification to match. It's post-call-hook eligible (runs outside the LLM turn) — e.g. a scheduled "post to Threads" agent.