Threads keyword matching rules (API and MCP)

This page explains how keyword search matches posts. It applies to:

• GET /post/search and the MCP tool search_posts
• GET /post/keyword-trend and the MCP tool get_keyword_trend

For examples, see Keyword examples and lists. Semantic search matches by meaning, so the rules on this page don’t apply to it.

The short version

Each keyword is treated as one whole phrase: a post is found only if its text contains that phrase. What counts as “contains” depends on the language:

Language	How it matches	Found	Not found
Chinese	Character by character; the characters must be contiguous	蛋白 → 高蛋白質早餐	減脂 → 減少脂肪
English posts	By word, case-insensitive; singular, plural and other word forms match each other	app → apps, App Store	AI → OpenAI
English and numbers in other posts	Whole words, case-insensitive	AI → AI設計, #ai, 用 AI 寫文案	AI → paid, Taiwan, OpenAI; app → apps
Japanese (kanji, hiragana)	Character by character, same as Chinese	お金 → お金持ち	—
Japanese (katakana)	Whole katakana words	コーヒー → コーヒーを飲む	コーヒー → アイスコーヒー
Korean	Whole words separated by spaces	꿀팁 → 오늘의 꿀팁	꿀팁 → 꿀팁을 공유

Chinese: character by character

Every character of a Chinese keyword must appear in the post in order and next to each other.

• 減脂 (fat loss) finds 「減脂餐」 and 「我在減脂」
• 減脂 doesn’t find 「減少脂肪」 (“reduce fat”), because the characters aren’t next to each other
• 蛋白 (egg white / protein) also finds 「蛋白質」 (protein), because 蛋白 does appear there contiguously

A few details that are easy to miss:

• Traditional and Simplified don’t match each other. 減肥 doesn’t find 「减肥」. To find both, send both as keywords.
• Punctuation and spaces are ignored. 減脂 also finds text like 「減，脂」 or 「減 脂」 where punctuation or a space sits between the characters.
• A single character matches broadly. 貓 (cat) finds every post containing 貓, including 「熊貓」 (panda) and 「貓咪」 (kitty). Use at least two characters.

English and numbers: by word

English doesn’t look for “these letters somewhere in the text”. It matches by word, and it’s case-insensitive.

• coffee, Coffee and COFFEE give the same results
• AI finds 「AI設計」, 「#AI」 and 「AI-generated」: English touching Chinese, a hashtag or a hyphen still counts as a separate word
• AI doesn’t find “paid”, “said” or “Taiwan”, and it doesn’t find “OpenAI” or “ChatGPT” either, because each of those is a whole word of its own
• gram doesn’t find “Instagram” or “Telegram”

For a keyword made of several English words, the words must appear in order: work from home finds 「Work From Home 一年心得」 but not 「#workfromhome」 written as one word. If a name has several spellings, send each spelling as its own keyword.

English posts

When you search English posts (language=en), each word in the keyword and the post is reduced to its base form before matching:

• Singular, plural and other word forms match each other: app also finds “apps”, and post also finds “posts” and “posting”.
• Common words such as the, a and of are ignored, so they don’t affect matching.

English in Chinese, Japanese and Korean posts

English inside Chinese, Japanese and Korean posts matches whole words, and singular, plural and tenses aren’t merged: app doesn’t find “apps”.

Japanese

• Kanji and hiragana: character by character, the same as Chinese. お金 finds 「お金持ち」.
• Katakana: matches whole katakana words. コーヒー finds 「コーヒーを飲む」 and 「コーヒー豆」 (the katakana word ends there), but not 「アイスコーヒー」 or 「コーヒーショップ」, because those are each one longer katakana word.

To cover compound words, send the common combinations too, for example コーヒー, アイスコーヒー and コーヒーショップ.

Korean

Korean matches whole words separated by spaces. Korean attaches particles directly to nouns, so:

• 꿀팁 finds 「오늘의 꿀팁」 and 「꿀팁!」
• 꿀팁 doesn’t find 「꿀팁을 공유합니다」 or 「꿀팁이」: 꿀팁을 and 꿀팁이 are each a whole word of their own

Send the common particle forms as well, for example 꿀팁, 꿀팁을, 꿀팁이 and 꿀팁은. /post/search takes up to 30 keywords at a time.

Planned

We’re improving katakana and Korean matching so that コーヒー also finds 「アイスコーヒー」 and 꿀팁 also finds 「꿀팁을」. We’ll update this page when it ships.

How multiple keywords combine

• /post/search: keywords are combined with OR. A post that matches any keyword appears in the results, and each post appears only once. Up to 30 keywords at a time. AND isn’t supported yet.
• /post/keyword-trend: each keyword gets its own trend line, counted independently. Up to 10 keywords at a time. The same post can count toward several lines, so you can’t simply add the lines together. See Total volume across spellings.

To send several keywords, repeat the same parameter:

curl -G 'https://premium-api.throk.ai/post/search' \
  -H 'Authorization: Bearer sk-throk-...' \
  --data-urlencode 'keywords=減脂' \
  --data-urlencode 'keywords=減肥' \
  --data-urlencode 'keywords=减肥'

Hashtags

A post’s hashtags are searched together with its text, and you don’t need to add #: 減脂 and #減脂 give the same results. A post tagged 減脂 is found even if 減脂 doesn’t appear in its text.

Which posts are searched

• Chinese, English, Japanese and Korean posts. Posts in other languages aren’t searched.
• Replies are searched too. Results include both top-level posts and replies by default, and keyword trend counts include replies. In /post/search, set post_type=thread for top-level posts only, or post_type=reply for replies only.
• One language per search: set language to zh (all Chinese, the default), zh-Hant, zh-Hans, yue, en, ja or ko. See Post language.

Search time range

Endpoint	When no time is set	Furthest back
/post/search	Last 7 days	90 days (for any time filter)
/post/keyword-trend	Last 7 days (days=7)	90 days (days up to 90)
/post/hot	Last 24 hours	30 days
/post/semantic-search	Last 30 days	30 days

• Time parameters always use UNIX seconds (for example 1790000000).
• Keyword search data is kept for about 90 days. Older posts can’t be found by keyword.
• Keyword trend splits days at 00:00 Taiwan time (UTC+8), and the last day is a partial count of “today so far”. Counts for the last two days will still go up. See Keyword monitoring.

Caution

When no time is set, /post/search searches the last 7 days. For older posts, set from_timestamp or max_age_hours, up to 90 days back.

How fresh are likes and replies

The likes and replies in search results are the numbers from the last time Throk fetched that post. New posts and posts that are going viral are refreshed more often. Older or less popular posts are refreshed less often, so their numbers may be lower than what you see on Threads.

When you need the current numbers, use GET /live/posts (MCP: get_live_posts), which reads the latest data from Threads live.