threads/
search

Query the Threads Search API by keyword or hashtag for the top posts the app shows, about 20 per search, each with text, author, likes, replies, reposts, media and publish time.

Threads Search API

Keyword or hashtag query
Top posts as Threads ranks them
Likes, replies and reposts
0.6 credits / result
Ready
Ready

Enter parameters and send a request. The task status and normalized results will appear here.

README

By SocQ · Updated

Threads Search

Threads search surfaces the posts the app ranks highest for a keyword or hashtag, and every one of them comes with its text, author, publish time, attached images or video and counts of likes, replies and reposts. That makes it a quick read on how a topic, product or event is being talked about right now and on which accounts are steering the conversation.

Threads Search API Features

  • One query, the top postsPut a keyword or hashtag in query and the Threads Search API returns the top posts Threads shows for it, about 20, in the ranking the app uses.
  • Likes, replies and reposts on each resultmetrics.likes_count, metrics.comments_count for replies and metrics.shares_count for reposts show which results are pulling the most attention.
  • The accounts behind each postauthor returns username, display name, profile url, avatar and is_verified, so the people leading a topic are identified alongside what they said.
  • Media and timingmedia lists attached images or video with their dimensions, and published_at dates every post for recency checks.

Threads Search API Parameters

ParametersRequiredDescription
queryRequiredThe keyword or hashtag to search, such as basketball or a campaign hashtag. One query per request.

How to Use the Threads Search API

Send a query to the Threads Search API and read the top posts once the task finishes.

  1. POST {"query": "basketball"} to /v1/threads/search and keep the returned task_id.
  2. Poll GET /v1/tasks/{task_id} until it reports succeeded.
  3. Read the posts in results.items; if has_more is true, request the remainder with results.next_cursor.
curl -X POST "https://api.socq.ai/v1/threads/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"basketball"}'

# 0.6 credits per post returned; a search with no matches is free.

Threads Search API Use Cases

  • Taking the pulse of a topic: Search a product, event or issue and read the text of the top posts to see what angles and opinions lead the discussion.
  • Identifying voices that drive a conversation: Rank the authors of the results by the likes and reposts their posts earned, and note which are verified, to build an outreach or watch list.
  • Monitoring a brand name or hashtag: Run the same query on a schedule, keep new post ids and their published_at, and you have a running log of fresh mentions.

Threads Search API Pro Tips

  • Split a broad subject into several narrower queries, such as product names, spelling variants and related hashtags, since each search returns about 20 top posts.
  • Merge results from overlapping queries by id so a post that ranks for two searches is counted once.
  • Read metrics.comments_count as the reply count and metrics.shares_count as the repost count when you label columns in reports.
  • Pass the url of any result to Threads Post Replies API when you need the conversation underneath it.

Beyond the Threads Search API, use these APIs when you need a different type of public Threads data.

  • Threads Posts API — Collect public post text, author context, media, timestamps, and visible engagement from supported Threads post URLs.
  • Threads Profiles API — Collect public profile identity, biographies, images, websites, visible account counts, and collection context from supported Threads profile URLs.
  • Threads User Posts API — Discover public posts from Threads profile URLs with a per-profile limit, normalized content, authors, media, timestamps, visible engagement, and source context.
  • Threads Post Replies API — Collect the replies under Threads posts from post URLs, with reply text, authors, like and reply counts, media and the ID of the post answered.
  • Threads User Search API — Find Threads accounts by name or username, returning usernames, display names, profile URLs, avatars and verification status.
  • Threads User Replies API — Collect the latest public replies an account has posted from Threads profile URLs, with reply text, engagement, media and links.

Explore other platforms

Combine Threads data with public data from other supported social platforms.

Threads Search API — FAQ

Threads Search API is a programmatic interface for searching public Threads posts by keyword or hashtag. It returns the top posts for the query with their text, author, likes, replies, reposts, media and publish time.

Put the hashtag in query the same way you would a keyword, and the posts Threads ranks for that tag come back.

About 20, in the order Threads ranks its top results for the query. Sort by published_at yourself when you need the newest first.

The Threads Search API charges 0.6 credits for each post returned, so a full search of about 20 posts comes to roughly 12 credits.