> ## Documentation Index
> Fetch the complete documentation index at: /dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# videos_find

> Find short videos on a topic, best outliers first.

> [!NOTE]
>
> Uses credits · Your own key only

Searches TikTok, Instagram or YouTube for short videos and ranks the ones that did far better than usual first. Takes 5-15 s and uses a few Constella credits.

Call it at `POST /platform/v1/me/tools/videos_find`. On MCP, your AI tool calls `videos_find` with the same arguments.

## Arguments

Send these inside `arguments`.

**query** `string` *required*

Plain words, `"#tag"` for a hashtag, or `"@handle"` for one creator.

**platform** `string` (default: "tiktok")

`tiktok`, `instagram` or `youtube`.

**cursor** `string` (default: null)

The `next_cursor` from the last call, for more.

**limit** `integer` (default: 20)

1-50.

## Returns

The tool's answer comes back under `result`.

**videos** `Video[]`

A Video has `platform`, `id`, `url`, `author`, `followers`, `caption`, `views`, `likes`, `comments`, `shares`, `saves`, `posted_at`, `duration_s`, `thumbnail`, `video` and `outlier` (how many times better than usual).

**next\_cursor** `string`

Pass it back for more.

```bash Your key theme={"system"}
curl https://api.constella.app/platform/v1/me/tools/videos_find \
  -H "Authorization: Bearer $CONSTELLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"arguments": {"query": "morning routine", "platform": "tiktok", "limit": 5}}'
```

```python Python theme={"system"}
import os, requests

r = requests.post(
    "https://api.constella.app/platform/v1/me/tools/videos_find",
    headers={"Authorization": f"Bearer {os.environ['CONSTELLA_API_KEY']}", "X-Constella-Client": "my-script"},
    json={"arguments": {"query": "morning routine", "platform": "tiktok", "limit": 5}},
)
print(r.json()["result"])
```

```javascript JavaScript theme={"system"}
const res = await fetch("https://api.constella.app/platform/v1/me/tools/videos_find", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CONSTELLA_API_KEY}`,
    "X-Constella-Client": "my-script",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"arguments": {"query": "morning routine", "platform": "tiktok", "limit": 5}}),
});
const { result } = await res.json();
```

```json 200 theme={"system"}
{
  "result": {
    "videos": [
      {
        "platform": "tiktok",
        "url": "https://www.tiktok.com/@.../video/...",
        "views": 2100000,
        "followers": 41000,
        "outlier": 51.2
      }
    ],
    "next_cursor": "20"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.