---
title: "Ranked hooks extracted from an agent’s collected videos"
method: GET
path: "/v1/agents/{id}/hooks"
tags: ["Hooks"]
---

# Ranked hooks extracted from an agent’s collected videos

`GET /v1/agents/{id}/hooks`

## Request

- Base URL: `https://api.virlo.ai`
- URL: `https://api.virlo.ai/v1/agents/{id}/hooks`
- Auth: HTTP bearer

The hook library of one content research agent: the distinct hooks from the agent’s collected videos, ranked by Virality Score (default) or views. This is "the 30 strongest hooks in my niche, with receipts". Each video appears once, identical hooks are collapsed to their strongest source (usage_count says how many posts share it), and pagination.total is exact. Works for one-shot and recurring agents (the ID is interchangeable with a legacy orbit_id/comet_id). coverage counts distinct videos: when coverage.videos_with_hooks is 0 the agent has no analyzed hook data yet (young agent or Data Intelligence disabled), so fall back to GET /v1/hooks/trending filtered to your niche instead of concluding the niche has no hooks. Pricing: $0.25 per call, waived (free) when the agent has data_intelligence_enabled, because those customers already funded hook extraction via the Data Intelligence add-on, and free while coverage.videos_with_hooks is 0 (the agent is still collecting or has no analyzed hooks yet).

## Path parameters

- `id` string, required

## Query parameters

- `limit` number
- `page` number
- `platform` 'tiktok' | 'youtube' | 'instagram'
- `hook_type` string
- `min_views` number
- `sort` 'weighted_score' | 'views'

## Response `200`

- AgentHooksResponseDto
  - `data` AgentHooksDataDto, required
    - `agent_id` string, required
    - `coverage` AgentHooksCoverageDto, required
      - `videos_collected` number, required: Distinct videos this agent has collected.
      - `videos_with_hooks` number, required: Distinct collected videos with a classified hook. 0 with a young agent means "no hook data yet", not "no hooks in this niche": fall back to GET /v1/hooks/trending filtered to the niche.
    - `hooks` 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)