---
title: "Top-performing hooks corpus-wide"
method: GET
path: "/v1/hooks/trending"
tags: ["Hooks"]
---

# Top-performing hooks corpus-wide

`GET /v1/hooks/trending`

## Request

- Base URL: `https://api.virlo.ai`
- URL: `https://api.virlo.ai/v1/hooks/trending`
- Auth: HTTP bearer

The strongest verbatim hooks across the whole Virlo corpus (~970k video hooks + ~440k slideshow hooks, growing daily), ranked by Virality Score (default) or raw views over a 7/14/30-day publish window. Each item carries the exact opening line, both hook classifications, the source post with metrics, and usage_count (how many posts open with the same hook; identical hooks are collapsed to their strongest source). Filter by platform, category, hook_type, visual_hook_type, language, or min_views. Use this for "what hooks are working right now"; use /v1/hooks/search to find hooks with a given phrasing and /v1/agents/{id}/hooks for a niche you already track. Never rank by raw views across platforms: the default Virality Score is the cross-platform signal. Top 1,000 results. $0.25 per call.

## Query parameters

- `limit` number
- `page` number
- `content_type` 'video' | 'slideshow' | 'all'
- `platform` 'tiktok' | 'youtube' | 'instagram'
- `category` 'art_design' | 'automotive' | 'beauty' | 'business_career' | 'crafts_diy' | 'education' | 'entertainment' | 'fashion' | 'finance' | 'fitness' | 'food_beverage' | 'gaming' | 'health_wellness' | 'home_garden' | 'kids_content' | 'lifestyle' | 'music' | 'news_politics' | 'parenting_family' | 'pets' | 'real_estate' | 'relationships_dating' | 'religion_spirituality' | 'science_nature' | 'sports' | 'tech' | 'travel' | 'other'
- `hook_type` string
- `visual_hook_type` 'text_hook' | 'extreme_closeup' | 'before_state' | 'shocking_image' | 'aesthetic_setup' | 'person_speaking_to_camera' | 'motion_action' | 'crowded_scene' | 'mystery_object' | 'dramatic_zoom' | 'animal_pet' | 'product_reveal'
- `language` string
- `min_views` number
- `days` 7 | 14 | 30
- `sort` 'weighted_score' | 'views'

## Response `200`

- TrendingHooksResponseDto
  - `data` HookItemDto[], required
    - `hook_text` string, required: Verbatim opening line — a contiguous substring of the first ~6 seconds of speech, or the frame-1 on-screen text when there is no spoken hook. Never paraphrased.
    - `hook_type` string, nullable: Spoken/text hook classification. GET /v1/hooks/types lists the values; the list grows over time.
    - `visual_hook_type` string, nullable: First-frame visual classification (12-value vocabulary). Orthogonal to hook_type. Null for slideshows.
    - `content_type` 'video' | 'slideshow', required
    - `platform` 'tiktok' | 'youtube' | 'instagram', required
    - `category` string, nullable: AI-classified content category of the source video.
    - `language` string, nullable: Detected ISO language code of the content.
    - `brand_safety_tier` string, nullable: Brand-safety tier of the source content (safe | low_risk | medium_risk — higher-risk content is excluded from the corpus).
    - `outlier_ratio` number, nullable: views / author followers. The raw outlier signal.
    - `weighted_score` number, nullable: Virality Score = ln(views/followers) × ln(followers). Size-weighted and cross-platform comparable: >=35 exceptional, 25-35 very strong, 18-25 strong, 10-18 promising.
    - `usage_count` number, required: How many corpus posts open with this exact hook (case- and whitespace-insensitive). Identical hooks are collapsed to their strongest source, so this is the only place the others show up. 1 = original; higher = a reused template or format.
    - `video` HookVideoDto, required
      - `video_id` string, required: Virlo id of the source video/slideshow. Interchangeable with the video ids returned by the agent content endpoints.
      - `url` string, nullable: Platform URL of the source post.
      - `thumbnail_url` string, nullable
      - `views` number, nullable
      - `likes` number, nullable
      - `comments` number, nullable
      - `shares` number, nullable
      - `duration` number, nullable: Video duration in seconds. Null for slideshows.
      - `publish_date` string, nullable
      - `author_handle` string, nullable: Creator handle on the platform.
      - `author_followers` number, nullable: Creator follower count at last sync.
  - `pagination` PaginationMetaDto, required
    - `page` number, required
    - `limit` number, required
    - `total` number, required
    - `total_pages` number, required
    - `has_next_page` boolean, required
    - `has_prev_page` boolean, required

## Other responses

- `401`: Missing or invalid API key (`missing_api_key` / `invalid_api_key`)
- `429`: Rate limit exceeded (`rate_limit_exceeded`); see the Retry-After header

---

[API](https://skmtc.dev/virlo/apis/virlo-public-api.md) · [All operations](https://skmtc.dev/virlo/apis/virlo-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/virlo/apis/virlo-public-api/revisions/3b69c6145087?raw)