---
title: "Search the hook corpus"
method: GET
path: "/v1/hooks/search"
tags: ["Hooks"]
---

# Search the hook corpus

`GET /v1/hooks/search`

## Request

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

Phrase and attribute search over every extracted hook, all time. With q, results come in tiers marked by match_type: exact (the hook IS your text; paste a hook you saw to find its source), then contains (hooks using your phrase, strongest Virality Score first, so "nobody talks about" returns the best-performing hooks built on it), then similar (near-matches, only when the first two tiers cannot fill the page). Phrase matching is whole-word, case-insensitive and ignores punctuation, emoji and line breaks between words. Without q, browse by hook_type / visual_hook_type ranked by Virality Score. At least one of q, hook_type, or visual_hook_type is required. No publish-date window (use /v1/hooks/trending for "right now"). Top 1,000 results. $0.25 per call.

## Query parameters

- `limit` number
- `page` number
- `q` string
- `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

## Response `200`

- SearchHooksResponseDto
  - `data` SearchHookItemDto[], 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.
    - `match_type` 'exact' | 'contains' | 'similar', nullable: How the hook matched q. exact: the hook IS the query (reverse lookup hit). contains: the hook contains the phrase; this tier is ranked by Virality Score. similar: a near-match (typos, reworded), returned only when the first two tiers cannot fill the page. Results are ordered exact, contains, similar. Null when no q was given.
    - `match_score` number, nullable: Trigram similarity between the query and hook_text (0-1); 1 for exact matches. Informational: ordering is by match_type first. Null when no q was given.
  - `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)