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

# Get Trend Brief

> Generate a one-call TikTok trend brief for a keyword with top hashtags, sounds, creators, posting windows, hook angles, and sample videos.

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.

<Note>
  Public trends access is brief-only. Use this endpoint instead of any legacy
  atomic trends routes.
</Note>

## Query Parameters

<ParamField query="platform" type="string" default="tiktok">
  Platform target. Current supported value is `tiktok`.
</ParamField>

<ParamField query="keyword" type="string" required>
  Required trend query seed (for example `morning routine`, `fitness`, `grwm`).
</ParamField>

<ParamField query="limit" type="number" default="10">
  Number of videos returned in `data.evidence.sample_videos`. Range: `1..30`.
</ParamField>

<ParamField query="range" type="string" default="7d">
  Trend window: `24h`, `7d`, or `30d`.
</ParamField>

## Response

<ResponseField name="platform" type="string">
  Echoed platform (`tiktok`).
</ResponseField>

<ResponseField name="keyword" type="string">
  Normalized keyword used to build the brief.
</ResponseField>

<ResponseField name="range" type="string">
  Applied range window (`24h`, `7d`, `30d`).
</ResponseField>

<ResponseField name="generated_at" type="string">
  ISO timestamp indicating when the brief payload was generated.
</ResponseField>

<ResponseField name="summary" type="object">
  Aggregated trend snapshot.

  <Expandable title="Summary Object">
    <ResponseField name="analyzed_video_count" type="number" />

    <ResponseField name="top_hashtags" type="array" />

    <ResponseField name="top_sounds" type="array" />

    <ResponseField name="top_creators" type="array" />

    <ResponseField name="posting_windows_utc" type="array" />
  </Expandable>
</ResponseField>

<ResponseField name="recommendations" type="object">
  Ready-to-use planning suggestions.

  <Expandable title="Recommendations Object">
    <ResponseField name="hook_angles" type="array" />

    <ResponseField name="hashtags" type="array" />

    <ResponseField name="sounds" type="array" />
  </Expandable>
</ResponseField>

<ResponseField name="evidence" type="object">
  Supporting sample videos from the analyzed pool.

  <Expandable title="Evidence Object">
    <ResponseField name="sample_videos" type="array" />
  </Expandable>
</ResponseField>

## Caching

* Cached for 3 hours by `platform + keyword + range`.
* `limit` affects only `sample_videos` length in the final response.

<RequestExample>
  ```bash cURL theme={null}
  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>'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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"
          }
        ]
      }
    }
  }
  ```
</ResponseExample>

## 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