Ranked hooks extracted from an agent’s collected videos
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).
Request
- Base URL: https://api.virlo.ai
- URL: https://api.virlo.ai/v1/agents/{id}/hooks
- Auth: HTTP bearer
Path parameters
Agent UUID (or legacy orbit/comet id)
Query parameters
Items per page (1-100, default 20). Values above 100 are clamped.
Page number, 1-indexed (default 1).
Only hooks from this platform. Omit for all platforms.
Only hooks of this spoken/text hook type (e.g. tutorial_promise). The list grows over time: GET /v1/hooks/types has the current values. An unknown value is a 400 that lists them.
Only hooks from videos with at least this many views.
Rank by Virality Score (weighted_score, default), comparable across creator sizes, or by raw views.
Response
Example response
{
"data": {
"hooks": [
{
"hook_text": "Stop doing this if you want clear skin",
"hook_type": "negation",
"visual_hook_type": "person_speaking_to_camera",
"language": "en",
"outlier_ratio": 27.3,
"weighted_score": 37.6,
"usage_count": 1
}
]
},
"pagination": {
"page": 1,
"limit": 20,
"total": 42,
"total_pages": 3,
"has_next_page": true
}
}Changes
No recorded changes to this operation across all 1 revision of this API.