threads

name	threads
description	When a workflow needs public Threads (Meta) data through UnifAPI — recent and top post search on a term, profiles, or a handle's posts, replies, and reposts. Also use on "what's being said on Threads about," "newest vs top Threads posts," "Threads profile for," or when another skill (social listening, content opportunity) needs the deterministic Threads read path. Connect via the `unifapi` skill first. Read-only research, never posts.
license	MIT
metadata	{"author":"UnifAPI","version":"1.0.0","homepage":"https://unifapi.com/agents/threads","source":"https://github.com/unifapi-agent/agents"}

threads

The deterministic read path for public Threads (Meta) data through UnifAPI. This is a Data Skill: it does not run a marketing job on its own — it names the concrete threads/... operations, response shapes, and gotchas so any text-first listening or content workflow reads from one known recipe instead of rediscovering the surface each time.

Read-only — eyes, not hands. It researches public Threads data and returns cited records; it never posts or replies, and UnifAPI never holds Threads credentials.

Use the unifapi skill for live evidence

Connect once through the shared unifapi skill (OAuth MCP), then call the operations below. Profiles are keyed by {username}. Keep any billing metadata so the output can state record cost.

Response contract

Single-entity endpoints return the object in data:

{
  "request_id": "unif_...",
  "data": {},
  "billing": { "records_charged": 1, "balance_remaining": 99 }
}

List endpoints return an array in data plus pagination:

{
  "request_id": "unif_...",
  "data": [],
  "pagination": { "has_more": false, "next_cursor": null },
  "billing": { "records_charged": 1 }
}

When pagination.has_more is true, pass pagination.next_cursor as the next request's cursor. Always preserve billing when reporting cost.

Core operations

Need	Operation
Newest posts on a term	threads/search/recent (?q=...)
Most-seen posts on a term	threads/search/top (?q=...)
Profiles on a term	threads/search/profiles (?q=...)
Profile by handle	threads/users/{username}
A handle's posts	threads/users/{username}/posts
A handle's replies	threads/users/{username}/replies
A handle's reposts	threads/users/{username}/reposts

Need a field not listed here? Use the unifapi skill's get_operation to read the exact schema before calling — but pick the operation from this table, don't discover blind.

Workflow

The deterministic recipes. Pick the one that matches the job; each names exactly what to call.

1. Set the term. For brand or category listening, call threads/search/recent?q=... (newest) and threads/search/top?q=... (most-seen) together — recent catches the live conversation, top catches the takes that actually spread. Page via next_cursor.
2. Find handles. Call threads/search/profiles?q=... to surface accounts on the term, then threads/users/{username} for follower size and biography.
3. Read a profile's activity. Call threads/users/{username}/posts, .../replies, and .../reposts for what a handle says, answers, and amplifies.
4. Cluster takes. Group text across the recent and top results into questions and opinions; like_count ranks which takes resonate.
5. Cite everything. Every quote ties back to its post or profile; report billing.records_charged (or estimate when billing metadata is absent).

Shape notes

• ThreadsUser — keyed by {username}. full_name, biography, follower_count, is_verified, is_private.
• ThreadsPost — code (the URL segment), text, taken_at, like_count, image_url, video_url, user.

Gotchas

• search/recent is the newest and search/top is the most-seen — use both for a balanced read; either alone skews recency or popularity.
• Posts expose like_count only — there are no reply/repost counts on the post object. Gauge spread from the search/top ranking, not a repost number.
• A private handle (is_private) limits what you can read — surface it.
• A low balance can silently truncate list pages: check billing.truncated_due_to_balance — when true the page is partial.

Output

Return the records the calling workflow needs, each cited to its post or profile, plus a one-line cost note (records_charged). When this skill is used directly, a compact listening brief is the default:

**"{term}" on Threads** — {N} recent / {N} top posts. Takes: {themes}. Loudest: "{quote}" ({likes} likes, by @handle). Evidence: {post URLs}. Records: ~{N}.

Related skills

• social-listening-brief (Social Listening), content-opportunity-brief (Content Strategy) — listening and content-idea work on top of this read path.
• unifapi — the shared data skill: connect MCP and look up exact schemas with get_operation.