threads_search_posts

Search public Threads posts by keyword or topic tag, with filters for media type, author, and date range to find relevant content.

Instructions

Search for public Threads posts by keyword or topic tag. Results can be filtered by media type and author.

Input Schema

TableJSON Schema

Name	Required	Description
`q`	Yes	Search keyword or query
`search_type`	No	Search by keyword or topic tag (default: keyword)
`media_type`	No	Filter results by media type
`author_username`	No	Filter results by author username
`since`	No	Start date (Unix timestamp)
`until`	No	End date (Unix timestamp)
`limit`	No	Number of results
`after`	No	Pagination cursor

Implementation Reference

src/tools/threads/media.ts:55-87 (handler)

The tool "threads_search_posts" is registered and handled within the `registerThreadsMediaTools` function in `src/tools/threads/media.ts`. It takes several optional parameters to filter Threads posts and performs a GET request to the Threads search API.

server.tool(
  "threads_search_posts",
  "Search for public Threads posts by keyword or topic tag. Results can be filtered by media type and author.",
  {
    q: z.string().describe("Search keyword or query"),
    search_type: z.enum(["keyword", "tag"]).optional().describe("Search by keyword or topic tag (default: keyword)"),
    media_type: z.enum(["TEXT", "IMAGE", "VIDEO", "CAROUSEL"]).optional().describe("Filter results by media type"),
    author_username: z.string().optional().describe("Filter results by author username"),
    since: z.string().optional().describe("Start date (Unix timestamp)"),
    until: z.string().optional().describe("End date (Unix timestamp)"),
    limit: z.number().optional().describe("Number of results"),
    after: z.string().optional().describe("Pagination cursor"),
  },
  async ({ q, search_type, media_type, author_username, since, until, limit, after }) => {
    try {
      const params: Record<string, unknown> = {
        q,
        fields: "id,text,username,permalink,timestamp,media_type,media_url,topic_tag",
      };
      if (search_type) params.search_type = search_type;
      if (media_type) params.media_type = media_type;
      if (author_username) params.author_username = author_username;
      if (since) params.since = since;
      if (until) params.until = until;
      if (limit) params.limit = limit;
      if (after) params.after = after;
      const { data, rateLimit } = await client.threads("GET", `/${client.threadsUserId}/threads_search`, params);
      return { content: [{ type: "text", text: JSON.stringify({ ...data as object, _rateLimit: rateLimit }, null, 2) }] };
    } catch (error) {
      return { content: [{ type: "text", text: `Search posts failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true };
    }
  }
);

meta-mcp