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

# Trending Videos

> Get currently trending viral videos across platforms

## Overview

This endpoint returns trending viral videos from TikTok and YouTube. Videos are ranked by viral score and filtered to show only the latest trending content.

### Query Parameters

<ParamField query="platform" type="string">
  Filter by platform:

  * `tiktok`: TikTok videos only
  * `youtube`: YouTube videos only
  * Omit to get videos from all platforms
</ParamField>

<ParamField query="niche" type="string">
  Filter by niche ID (e.g., "fitness", "cooking", "gaming"). Use the [List Niches](/api-reference/niche/list) endpoint to get available niches.
</ParamField>

<ParamField query="limit" type="number" default="20">
  Number of videos to return (1-50)
</ParamField>

<ParamField query="offset" type="number" default="0">
  Pagination offset
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="data">
    <ResponseField name="videos" type="array">
      Array of trending video objects

      <Expandable title="video">
        <ResponseField name="id" type="string">
          Internal video ID
        </ResponseField>

        <ResponseField name="externalId" type="string">
          Platform-specific video ID
        </ResponseField>

        <ResponseField name="platform" type="string">
          Platform (tiktok or youtube)
        </ResponseField>

        <ResponseField name="title" type="string">
          Video title or caption
        </ResponseField>

        <ResponseField name="thumbnailUrl" type="string">
          URL to video thumbnail
        </ResponseField>

        <ResponseField name="videoUrl" type="string">
          Direct URL to watch the video
        </ResponseField>

        <ResponseField name="creator" type="object">
          Creator information
        </ResponseField>

        <ResponseField name="stats" type="object">
          Video statistics (views, likes, comments, shares)
        </ResponseField>

        <ResponseField name="viralScore" type="number">
          Viral score (0-100)
        </ResponseField>

        <ResponseField name="engagementRate" type="number">
          Engagement rate percentage
        </ResponseField>

        <ResponseField name="hashtags" type="array">
          Array of hashtags used
        </ResponseField>

        <ResponseField name="niche" type="string">
          Content niche category
        </ResponseField>

        <ResponseField name="publishedAt" type="string">
          Publication date (ISO 8601)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="total" type="number">
      Total number of trending videos
    </ResponseField>

    <ResponseField name="limit" type="number">
      Current limit applied
    </ResponseField>

    <ResponseField name="offset" type="number">
      Current offset applied
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.hooked.so/v1/trends/videos?platform=tiktok&limit=10" \
    -H "x-api-key: your_api_key_here"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.hooked.so/v1/trends/videos?platform=tiktok&limit=10', {
    headers: {
      'x-api-key': 'your_api_key_here'
    }
  });

  const data = await response.json();
  console.log(data.data.videos);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.hooked.so/v1/trends/videos',
      params={'platform': 'tiktok', 'limit': 10},
      headers={'x-api-key': 'your_api_key_here'}
  )

  videos = response.json()['data']['videos']
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "videos": [
        {
          "id": "clx123abc",
          "externalId": "7234567890123456789",
          "platform": "tiktok",
          "title": "This fitness hack changed my life #fitness #workout",
          "thumbnailUrl": "https://cdn.tiktok.com/thumb.jpg",
          "videoUrl": "https://www.tiktok.com/@creator/video/7234567890123456789",
          "creator": {
            "username": "fitnessguru",
            "displayName": "Fitness Guru",
            "avatarUrl": "https://cdn.tiktok.com/avatar.jpg",
            "followers": 1500000,
            "isVerified": true
          },
          "stats": {
            "views": 5400000,
            "likes": 890000,
            "comments": 12500,
            "shares": 45000
          },
          "viralScore": 92.5,
          "engagementRate": 17.5,
          "hashtags": ["fitness", "workout", "gym"],
          "niche": "fitness",
          "publishedAt": "2024-01-15T10:30:00Z"
        }
      ],
      "total": 150,
      "limit": 10,
      "offset": 0
    }
  }
  ```
</ResponseExample>

## Notes

<Note>
  Trending videos are updated regularly. The `isLatestViral` flag ensures you only see the most current trending content.
</Note>

<Tip>
  Combine platform and niche filters to find relevant trending content for your specific audience.
</Tip>


## OpenAPI

````yaml GET /v1/trends/videos
openapi: 3.0.0
info:
  title: Hooked API
  version: 1.0.0
  description: AI Video Generation API
servers:
  - url: https://api.hooked.so
security:
  - ApiKeyAuth: []
paths:
  /v1/trends/videos:
    get:
      tags:
        - Trends
      summary: Trending Videos
      description: Get currently trending viral videos across platforms
      operationId: getTrendingVideos
      parameters:
        - name: platform
          in: query
          schema:
            type: string
            enum:
              - tiktok
              - youtube
        - name: niche
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Success
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````