Fetch a post

Fetch one TikTok post by video id, with a fully structured payload and all engagement metrics — plays, likes, comments, shares, saves, and reposts.

GET /v1/tiktok/post/{video_id}

Path parameter

Parameter	Description
video_id	The numeric video id (e.g. 7523456789012345678) or a full TikTok video URL.

Example

curl "$LISTENX_BASE/v1/tiktok/post/7523456789012345678" \
  -H "X-API-Key: $LISTENX_KEY"

Response

{
  "id": "7523456789012345678",
  "url": "https://www.tiktok.com/@doc/video/7523456789012345678",
  "type": "video",
  "desc": "3 tips for whiter teeth #dentalcare @clinic",
  "created_at": "2025-06-12T15:25:12+00:00",
  "hashtags": ["dentalcare"],
  "mentions": ["clinic"],
  "author": {
    "id": "99887766",
    "unique_id": "doc",
    "nickname": "Dr. Smile",
    "sec_uid": "MS4wLjABAAAA…",
    "avatar_url": "https://…",
    "is_verified": true,
    "signature": "Dentist • tips & myths",
    "follower_count": 120400,
    "following_count": 180,
    "heart_count": 3400000,
    "video_count": 412
  },
  "engagement": {
    "play_count": 185300,
    "digg_count": 4045,
    "comment_count": 238,
    "share_count": 512,
    "collect_count": 1290,
    "repost_count": 12
  },
  "music": {
    "id": "…",
    "title": "original sound",
    "author": "doc",
    "is_original": true,
    "duration": 15,
    "play_url": "https://…"
  },
  "media": {
    "video": {
      "id": "…",
      "duration": 15,
      "ratio": "720p",
      "width": 720,
      "height": 1280,
      "cover": "https://…",
      "play_addr": "https://…",
      "download_addr": "https://…"
    },
    "images": []
  },
  "challenges": [ { "id": "…", "title": "dentalcare" } ],
  "is_ad": false,
  "region": "US",
  "billing": {
    "endpoint": "tiktok.post",
    "units": 1,
    "unit_price": "0.010000",
    "amount": "0.010000",
    "balance_after": "97.320000",
    "request_id": "…"
  }
}

Engagement metrics

Field	Description
play_count	Plays / views.
digg_count	Likes.
comment_count	Comments.
share_count	Shares.
collect_count	Saves (favourites).
repost_count	Reposts.

Why some fields are null

TikTok does not return every metric for every post. Fields that TikTok omits are returned as null rather than dropped, so your schema stays stable.

Media

• Videos: media.video gives duration, dimensions, cover image, and the play / download URLs.
• Photo-mode posts: type is photo and media.images is an array of image URLs (with width/height); media.video is null.

Billing

Billed per request (units = 1), regardless of media type. See Billing.

Errors

HTTP	code	Meaning
400	invalid_video_id	Not a valid video id / URL.
404	post_not_found	Private, deleted, or nonexistent.
429	upstream_rate_limited	Retry with backoff.
503	signer_unavailable	Signing service temporarily unavailable — retry.