---
title: "Search TikTok for videos on a word or a hashtag"
method: GET
path: "/search/tiktok"
tags: ["Search"]
---

# Search TikTok for videos on a word or a hashtag

`GET /search/tiktok`

## Request

- Base URL: `https://api.socially.run/v1`
- URL: `https://api.socially.run/v1/search/tiktok`
- Auth: HTTP bearer

What TikTok lists for a word or a hashtag: caption, author, exact views, likes, comments and shares, the date, the length and the tags, read through a paid reader. A word searches TikTok's search bar and takes a window (`recency`), an order (`sort`) and a country. A `#tag` reads that tag's own page, which lists its popular videos of any age in TikTok's order, from any country, and takes none of those. A word's page lists up to 30 videos and a tag's about 20: pass `nextCursor` back as `cursor` for the next one, which is another read. The author's follower count is on keyword results and absent from a hashtag feed. A deployment with no TikTok reader configured answers 503 before it charges. Cached for thirty minutes.

## Query parameters

- `q` string, required: A word or a phrase for TikTok's search bar ("padaria artesanal"), or a hashtag with its # ("#padaria").
- `limit` integer: Videos to return, 1–30. One page is one read: a smaller `limit` on the same question is served from it, and a `limit` that cuts the page ends the cursor.
- `recency` 'day' | 'week' | 'month' | 'quarter' | 'half_year': Words only. Only videos posted within the window: `day`, `week`, `month`, `quarter` (90 days) or `half_year` (180 days), TikTok's own filters. Absent means all time. A hashtag takes none.
- `sort` 'relevance' | 'likes' | 'recent': Words only. `relevance` (the default) is TikTok's ranking, `likes` puts the most-liked first and `recent` the newest. Combine `likes` with `recency` to find what is working lately. A hashtag takes none.
- `country` string: Words only. Search as a person in this country would, ISO 3166-1 alpha-2 (BR, US, ES). Absent means no country. A code with no region behind it is not refused and filters nothing, so check `videos[].region` against the country you meant. A hashtag takes none.
- `cursor` string: The `nextCursor` of the page before. Each page is another read and another charge, and a cursor only works against the source that made it.
- `refresh` boolean: Read the page again instead of serving the half-hour cache. Charged like any read, and the fresh answer replaces the cached one.

## Response `200`

Search TikTok for videos on a word or a hashtag

- object
  - `data` unknown, required

## Other responses

- `400`: VALIDATION_ERROR / INVALID_TARGET / SSRF_BLOCKED: the issues, never the values.
- `401`: UNAUTHORIZED / INVALID_TOKEN: the key is missing or wrong.
- `402`: PAYMENT_REQUIRED / PLAN_GATE: clears by upgrading or buying credits, never by waiting.
- `429`: RATE_LIMIT_EXCEEDED / QUOTA_EXCEEDED: Retry-After says when it clears.
- `default`: Any other failure.

---

[API](https://skmtc.dev/socially/apis/socially-run-send-a-profile-link-get-its-public-data-as-json.md) · [All operations](https://skmtc.dev/socially/apis/socially-run-send-a-profile-link-get-its-public-data-as-json/llms.txt) · [OpenAPI document](https://skmtc.dev/socially/apis/socially-run-send-a-profile-link-get-its-public-data-as-json/revisions/5a0b24534b90?raw)