Skip to main content
GET
/
api
/
partner
/
v1
/
trends
/
brief
curl --request GET \
  --url 'https://www.genviral.io/api/partner/v1/trends/brief?platform=tiktok&keyword=morning%20routine&limit=10&range=7d' \
  --header 'Authorization: Bearer <token>'

{
  "ok": true,
  "code": 200,
  "message": "Trend brief retrieved",
  "data": {
    "platform": "tiktok",
    "keyword": "morning routine",
    "range": "7d",
    "generated_at": "2026-02-19T06:30:00.000Z",
    "summary": {
      "analyzed_video_count": 42,
      "top_hashtags": [
        { "hashtag": "morningroutine", "videos_count": 29, "avg_views": 157217 }
      ],
      "top_sounds": [
        {
          "sound_id": "sound:summer",
          "sound_name": "Summer",
          "usage_count": 1,
          "avg_views": 2244030,
          "sample_url": null
        }
      ],
      "top_creators": [
        {
          "handle": "chaseridgewayy",
          "videos_count": 1,
          "total_views": 2244030,
          "avg_views": 2244030,
          "top_video_url": "https://www.tiktok.com/@chaseridgewayy/video/7606308970243968270"
        }
      ],
      "posting_windows_utc": [
        { "day_of_week_utc": 5, "hour_utc": 11, "videos_count": 1, "avg_views": 2244030 }
      ]
    },
    "recommendations": {
      "hook_angles": ["Ummmm should I..."],
      "hashtags": ["#morningroutine"],
      "sounds": [{ "sound_id": "sound:summer", "sound_name": "Summer" }]
    },
    "evidence": {
      "sample_videos": [
        {
          "video_id": "7606308970243968270",
          "url": "https://www.tiktok.com/@chaseridgewayy/video/7606308970243968270",
          "views": 2244030,
          "likes": 298790,
          "comments": 613,
          "shares": 17460,
          "caption": "Ummmm should I....move here????",
          "hashtags": [],
          "sound_id": "sound:summer",
          "sound_name": "Summer",
          "author_handle": "chaseridgewayy",
          "published_at": "2026-02-13T11:23:51.000Z"
        }
      ]
    }
  }
}
Generate an AI-agent ready TikTok trend brief from one keyword. This endpoint consolidates trend videos, search results, and sounds into one response so OpenClaw or custom agents can plan content without making multiple trend calls. Brief aggregation is keyword-relevance aware: when matching videos are found, the summary/recommendation output prioritizes those matches over unrelated high-view videos.
Public trends access is brief-only. Use this endpoint instead of any legacy atomic trends routes.

​
Query Parameters

​
platform
string
default:"tiktok"
Platform target. Current supported value is tiktok.
​
keyword
string
required
Required trend query seed (for example morning routine, fitness, grwm).
​
limit
number
default:"10"
Number of videos returned in data.evidence.sample_videos. Range: 1..30.
​
range
string
default:"7d"
Trend window: 24h, 7d, or 30d.

​
Response

​
platform
string
Echoed platform (tiktok).
​
keyword
string
Normalized keyword used to build the brief.
​
range
string
Applied range window (24h, 7d, 30d).
​
generated_at
string
ISO timestamp indicating when the brief payload was generated.
​
summary
object
Aggregated trend snapshot.
​
recommendations
object
Ready-to-use planning suggestions.
​
evidence
object
Supporting sample videos from the analyzed pool.

​
Caching

  • Cached for 3 hours by platform + keyword + range.
  • limit affects only sample_videos length in the final response.
curl --request GET \
  --url 'https://www.genviral.io/api/partner/v1/trends/brief?platform=tiktok&keyword=morning%20routine&limit=10&range=7d' \
  --header 'Authorization: Bearer <token>'

{
  "ok": true,
  "code": 200,
  "message": "Trend brief retrieved",
  "data": {
    "platform": "tiktok",
    "keyword": "morning routine",
    "range": "7d",
    "generated_at": "2026-02-19T06:30:00.000Z",
    "summary": {
      "analyzed_video_count": 42,
      "top_hashtags": [
        { "hashtag": "morningroutine", "videos_count": 29, "avg_views": 157217 }
      ],
      "top_sounds": [
        {
          "sound_id": "sound:summer",
          "sound_name": "Summer",
          "usage_count": 1,
          "avg_views": 2244030,
          "sample_url": null
        }
      ],
      "top_creators": [
        {
          "handle": "chaseridgewayy",
          "videos_count": 1,
          "total_views": 2244030,
          "avg_views": 2244030,
          "top_video_url": "https://www.tiktok.com/@chaseridgewayy/video/7606308970243968270"
        }
      ],
      "posting_windows_utc": [
        { "day_of_week_utc": 5, "hour_utc": 11, "videos_count": 1, "avg_views": 2244030 }
      ]
    },
    "recommendations": {
      "hook_angles": ["Ummmm should I..."],
      "hashtags": ["#morningroutine"],
      "sounds": [{ "sound_id": "sound:summer", "sound_name": "Summer" }]
    },
    "evidence": {
      "sample_videos": [
        {
          "video_id": "7606308970243968270",
          "url": "https://www.tiktok.com/@chaseridgewayy/video/7606308970243968270",
          "views": 2244030,
          "likes": 298790,
          "comments": 613,
          "shares": 17460,
          "caption": "Ummmm should I....move here????",
          "hashtags": [],
          "sound_id": "sound:summer",
          "sound_name": "Summer",
          "author_handle": "chaseridgewayy",
          "published_at": "2026-02-13T11:23:51.000Z"
        }
      ]
    }
  }
}

​
Error Responses

  • 401 - authentication failed (missing/invalid/revoked token)
  • 402 subscription_required - active Creator/Professional/Business plan required
  • 403 tier_not_allowed - Scheduler tier cannot use Partner API
  • 422 - invalid query parameters (for example unsupported platform, missing keyword, or invalid limit)
  • 500 trends_brief_failed - unexpected trend brief generation failure