Keywords & Surveillance API
List and register brand search keywords for automated background surveillance.
Manage the search queries and topic queries that Mostly sweeps on a daily or weekly schedule across TikTok, Meta, and Reddit.
1. List Monitored Keywords
GET /api/v1/keywordsRequest Headers
| Header | Type | Description |
|---|---|---|
Authorization | string | Bearer mst_live_... (Required) |
Example Request
curl -X GET https://mostly.so/api/v1/keywords \
-H "Authorization: Bearer mst_live_abc123..."Example Response (200 OK)
{
"brandId": "brand_4f123a-5678-90ab",
"brandName": "Aura Wellness",
"totalKeywords": 2,
"keywords": [
{
"id": "kw_9a8b7c6d-5432-10fe",
"query": "hair growth oil routine",
"platform": "TIKTOK",
"category": "PRODUCT",
"frequency": "DAILY",
"isEnabled": true,
"lastRunAt": "2026-09-28T04:00:00.000Z",
"creativeCount": 42
},
{
"id": "kw_3c2b1a0f-1234-5678",
"query": "scalp detox mistakes",
"platform": "ALL",
"category": "PAIN_POINT",
"frequency": "WEEKLY",
"isEnabled": true,
"lastRunAt": "2026-09-27T12:00:00.000Z",
"creativeCount": 18
}
]
}2. Register New Surveillance Keyword
POST /api/v1/keywordsRegistering a keyword automatically triggers background crawler tasks to ingest matching viral posts and monitor for emerging competitor ads.
Request Body (JSON)
| Field | Type | Default | Description |
|---|---|---|---|
query | string | (Required) | The keyword phrase or topic to monitor (Min 2 characters). |
platform | string | "TIKTOK" | TIKTOK, META, REDDIT, or ALL. |
category | string | "CUSTOM" | Strategic bucket: PAIN_POINT, PRODUCT, DESIRED_OUTCOME, BUYING_INTENT, COMPETITOR, CUSTOM. |
frequency | string | "DAILY" | Sweeper cadence: DAILY or WEEKLY. |
country | string | "US" | 2-letter country code. |
Example Request
curl -X POST https://mostly.so/api/v1/keywords \
-H "Authorization: Bearer mst_live_abc123..." \
-H "Content-Type: application/json" \
-d '{
"query": "peptide serum review",
"platform": "TIKTOK",
"category": "PRODUCT",
"frequency": "DAILY",
"country": "US"
}'Example Response (201 Created)
{
"success": true,
"keywordId": "kw_5e6f7a8b-9012-34cd",
"query": "peptide serum review",
"platform": "TIKTOK",
"category": "PRODUCT",
"frequency": "DAILY",
"message": "Registered keyword 'peptide serum review' and triggered initial backfill sweeper."
}