# Semantic search on Threads with the Throk API

`GET /post/semantic-search` finds posts by **meaning**, not by matching literal keywords. Describe what you're looking for in one sentence, and the API returns the posts from the last 30 days that are closest in meaning.

## When to use semantic search and when to use keyword search

Say you want posts from office workers complaining about their boss and wanting to quit. With `/post/search` you have to list the keywords yourself: 離職 (quit), 辭職 (resign), 慣老闆 (bad boss), 遣散 (layoff)… The list never ends, and many posts don't use any of those words. With semantic search, one sentence is enough:

> 上班族被老闆氣到想離職

("An office worker so fed up with the boss that they want to quit.") The results include posts that say they're handing in their notice, resigning or being laid off, and even posts that use none of those words and just complain about a manager.

On the other hand, if you're looking for **specific words**, such as a brand name, an account, a campaign hashtag or a product model, use `/post/search`. Semantic search performs poorly on one- or two-character keywords (see the score guide below).

| Situation | Use |
| --- | --- |
| You know the topic but can't list every keyword | Semantic search |
| You want posts about a situation or a mood | Semantic search |
| Monitoring a brand name, an account or a specific term | `/post/search` |
| You need data older than 30 days | `/post/search` |
| You need replies included | `/post/search` |

## Quickstart

```bash
curl -G 'https://premium-api.throk.ai/post/semantic-search' \
  -H 'Authorization: Bearer sk-throk-...' \
  --data-urlencode 'query=新手第一次去健身房不知道要練什麼' \
  --data-urlencode 'size=10'
```

The query means "a beginner going to the gym for the first time and not knowing what to train".

Response (excerpt):

```json
{
  "results": [
    {
      "post": {
        "url": "https://threads.com/post/DaXXXXXX",
        "caption": "健身新手要怎麼練 怎麼吃 那麼多器械要怎麼選 求大佬指教",
        "like_count": 12,
        "reply_count": 3,
        "post_timestamp": 1784402170
      },
      "user": { "username": "...", "full_name": "..." },
      "score": 0.990
    }
  ],
  "credits_consumed": 30
}
```

Results are sorted by relevance, and each one includes the full post and author data.

## How to read the score

Each result's `score` is the semantic similarity between the query and the post, from 0 to 1:

- **0.98 and above**: strongly related, ready to use
- **0.95–0.98**: broadly related, but may include results where the topic looks similar and the subject is wrong (for example, a search about children who can't sleep picking up posts about pets who can't sleep)
- **Below 0.95**: treat as noise

A fragment that isn't a complete idea (for example just 蛋白, "protein" or "egg white") scores no higher than 0.92–0.94, and unrelated posts score just as high in that band, so you can't filter them out. A term that is a complete topic on its own, such as 台南美食 (Tainan food), works fine and can score 0.98 or higher.

:::tip
If the top score you get back is below 0.96, the query isn't a good fit for semantic search. Keyword matching with `/post/search` will be more accurate.
:::

## How to write a query

Testing with 台南美食 (Tainan food), three styles of query lean in different directions:

- **A set of keywords on one topic**: `台南美食 台南小吃 台南餐廳推薦` (Tainan food, Tainan snacks, Tainan restaurant picks). Several terms on the same topic keep the topic focused. This is the most reliable style, and two or three terms are enough. They must all be about the **same** topic. Query unrelated topics separately.
- **A full sentence**: `去台南玩有什麼在地美食推薦` ("Any local food recommendations for a trip to Tainan?"). Results stay close to the situation in the sentence. Because this one is a question, most results are also posts asking for recommendations. To find food reviews, describe the content as a statement.
- **A single topic term**: `台南美食`. It works, but tends to pull in very short posts and results from nearby cities.

For high-engagement posts, add `min_like_count`. You don't need to rewrite the query.

## Parameters

| Parameter | Description | Default |
| --- | --- | --- |
| `query` | One sentence describing what you're looking for, 2–200 characters | Required |
| `size` | Number of results, 10–3000 | 10 |
| `language` | Post language: `zh`, `zh-Hant`, `zh-Hans`, `yue`, `en`, `ja` or `ko`. See [Post language](/en/api/guides/regions/) | `zh` |
| `exclude_hk` | Exclude Cantonese (`yue`) posts. Only applies with `language=zh` | `false` |
| `from_timestamp` | Start time (UNIX seconds), up to 30 days back | 30 days ago |
| `to_timestamp` | End time (UNIX seconds) | Now |
| `min_like_count` | Keep only posts with at least this many likes | No filter |
| `min_reply_count` | Keep only posts with at least this many replies | No filter |

`min_like_count` and `min_reply_count` filter the top-ranked semantic candidates, so with a threshold set you may get fewer results than `size`. If the threshold is too high (for example 1,000 likes), a niche topic may return nothing at all.

Example: find posts from the last week about fat loss with at least 100 likes (the query asks "what can you actually eat while cutting?"):

```bash
curl -G 'https://premium-api.throk.ai/post/semantic-search' \
  -H 'Authorization: Bearer sk-throk-...' \
  --data-urlencode 'query=減脂期到底可以吃什麼' \
  --data-urlencode "from_timestamp=$(date -v-7d +%s)" \
  --data-urlencode 'min_like_count=100'
```

## Pricing

30 credits for the first 10 results, then 2 credits per result (for example, 30 results cost 70 credits). Beyond 10, you're charged by the number of results actually returned, but every call costs at least 30 credits, even if filtering leaves fewer than 10 results or none at all.

## Use it in MCP

The MCP tool is `semantic_search_posts`. It takes the same parameters, but `size` is capped at 10.

How it differs from `get_inspiration`: `get_inspiration` only searches curated high-engagement posts, while `semantic_search_posts` searches all recent posts, so it also finds posts from small, everyday accounts.

## Limitations

- **Only the last 30 days.** For older posts, use `/post/search`.
- **Top-level posts only, no replies**, and very short posts are left out.
- **No guarantee that results contain a specific word.** When you need exact matching, use `/post/search`.
- **Queries tied to a place** (for example 台北美食, Taipei food) tend to pull in results from other cities. This is a known weakness of the current semantic model.