# 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](/en/api/guides/search-examples/). [Semantic search](/en/api/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.

:::note[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](/en/api/keyword-monitoring/#total-volume-across-spellings).

To send several keywords, repeat the same parameter:

```bash
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](/en/api/guides/regions/).

## 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](/en/api/keyword-monitoring/#2-see-the-volume-trend).

:::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.