--- title: "One conversation with its messages and runs" method: GET path: "/v1/conversations/{conversation_id}" tags: ["chat"] --- # One conversation with its messages and runs `GET /v1/conversations/{conversation_id}` ## Request - Base URL: `https://api.hookdetector.com` (the document declares no server; this is the origin it was published from) - URL: `https://api.hookdetector.com/v1/conversations/{conversation_id}` - Auth: none declared One conversation: its newest messages in order (a page of `limit`; earlier_cursor pages back through older ones), and the runs those messages hold (started by the chat, or attached with conversation_id in the same stretch of time) with their hooks. Free. MCP: get_conversation. ## Path parameters - `conversation_id` string, uuid, required ## Query parameters - `limit` integer: messages per page, newest page first - `before` string, nullable: earlier_cursor from the previous page; leave out for the newest messages ## Headers - `authorization` string, nullable: Bearer hd_... from POST /v1/accounts or POST /v1/keys ## Response `200` Successful Response - ConversationOut - `conversation_id` string, required - `title` string, required - `language` string, nullable - `country` string, nullable - `posted_within_days` integer, nullable: the conversation's recency chip, or null for any time - `created_at` string, required - `updated_at` string, required - `messages` MessageOut[], required: the newest page of messages (all of them in a short conversation), oldest first - `role` string, required - `content` string, required - `run_id` string, nullable, required - `created_at` string, required - `runs` RunOut[], required: the runs this page's messages point at, and runs attached in the same stretch of time - `run_id` string, required - `kind` string: what the run researches: "short" (hooks from TikTok, Instagram and YouTube Shorts, POST /v1/research), "long" (how long-form YouTube outliers open, POST /v1/longform) or "packaging" (their titles and thumbnails, POST /v1/packaging). Every run from before 2026-10-07 is short - `topic` string, required - `requested` integer, required - `language` string, nullable: the language or dialect asked for, as sent, or null for any language - `country` string, nullable: the country asked for, as an ISO 3166-1 alpha-2 code (upper-cased, UK read as GB), or null for any country - `status` union, required - 'queued' | 'running' | 'done' | 'failed' - string - `error` string, nullable, required: on a failed run: why, ending with the request id - `reserved` integer, required: credits held for this run when it started; what it does not use is refunded when it finishes - `charged` integer, required: credits deducted from your balance for this run: what it used, never more than `reserved`; 0 while it runs, on a failed run, and on a run that found no hooks within the account's allowance of free empty runs (three a day, 500 credits in all; `outcome` says which) - `credits_ig` integer, required: Instagram provider credits used so far, including on a refunded run; what you pay is `charged` - `credits_tt` integer, required: TikTok provider credits used so far, including on a refunded run; what you pay is `charged` - `credits_yt` integer, nullable: of credits_tt, the provider credits that went to YouTube Shorts (since 2026-10-01; null on older runs); already inside credits_tt, never added again; what you pay is `charged` - `posted_within_days` integer, nullable: the recency window asked for (7, 30, 90 or 365 days), or null - `seed_hook_ids` string[], nullable: the seed hooks asked for, or null - `platforms` string[], nullable: the platforms this Short form run searches and delivers from ("tiktok", "instagram", "youtube"): the ones asked for, or all three; null on a long or packaging run - `stats` RunStats, required: A finished run's stats. Every key is optional: a failed or older run carries fewer, and a key added later reaches clients before this model names it. - `locale` LocaleOut - `subject` string, nullable: what was searched, read out of the topic - `language` string, nullable: the language or dialect enforced, or null - `country` string, nullable: the creators' country enforced, or null - `exclude` string[]: languages, dialects and countries the judges ruled out - `rejected_after_reading` integer: clips the judges refused after reading what they say and show: another language or dialect, or off topic - `dropped_other_country` integer: TikTok clips placed in another country, dropped before any credit was spent on them - `credits_lent_to_tiktok` integer: credits of Instagram's share that TikTok searched with instead; they are counted in credits_tt, not credits_ig - `dropped_carousels` integer: TikTok photo posts (slideshows) and Instagram carousels met at search and dropped unread, free: a run delivers single videos only since 2026-09-26 - `search_breadth` object: how widely the run searched, since 2026-09-28 - `phrases` object: search phrases asked for per round, per platform: 6 each for a request of up to 5 hooks, 30 on Instagram and 12 on TikTok for a larger one - `instagram_reels` object: Instagram sweeps that bought the viewless reels route (bought) and that skipped it because the popular route already found enough (skipped) - `rejections` object: why clips were refused, each clip in one bucket once; `outcome` says it in words - `other_country` integer: TikTok clips placed in another country, dropped unread and free, each clip once - `off_subject_or_locale` integer: read, and the judge refused them: not about the subject or, on a run with a language or country, not in it (one verdict answers both) - `other_language` integer: written up, and their own write-up placed them in another language or dialect - `no_words` integer: read, nothing said or shown, on a run whose language rules such a clip out - `other` integer: not checked because a check or a write-up failed - `languages` object: the languages the other_language clips were placed in, with counts, at most five plus other - `held_back` object: what kept clips out of the deck, by reason, each clip once, since 2026-10-08; `outcome` says the largest reasons in one sentence on a short deck - `proof` integer: on the subject, but no sign it travelled: a TikTok clip with fewer views than its creator has followers and no outlier of 2x, a clip under the view floor without proof, or one doing less than its creator's usual; each clip once, none that was delivered after all - `relevance` integer: read, and the judge refused them: not about the subject or, on a run with a language or country, not in it - `language` integer: their own write-up placed them in another language or dialect - `no_words` integer: nothing said or shown, on a run whose language rules such a clip out - `supply` integer: on the subject, 10,000 views or more, never read because the search ended first; counted only when the deck came back short - `other` integer: not checked because a step failed - `credits_waived` integer: provider credits a run that found no hooks used and was not charged; they still count against the key's credit_limit - `waiver_refused` object: on a run that found no hooks and was charged: the allowance of free empty runs that was used up, per_day (runs a UTC day) or lifetime (credits in all) - `limit` 'per_day' | 'lifetime' - `allowance` integer - `transcription` object: speech recognition on a dialect request: whether the language asked for is a dialect, TikTok clips whose auto captions (or missing captions) were heard again by OpenAI, the seconds and estimated dollars (ours, never charged to you), failures and clips past the run's ceiling - `charged` integer: credits deducted from your balance for this run: what it used, never more than `reserved`; 0 while it runs, on a failed run, and on a run that found no hooks within the account's allowance of free empty runs (three a day, 500 credits in all; `outcome` says which) - `credits_earlier_attempts` integer: provider credits spent by attempts before a restart; never charged to you - `talking` object: how the run told talking heads (hooks) from clips where nobody talks, since 2026-09-29 - `checked` integer: clips checked for a person talking - `talking` integer: of those, a person talking - `not_talking` integer: clips on the subject dropped because nobody talks on camera (since 2026-10-08) - `vision_calls` integer: frame checks it took - `certain_by_text` integer: decided from the words alone, with no frame check - `model` object: language model usage for the run - `patterns_model` object: language model usage of the one patterns call made after delivery (since 2026-10-01); absent when no call was made - `patterns_note` string: beside null patterns, one honest line: no opening structure is shared by two or more of the deck's hooks (quality round, 2026-10-01); absent otherwise - `posted_within_days` integer: the recency window the engine honoured, in days (since 2026-10-01) - `seeds` integer: seed hooks the engine steered by (since 2026-10-01) - `pool_size` integer: distinct clips found - `reused_from_earlier_runs` integer: clips taken from your earlier runs, not bought again - `resumed_from_earlier_attempt` integer: clips carried over from before a restart - `above_floor` integer: clips above the view floor - `on_topic_above_floor` integer: of those, the clips judged on topic - `delivered` integer: hooks delivered - `delivered_above_floor` integer: delivered hooks above the view floor - `undescribed_dropped` integer: chosen clips dropped because they could not be read - `hooks_not_verbatim` integer: opening lines not found word for word in the clip - `catchy_lines_not_verbatim` integer: catchy lines not found word for word - `catchy_lines_anchored` integer: catchy lines matched to the transcript - `catchy_lines_by_number` integer: catchy lines picked by number - `cross_posts_merged` integer: the same clip on both platforms, counted once - `timings` object: seconds spent per stage - `calls_by_route` object: provider calls per route - `latency` object: per provider route: calls, seconds, p50_s and max_s - `progress` ProgressOut, required - `stage` string, required: one of: queued, starting, reusing, searching_instagram, searching_tiktok, judging, transcribing, writing, searching_youtube, saving, done, failed, other - `message` string, required - `updated_at` string, nullable, required - `counts` ProgressCounts - `found` integer, required - `above_floor` integer, required - `on_topic` integer, required - `read` integer, required - `held` integer, required - `written` integer, required - `wanted` integer, required - `talking` integer, nullable: clips checked so far that show a person talking (the main deck's kind); since 2026-09-29 - `channels` integer, nullable: Long form and Packaging: channels measured so far, counting up while they are - `outliers` integer, nullable: Long form and Packaging: candidates that beat their channel by the bar once ranked, counting each channel's other uploads that did; once channels are measured - `measured` integer, nullable: Long form and Packaging: videos held against their own channel so far, the set the finished run's report.landscape.videos counts; once a channel is measured (since 2026-10-08) - `beat` integer, nullable: Long form and Packaging: how many of those beat the bar, the finished run's report.landscape.outliers; use it, not outliers, for a 'beat their channel' number (since 2026-10-08) - `preview` ProgressPreview[], nullable - `hook` string, nullable, required - `platform` 'tiktok' | 'instagram' | 'youtube', required - `creator` string, required - `views` integer, required - `topic` string, nullable, required - `cover_url` string, nullable, required - `onscreen_hook` string, nullable: the text on screen that opens the clip (its banner, else its first line on screen), null when none was read - `why` string, nullable: why the opening holds a viewer, as the finished hook's mechanism says it; null when none - `hook_type` string, nullable: since 2026-10-02: the device the opening uses, one of curiosity_gap, contrarian_claim, specific_number, identity_callout, stakes_threat, promise_payoff, pattern_interrupt, story_open, question, direct_command, other (then `hook_type_other` names it in two to five words). Null on older hooks and when the write-up gave none. A client should treat an unknown value as other. - `watch_url` string, nullable: the clip on its platform - `player_url` string, nullable: a 9:16 iframe src, the player the finished hook gets; null when it has none - `thumb_url` string, nullable: the clip's cover as a JPEG, served by this API with no key (the wall's route); null when there is none. Use it rather than cover_url, which is the platform's own address and may not load on your page - `feed` ProgressFeedEntry[], nullable: the live research wall: the clips the run is working on, newest first, at most 24; only while a run shows one (since 2026-09-30) - `key` string, required: opaque and stable per clip within the run; never the provider's id - `platform` 'tiktok' | 'instagram' | 'youtube', required - `creator` string, required - `views` integer, nullable, required - `state` 'found' | 'reading' | 'talking' | 'bonus' | 'passed', required: found: in the pool; reading: being read; talking: a person talking, held for the deck; passed: dropped (off subject, other language, not talking, not needed). bonus appears only on runs from before 2026-10-08, when Bonus was removed - `thumb_url` string, nullable, required: absolute URL of the clip's cover as a JPEG, no key needed (GET /v1/runs/{run_id}/thumbs/{key}); null when there is none - `line` string, nullable, required: the banner or the opening words, only once the judges passed the clip and it is on its way to delivery - `items` object[], nullable: on a running long or packaging run: the finds written so far in rank order, each as a card (video_id, kind, rank, title, channel, watch_url, thumbnail_url, views, duration_s, posted_at, posted_exact, age_days, outlier, outlier_score, outlier_tier, style_match, analysed, and hook on Long form, thumbnail_text and thumbnail_faces on Packaging); the whole find, in the shape `finds` carries, arrives with the finished run, which is when this is gone (since 2026-10-07; cards only since 2026-10-08) - `scan` ProgressScan - `tiles` ProgressScanTile[], required: at most 60, in the order the run first saw each video (oldest first); a tile never changes place. When more exist, the oldest not beat, reading or ready go first - `v` string, required: the YouTube video id (11 characters of A-Z a-z 0-9 _ -); its thumbnail is https://i.ytimg.com/vi/{v}/mqdefault.jpg - `s` string, required: found: a search returned it; on_topic: the title judge kept it; off_topic: the judge dropped it; measured: its channel's usual is known and it is under the bar; beat: its views are at least the bar times the channel's usual; reading: its transcript (Long form) or thumbnail (Packaging) is being read; ready: written up, it is a result; passed: dropped (no captions, another language, before 2023, unreadable, below the bar once dated, not needed). Read an unknown state as found - `x` number, nullable, required: how many times its channel's usual views it has, to one decimal, once known; else null - `lanes` object, required: counts: found (videos the run holds), on_topic (judged to be about the subject), measured (held against their own channel, the set report.landscape counts), beat (of those, how many beat the bar), reading (being read right now), ready (written up so far) - `created_at` string, required - `finished_at` string, nullable, required - `request_id` string, nullable, required: the X-Request-Id of the call that started it - `conversation_id` string, nullable, required: the chat conversation this run belongs to, or null for a run started outside one - `hooks` HookOut[], required: the main deck: clips where a person on camera is talking, ranked. Since 2026-09-29 it never holds a clip without talking; a run that found fewer talking heads than asked says so in `outcome` - `hook_id` string, required - `rank` integer, required - `hook` string, nullable, required: the exact opening line; null when the clip had none - `catchy_line` string, nullable, required - `main_idea` string, nullable, required - `why_it_travelled` string, nullable, required - `topic` string, nullable, required - `onscreen_text` string, nullable, required: text burned into the video; on hooks found before 2026-09-26, every slide of a photo post in order - `transcript` string, nullable, required - `transcript_kind` 'speech' | 'music' | 'none' | 'other', nullable - `language` string, nullable: the language or dialect the clip was judged to be in, named in English ("Moroccan Darija", not "Arabic"); null for hooks found before this field - `platform` union, required: tiktok, instagram or youtube (YouTube Shorts only, never long-form, since 2026-10-01; its watch_url is the Shorts form) - 'tiktok' | 'instagram' | 'youtube' - string - `creator` string, required - `views` integer, required - `likes` integer, nullable, required - `above_floor` boolean, required - `watch_url` string, required - `cover_url` string, nullable, required - `slide_count` integer, nullable, required: always null on hooks found since 2026-09-26 (no carousels are delivered); the slide count of a TikTok photo post on older hooks - `found_by` string, nullable, required - `caption` string, nullable, required - `verdict` string, nullable, required - `format` string, nullable: what kind of clip it is: talking_head, podcast, interview, stage (a person on camera talking; the main deck), or voiceover, text_on_screen, broll, skit, lipsync, trending_sound, slideshow, call_recording (a recorded call or voicemail), live_interaction (the creator with real people in the scene, not talking to the viewer), other (never delivered since 2026-10-08). Null on hooks found before 2026-09-29. A client should treat an unknown value as other. - `section` 'main': always "main": the deck of a person on camera talking. Bonus was removed on 2026-10-08, and bonus hooks older runs stored are no longer returned. - `creator_country` string, nullable: the country of the creator's TikTok account as an ISO 3166-1 alpha-2 code ("MA"), as TikTok states it on the clip's search row. It is the account's country, not GPS. Always null on Instagram, which states none, and on hooks found before 2026-09-30. Never guessed. - `place` string, nullable: the name of the place the creator tagged on the post (at most 80 characters), null when untagged, as most posts are. Where it was posted from, not where the creator lives. - `place_country` string, nullable: the tagged place's country as an ISO 3166-1 alpha-2 code, only when the platform states it (TikTok usually does, Instagram rarely). Null otherwise; never guessed from the name or the map position. - `banner` string, nullable: since 2026-09-30: the banner hook, the title-style text the creator placed on the video to hook the viewer (a headline, a "POV:", a question, a list title), verbatim as one line of at most 200 characters. Null when the clip has none: running subtitles of the speech, usernames, watermarks and a lower third naming the speaker are never a banner. Null on hooks found before 2026-09-30. `onscreen_text` still holds all the text read on screen. - `match` 'exact' | 'close', nullable: since 2026-09-30, on runs with a language or a country: "exact" when the clip is about the subject itself, "close" when it is about a neighbouring subject with the same intent (general wealth-building advice for "getting wealthy in your 20s"): a close match, delivered after every exact match and to be labelled as one. Null on hooks found before 2026-09-30 and on runs with no language or country, which are judged as before. - `style_match` boolean, nullable: since 2026-10-04, on a run whose request asked for a kind of opening ("controversial hooks", "question hooks", "storytime"): true when this hook opens that way (its hook_type is one asked), false when it is a strong hook on the subject that opens differently, delivered after the ones that match. Null when no kind was asked. - `signals` object, nullable: how far the clip travelled beyond its creator, from the platform's own numbers (TikTok carries all of them, Instagram at most comments and the post date); each key only when the platform stated it; null for a hook with none. Hooks are ranked by views, reach and shares and saves per view together since 2026-09-28 - `followers` integer: the creator's followers - `shares` integer - `saves` integer - `comments` integer - `posted` string: the post date, YYYY-MM-DD, UTC - `reach` number: views over the creator's followers: 12.5 means it reached 12.5 times the creator's own audience - `shares_per_1k` number: shares per 1,000 views - `saves_per_1k` number: saves per 1,000 views - `opening` 'banger' | 'ok' | 'weak' | 'other': how hard the clip's first words stop a scrolling viewer, as the write-up rated them; absent on hooks found before 2026-10-13 - `opening_why` string: at most 15 words on why the opening rates as it does - `posted_at` string, nullable: when the clip was posted, exact when the platform gives it; null when unknown - `age_days` number, nullable: days since posted_at, at delivery - `views_per_day` number, nullable: views divided by age_days - `creator_median_views` integer, nullable: the creator's usual views per video: the median of their recent videos, pinned excluded (TikTok may use likes per video as a proxy, said so in outlier_basis) - `outlier` number, nullable: views divided by the creator's usual views per video (`creator_median_views`): 31.2 means 31 times what this creator normally gets. Null when the creator's baseline was not priced for this run. - `outlier_basis` 'median_views' | 'likes_per_video', nullable: what creator_median_views was measured from, or null - `duration_s` integer, nullable: the clip's length in seconds - `paid` boolean, nullable: an ad, a paid partnership or branded content, as the platform labels it; null when unknown - `sound_reuse` integer, nullable: videos reusing the clip's sound - `own_sound` boolean, nullable: the sound is the creator's own - `hashtags` string[], nullable: the post's hashtags, at most 20, without the # - `virality` number, nullable: since 2026-10-01: how viral the clip is, 0 to 1 (0.58 is 58 out of 100), since 2026-10-02 on one fixed scale: the same clip scores the same in every run. Built from the outlier (views over the creator's usual, when known), freshness, travel (shares and saves per 1,000 views), own-sound reuse and a paid penalty; null on hooks found before this field. - `virality_why` string, nullable: one short line naming the strongest signal behind `virality` ("31x this creator's usual", "1.2M views in 4 days"); never empty when virality is set; null when unknown - `hook_type` string, nullable: since 2026-10-02: the device the opening uses, one of curiosity_gap, contrarian_claim, specific_number, identity_callout, stakes_threat, promise_payoff, pattern_interrupt, story_open, question, direct_command, other (then `hook_type_other` names it in two to five words). Null on older hooks and when the write-up gave none. A client should treat an unknown value as other. - `hook_type_other` string, nullable: two to five words naming the device when hook_type is other, else null - `mechanism` string, nullable: since 2026-10-02: why the opening stops the scroll, in at most two short sentences: what the first three seconds make the viewer think or feel, quoting the clip's own words (every quote is checked word for word against what was said or shown), and the open question the clip then pays off. Never a view or follower count. `why_it_travelled` carries the same text. Null on older hooks. - `visual_hook` string, nullable: since 2026-10-02: one sentence on what the banner or other on-screen text adds to the spoken opening; null when no on-screen text hooks - `audience` string, nullable: since 2026-10-02: the specific viewer this opening stops, a few words - `template` string, nullable: since 2026-10-02: the hook as a fill-in structure of at most 20 words, its subject words replaced by {placeholders} - `steal_it` string, nullable: since 2026-10-02: one sentence on how a creator in another niche reuses this exact move - `video_id` string, nullable, required - `player_url` string, nullable, required: a 9:16 iframe src (TikTok's player, Instagram's reel embed, YouTube's embed); null for an unusable id or a photo post found before 2026-09-26 - `aspect` string, required - `still_url` string, required: the card image as a JPEG, served by this API; no key needed - `media_url` string, nullable: our own player's source: put it in a