# Threads API tutorial: Throk API quickstart

## 1. Get an API key

Sign in to the [Throk developer portal](https://developer.throk.ai/dashboard), open the **API keys** page and click **Create key**. Keys start with `sk-throk-`. Every example in these docs writes the key as `sk-throk-...`; replace it with your own key.

![The API keys page in the developer portal: create a key, account credit balance and the key list](../../../../assets/screenshots/en/api/portal-api-keys.jpg)

You need an active [API plan](/en/api/credits/#api-plans) to call the API. All keys share the account's credits.

:::caution
An API key is as good as your account's credits. Never put it in frontend code, a public repo or a screenshot.
:::

## 2. Send your first request

Send every request to `https://premium-api.throk.ai` with the header `Authorization: Bearer <your key>`.

The request below searches Chinese posts from the last 24 hours that mention 減脂 ("fat loss"), sorts them by likes from high to low and returns the top 10:

```bash
curl -G 'https://premium-api.throk.ai/post/search' \
  -H 'Authorization: Bearer sk-throk-...' \
  --data-urlencode 'keywords=減脂' \
  --data-urlencode 'max_age_hours=24' \
  --data-urlencode 'sort=like:desc' \
  --data-urlencode 'size=10'
```

Without `language`, the search covers all Chinese posts (`zh`). To search another language, add `language`, for example `language=zh-Hant` (Traditional Chinese), `language=yue` (Cantonese), `language=en` (English) or `language=ja` (Japanese). See [Post language](/en/api/guides/regions/).

Response (excerpt):

```json
{
  "content": [
    {
      "post": {
        "url": "https://threads.com/post/DaXXXXXX",
        "code": "DaXXXXXX",
        "caption": "減脂期間我都這樣吃……",
        "like_count": 1520,
        "reply_count": 48,
        "post_timestamp": 1790000000
      },
      "user": null
    }
  ],
  "metadata": {
    "total_count": 356,
    "current_page": 1,
    "page_size": 10,
    "total_pages": 36,
    "credits_consumed": 10
  }
}
```

`total_count` shows at most 10,000. When more than 10,000 posts match, `total_count` stops at 10,000 and `total_pages` is capped with it. To measure mention volume, use the [keyword trend](/en/api/keyword-monitoring/#2-see-the-volume-trend).

:::tip[Searches cover the last 7 days by default]
When you don't set a time, `/post/search` searches posts from the **last 7 days**. For another range, add `max_age_hours` (up to 2160, which is 90 days) or `from_timestamp`. Any time filter can reach back at most 90 days. See [Search rules](/en/api/guides/search-rules/#search-time-range).
:::

## 3. Check your remaining credits

The **Overview** and **Usage** pages in the developer portal show your balance and every charge. You can also check it with the API, which costs no credits:

```bash
curl 'https://premium-api.throk.ai/balance' \
  -H 'Authorization: Bearer sk-throk-...'
```

```json
{ "credits": 48210 }
```

The `credits_consumed` field in each response shows how many credits that call used. To list your usage history, call `GET /balance/history`.

## Common errors

| HTTP status | Message | Cause |
| --- | --- | --- |
| 401 | `Invalid API key` | The key is mistyped or deleted, or the header is missing the `Bearer` prefix |
| 402 | `Insufficient credits` | Not enough credits. Throk estimates the cost before running a query and won't run it if your credits fall short |
| 400 | Other messages | A parameter is missing, malformed or out of range. The message names the parameter, for example when a time goes back further than allowed |

Error responses always use the format `{"detail": "error message"}`.

## Next steps

- Read the [search rules](/en/api/guides/search-rules/) first. Knowing how keywords match saves a lot of trial and error.
- To query data directly in Claude, ChatGPT, Codex or Cursor, see [Use in AI assistants (MCP)](/en/api/mcp/).
- To compare API plans and prices, see [Throk API plans](https://www.throk.ai/en/developers/pricing).