Skip to content

Get video

One video for close reading: its whole hook and description, stats, creator, niche, formats, the classifier's labels (visual formats, hook tactic, tone, talent, awareness, emotional trigger, asset type) and how_its_built, a note on how the video is put together from those labels (null until the classifier has read it). It describes construction, not why the video got its views. No download and no transcript. Same answer as the MCP tool get_video. Each request counts against the team's call allowance, shared with MCP; past it, a 402.

get/api/v1/videos/{id}

Authentication

OAuth token, API key or signed-in session, sent as Authorization: Bearer <token> (a session rides on its cookie). An OAuth token needs mcp:read. See authentication.

Path parameters

  • idstring (uuid)required

    The video id, as in its page URL /videos/{id}.

Response fields

  • idstring (uuid)

  • hookstring or null

    The whole opening line.

  • descriptionstring or null

    The whole description.

  • platformenum

    One of tiktok, instagram.

  • languagestring or null

    ISO 639-1 code, e.g. en.

  • hook_tacticstring or null

    The classifier's hook tactic; null until it has read the video.

  • tonestring or null

    The classifier's tone; null until it has read the video.

  • visual_formatsarray or null

    How the video is shot and edited (up to three); null until the classifier has read it.

  • creatorstring

    The account's username.

  • nichestring or null

  • formatsarray of string

  • viewsnumber

  • viral_factornumber

    Views divided by the account's usual views: 20 means twenty times its normal reach.

  • engagement_ratenumber

    Engagement as a share of views (0.05 = 5%).

  • posted_atstring (date-time)

  • coverstring or null (uri)

    Cover image.

  • urlstring (uri)

    The video's page on this site. Link the reader here.

  • original_urlstring (uri)

    The post on TikTok or Instagram.

  • content_typeenum

    One of video, photo, null.

  • asset_typestring or null

    The classifier's asset type; null until it has read the video.

  • talentstring or null

    The classifier's talent; null until it has read the video.

  • awarenessstring or null

    The classifier's awareness stage; null until it has read the video.

  • emotional_triggerstring or null

    The classifier's emotional trigger; null until it has read the video.

  • how_its_builtstring or null

    How the video is put together, written from its labels: construction, not why it got its views. Null until the classifier has read it.

  • creator_genderstring or null

  • creator_urlstring (uri)

    The creator's page on this site.

  • niche_urlstring or null (uri)

    The niche's page.

Responses

  • 200

    One video in full: hook, description, labels, how it's built. Body: VideoDetail.

  • 400

    A parameter is malformed or not supported. Body: Problem.

  • 401

    No account: send an API key, an OAuth access token or a session cookie. WWW-Authenticate names the protected-resource metadata. Body: Problem.

  • 402

    The team's call allowance is used up (quota_exceeded), or the account has no plan and so no calls (no_plan), or an account with no plan asked past a list's first page (plan_limit); resolution says what to do and links the plans page. Body: Problem.

  • 403

    The token lacks mcp:read. Body: Problem.

  • 404

    No video with that id. A video added in the last hours can be missing until the library refreshes. Body: Problem.

  • 429

    Rate limit exceeded; wait Retry-After seconds. Body: Problem.

  • 500

    The request failed on our side. Body: Problem.