Hook Intelligence

The hook — the opening line and first frame of a short-form video — is the highest-leverage creative decision in the format. Virlo's analysis pipeline extracts every hook verbatim (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) and classifies it on two orthogonal dimensions. The Hooks API exposes that corpus — 600k+ video hooks and 350k+ slideshow hooks, growing by thousands daily — plus a curated 4,000-template writing library.

All endpoints use the base URL https://api.virlo.ai/v1/hooks (plus GET /v1/agents/:id/hooks). All parameters and response fields use snake_case. Single objects are wrapped in { "data": ... }; lists add a pagination object.

The two hook dimensions

Every analyzed video carries one value from each vocabulary — they are orthogonal, never merged:

hook_type (17 values) — what the opening line does: question, bold_claim, shock_statement, story_tease, tutorial_promise, controversy, before_after, pov_setup, statistic, direct_address, trend_reference, cliffhanger, negation, relatable_scenario, comparison, mystery_setup, none
visual_hook_type (12 values) — what fills frame 1: text_hook, extreme_closeup, before_state, shocking_image, aesthetic_setup, person_speaking_to_camera, motion_action, crowded_scene, mystery_object, dramatic_zoom, animal_pet, none

Rows classified none ("no discernible hook") are excluded from result sets but appear in the taxonomy stats for corpus accounting.

Ranking

Results default to Virality Score (weighted_score) = ln(views ÷ followers) × ln(followers) — size-weighted and comparable across creator sizes and platforms: ≥35 exceptional, 25–35 very strong, 18–25 strong, 10–18 promising. sort=views ranks by raw views; never compare raw views across platforms.

GET/v1/hooks/types

Hook Taxonomy & Stats

The discovery surface for every other hooks endpoint: both vocabularies with per-value effectiveness stats from the latest daily corpus snapshot — counts, corpus share, average/median views, and average + 90th-percentile Virality Score. Answers "which hook types are most effective in my category / on my platform?"

Cost per request:Free

Query parameters

Name
dimension
Type
string
Description
hook_type (default) or visual_hook_type.
Name
platform
Type
string
Description
tiktok, youtube, or instagram. Omit for all platforms combined.
Name
category
Type
string
Description
Content category slice (e.g. beauty, tech, education). Omit for all categories combined.

Request

GET

/v1/hooks/types

curl "https://api.virlo.ai/v1/hooks/types?platform=tiktok" \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "dimension": "hook_type",
    "platform": "tiktok",
    "category": "all",
    "snapshot_date": "2026-08-20",
    "types": [
      {
        "value": "tutorial_promise",
        "video_count": 143969,
        "share_of_corpus": 0.2351,
        "total_views": 47473584304,
        "avg_views": 329751,
        "median_views": 11492,
        "avg_weighted_score": 14.21,
        "p90_weighted_score": 28.4
      }
    ]
  }
}

GET/v1/hooks/trending

The strongest verbatim hooks across the whole corpus over a recent publish window — replicable templates with receipts. Each item carries the exact opening line, both classifications, and the source post with metrics and creator handle. Exact-duplicate hook texts are collapsed to their strongest source video.

Cost per request:$0.25

Query parameters

Name
content_type
Type
string
Description
video (default), slideshow (TikTok carousels), or all.
Name
platform
Type
string
Description
tiktok, youtube, or instagram.
Name
category
Type
string
Description
Content category filter.
Name
hook_type
Type
string
Description
One of the 16 non-none hook types.
Name
visual_hook_type
Type
string
Description
One of the 11 non-none visual hook types.
Name
language
Type
string
Description
ISO language code of the hook text (e.g. en, es, pt).
Name
min_views
Type
integer
Description
Only hooks from videos with at least this many views.
Name
days
Type
integer
Description
Publish window: 7 (default), 14, or 30.
Name
sort
Type
string
Description
weighted_score (default) or views.
Name
page
Type
integer
Description
Page number (default 1).
Name
limit
Type
integer
Description
Items per page (default 20, max 100 — higher values are clamped).

pagination.total uses the running-lower-bound idiom: a full page always reports has_next_page: true, and total grows as you paginate.

Request

GET

/v1/hooks/trending

curl "https://api.virlo.ai/v1/hooks/trending?platform=tiktok&hook_type=tutorial_promise&days=7&limit=10" \
  -H "Authorization: Bearer {token}"

Response (item)

{
  "data": [
    {
      "hook_text": "POV: You said\nyou'd start saving “tomorrow”\nDay 1",
      "hook_type": "pov_setup",
      "visual_hook_type": "text_hook",
      "content_type": "video",
      "platform": "tiktok",
      "category": "finance",
      "language": "en",
      "brand_safety_tier": "safe",
      "outlier_ratio": 1226.9,
      "weighted_score": 63.19,
      "video": {
        "video_id": "8fcef651-a0f7-41f1-a5ec-1dc8dd12785f",
        "url": "https://www.tiktok.com/@.../video/...",
        "thumbnail_url": "https://...",
        "views": 8861925,
        "likes": 812000,
        "comments": 4100,
        "shares": 12000,
        "duration": 21,
        "publish_date": "2026-08-14T16:50:20+00:00",
        "author_handle": "kingba2026",
        "author_followers": 7223
      }
    }
  ],
  "pagination": { "page": 1, "limit": 10, "total": 11, "total_pages": 2, "has_next_page": true, "has_prev_page": false }
}

GET/v1/hooks/search

Search Hooks

Text and attribute search over the full corpus, with no publish window. With q, results are trigram-similarity + substring matched (multilingual-safe) and ranked by match quality then Virality Score — this is also the reverse lookup: paste a hook you saw somewhere to find its source video(s). Without q, browse by classification — e.g. every video using a tutorial_promise hook.

At least one of q, hook_type, or visual_hook_type is required (400 otherwise).

Cost per request:$0.25

Query parameters

Name
q
Type
string
Description
Free-text query (3–200 chars). Items gain a match_score (0–1 trigram similarity).
Name
content_type
Type
string
Description
video (default), slideshow, or all.
Name
hook_type
Type
string
Description
Hook type filter.
Name
visual_hook_type
Type
string
Description
Visual hook type filter.
Name
platform
Type
string
Description
Platform filter.
Name
category
Type
string
Description
Category filter.
Name
language
Type
string
Description
ISO language code.
Name
min_views
Type
integer
Description
Minimum source-video views.
Name
page
Type
integer
Description
Page number (default 1).
Name
limit
Type
integer
Description
Items per page (default 20, max 100).

Request

GET

/v1/hooks/search

curl "https://api.virlo.ai/v1/hooks/search?q=morning%20routine&platform=tiktok&limit=10" \
  -H "Authorization: Bearer {token}"

Response (item, abridged)

{
  "data": [
    {
      "hook_text": "morning routine",
      "hook_type": null,
      "visual_hook_type": "text_hook",
      "match_score": 1.0,
      "weighted_score": 36.92,
      "video": { "views": 1571000, "author_handle": "..." }
    }
  ],
  "pagination": { "page": 1, "limit": 10, "total": 11, "total_pages": 2, "has_next_page": true, "has_prev_page": false }
}

GET/v1/hooks/library

Hook Template Library

4,000+ hand-curated, fill-in-the-blank hook templates across 30+ categories — each with a filled-in example, the psychology of why it works, and psychology tags (curiosity, fomo, social_proof, …). The corpus endpoints show what is working in the wild; the library is writing material for drafting your own.

Cost per request:$0.10

Query parameters

Name
category
Type
string
Description
Library category slug (from the categories endpoint below).
Name
psychology_tag
Type
string
Description
Psychology tag filter.
Name
q
Type
string
Description
Free-text filter over template, example, and psychology notes.
Name
page
Type
integer
Description
Page number (default 1).
Name
limit
Type
integer
Description
Items per page (default 20, max 100). Totals are exact for this endpoint.

Request

GET

/v1/hooks/library

curl "https://api.virlo.ai/v1/hooks/library?psychology_tag=curiosity&limit=5" \
  -H "Authorization: Bearer {token}"

Response (item)

{
  "data": [
    {
      "hook_text": "Imagine finishing in 4 hours what used to take all day.",
      "example": "Imagine closing your client work by lunch—without cutting quality.",
      "psychology": "Future pacing (visualizes a desirable outcome and pulls the reader forward).",
      "psychology_tags": ["future_pacing", "aspiration"],
      "tags": ["productivity"],
      "library_category": { "slug": "productivity-focus-hooks", "name": "Productivity & Focus Hooks" }
    }
  ],
  "pagination": { "page": 1, "limit": 5, "total": 4160, "total_pages": 832, "has_next_page": true, "has_prev_page": false }
}

GET/v1/hooks/library/categories

Library Categories

The library's category slugs with per-category template counts — use these as the category filter above.

Cost per request:Free

Request

GET

/v1/hooks/library/categories

curl "https://api.virlo.ai/v1/hooks/library/categories" \
  -H "Authorization: Bearer {token}"

Response (abridged)

{
  "data": [
    { "slug": "educational-hooks", "name": "Educational Hooks", "description": null, "hook_count": 200 }
  ]
}

GET/v1/agents/:id/hooks

Agent Hooks

The ranked hook library of one of your content research agents: every extracted hook from the agent's collected videos, ranked by Virality Score or views — "the strongest hooks in my niche, with receipts". Works for one-shot and recurring agents; the id is interchangeable with a legacy orbit/comet id. Returns 404 for agents you don't own.

Pricing: $0.25 per call, free when the agent has data_intelligence_enabled — Data Intelligence customers already funded hook extraction through the +$1.00/run add-on.

Coverage semantics

The response's coverage object explains empty results: videos_with_hooks: 0 means the agent has no analyzed hook data yet (young agent, or Data Intelligence disabled) — not that the niche has no hooks. Fall back to /v1/hooks/trending filtered to your niche.

Query parameters

Name
platform
Type
string
Description
Platform filter.
Name
hook_type
Type
string
Description
Hook type filter.
Name
min_views
Type
integer
Description
Minimum source-video views.
Name
sort
Type
string
Description
weighted_score (default) or views.
Name
page
Type
integer
Description
Page number (default 1).
Name
limit
Type
integer
Description
Items per page (default 20, max 100).

Request

GET

/v1/agents/:id/hooks

curl "https://api.virlo.ai/v1/agents/{agent_id}/hooks?limit=30" \
  -H "Authorization: Bearer {token}"

Response (abridged)

{
  "data": {
    "agent_id": "0efe3660-...",
    "coverage": { "videos_collected": 28649, "videos_with_hooks": 2006 },
    "hooks": [
      {
        "hook_text": "This is AI that doesn't suck, part four.",
        "hook_type": "bold_claim",
        "visual_hook_type": "person_speaking_to_camera",
        "weighted_score": 78.37,
        "video": { "views": 128988804, "author_handle": "landonbtw", "author_followers": 221444 }
      }
    ]
  },
  "pagination": { "page": 1, "limit": 30, "total": 31, "total_pages": 2, "has_next_page": true, "has_prev_page": false }
}