TikTok Channel Posts API
Latest videos from a TikTok profile. May return a labelled 6h-stale snapshot (degraded + staleAgeMs) when the live list is blocked. Failures are 0 credits.
GET request to /v1/tiktok/channel-posts that responds with clean JSON and costs 2 credits. Pass cache=true for a free 24h cache hit; default is always fresh. Start with 100 free credits — no credit card.What is the TikTok Channel Posts API?
Send a profile URL, @handle, or username and the TikTok Channel Posts API returns that creator's most recent videos as clean, structured JSON. When TikTok blocks the live post list, a successful call may be a snapshot up to 6 hours old — not a silent cache. Those responses set degraded=true, degradedReason=extended-timeout-served-stale, and staleAgeMs / staleTtlMs (21600000) / staleFinishedAt so you can see how old the snapshot is before you treat the numbers as current. A live miss with no in-window snapshot is 502 UPSTREAM_UNAVAILABLE (0 credits) with timings{path,nativeMs,apifyMs,apifyStatus,decodoStatus,…}. views / likes / comments / shares / saves each carry *IsApproximate from the same display-rounding ladder as top-search (rounded → true, exact → false). Each post includes the TikTok page URL and video ID, caption, publish date, duration, thumbnail, playable videoUrl plus downloadUrl / downloadUrlNoWatermark when TikTok exposes them (CDN-signed — check mediaUrlsExpireAt before archiving), hashtags, sound/music, isAd / isPaidPartnership / shopProductUrl when present, and the author's profile (id, secUid, username, display name, followers, verified badge, avatar). Fetch up to 200 posts per call with the limit parameter. hasMore / nextCursor are only set when a leftover row is already in hand. A cursor TikTok rejects comes back as 400 INVALID_CURSOR. Flat 2 credits per successful call (including a labelled stale snapshot); failures stay 0 credits.
What you get
- Latest public videos from any TikTok profile
- Playable videoUrl + download URLs (CDN-signed; mediaUrlsExpireAt)
- Caption, publish date, duration, thumbnail, hashtags, and sound name
- Views, likes, comments, shares, and saves per video
- Author profile — id, secUid, handle, name, followers, verified, avatar
- isAd / isPaidPartnership / shopProductUrl when TikTok exposes them
- May serve a labelled 6h-stale snapshot: degraded + staleAgeMs / staleTtlMs / staleFinishedAt
- hasMore only when a leftover row is in hand — flat 2 credits on success, 0 on failure
- timings{path,nativeMs,apifyMs,apifyStatus,decodoStatus,pagesFetched} on every response including 502
Try it
Fill in the parameters below and copy a ready-to-run request, or open the live Playground to run it against your account (no API key paste).
Parameters
curl "https://api.captapi.com/v1/tiktok/channel-posts?url=https%3A%2F%2Fwww.tiktok.com%2F%40natgeo" \
-H "Authorization: Bearer capt_live_..."
# or: -H "x-api-key: capt_live_..."Edit the parameters and the code updates instantly. Switch languages and hit copy.
Example response
{
"success": true,
"data": {
"url": "https://www.tiktok.com/@natgeo",
"totalReturned": 2,
"posts": [
{
"platform": "tiktok",
"url": "https://www.tiktok.com/@natgeo/photo/7671655634479156494",
"id": "7671655634479156494",
"caption": "There's more to the mad hatterpillar than funky headwear. By wearing the stacked remains of its old head capsules, it confuses predators, giving it more time to escape. 🎩 #Underdogs is streaming on @Disney+ and @hulu.",
"publishedAt": "2026-08-08T13:42:53.000Z",
"durationSeconds": 31.659,
"thumbnailUrl": "https://p16-common-sign.tiktokcdn.com/tos-useast5-p-0068-tx/owCc3tEwJKAiUi5MBsI8wOfCAkBcBBAI9Al1c3~tplv-tiktokx-cropcenter-q:300:400:q70.webp?dr=14782&refresh_token=9b419d9e&x-expires=1786348800&x-signature=AtHD%2FQzBnExrYlaiQ9ATmAC2JSY%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=my&biz_tag=tt_video&s=PUBLISH&sc=cover",
"mediaType": "photo",
"contentType": "photo",
"width": 1080,
"height": 1920,
"hasWatermark": false,
"author": {
"id": "6780344874811442181",
"secUid": "MS4wLjABAAAAEf96k3JW8-3eOhgzgQswlFF6ZDnn1dzqWWorJjwDsiNZymqTtvOcFhp_RiYYST6s",
"username": "natgeo",
"displayName": "National Geographic",
"url": "https://www.tiktok.com/@natgeo",
"followers": 9590843,
"verified": true,
"profileImage": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/324924e171e481040a1ea202962f6e07~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp?dr=10796&refresh_token=ee0a2fa4&x-expires=1786348800&x-signature=GjL1qODTN0sutAGopvXV5kCBjhw%3D&t=223449c4&ps=87d6e48a&shp=d05b14bd&shcp=132edbea&idc=my&sc=avatar&s=PUBLISH"
},
"engagement": {
"views": 29128,
"likes": 2305,
"comments": 35,
"shares": 251,
"saves": 155
},
"hashtags": [
"underdogs"
],
"mentions": [
{
"userId": "6844178288162063365",
"secUid": "MS4wLjABAAAAqUNM3kSR5Ftp2-qS8tMXPcOX8sQIrztPZ6xbXF19zZMi805WqA158zLCL15WnGHL",
"start": 200,
"end": 208
},
{
"userId": "6647632235926503429",
"secUid": "MS4wLjABAAAAM4MY_0Mngt5neJyXf3HiDcYRyCBv_dMx1DU4OpbQNbNThk2QRZLWPKgSidSUqAd8",
"start": 213,
"end": 218
}
],
"musicName": "original sound - natgeo",
"musicId": "7671655849333099278",
"musicAuthor": "National Geographic",
"locationCreated": "GB",
"descLanguage": "en",
"isAd": false,
"isPaidPartnership": false
},
{
"platform": "tiktok",
"url": "https://www.tiktok.com/@natgeo/photo/7671355385575410958",
"id": "7671355385575410958",
"caption": "More than two centuries after excavations began, archaeologists are still uncovering parts of Pompeii. Archaeologists still use methods from the past, but new technology is helping them explore the ancient city while protecting the site. #PompeiiOutOfTime with Tom Hiddleston is now streaming on @Disney+ and @hulu",
"publishedAt": "2026-08-07T18:17:23.000Z",
"durationSeconds": 39.574,
"thumbnailUrl": "https://p16-common-sign.tiktokcdn.com/tos-useast5-p-0068-tx/o0bRJ4IxLAOGYe8AUCsgALFICO2vBffepFHtHO~tplv-tiktokx-cropcenter-q:300:400:q70.webp?dr=14782&refresh_token=26b45f7e&x-expires=1786348800&x-signature=NCt%2BCGLGMrck73N5qPCDj%2BTryAA%3D&t=bacd0480&ps=933b5bde&shp=d05b14bd&shcp=132edbea&idc=my&sc=cover&biz_tag=tt_video&s=PUBLISH",
"mediaType": "photo",
"contentType": "photo",
"width": 1080,
"height": 1920,
"hasWatermark": false,
"author": {
"id": "6780344874811442181",
"secUid": "MS4wLjABAAAAEf96k3JW8-3eOhgzgQswlFF6ZDnn1dzqWWorJjwDsiNZymqTtvOcFhp_RiYYST6s",
"username": "natgeo",
"displayName": "National Geographic",
"url": "https://www.tiktok.com/@natgeo",
"followers": 9590843,
"verified": true,
"profileImage": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/324924e171e481040a1ea202962f6e07~tplv-tiktokx-cropcenter-q:1080:1080:q70.webp?dr=10796&refresh_token=ee0a2fa4&x-expires=1786348800&x-signature=GjL1qODTN0sutAGopvXV5kCBjhw%3D&t=223449c4&ps=87d6e48a&shp=d05b14bd&shcp=132edbea&idc=my&sc=avatar&s=PUBLISH"
},
"engagement": {
"views": 9116,
"likes": 548,
"comments": 6,
"shares": 9,
"saves": 18
},
"hashtags": [
"pompeiioutoftime"
],
"mentions": [
{
"userId": "6844178288162063365",
"secUid": "MS4wLjABAAAAqUNM3kSR5Ftp2-qS8tMXPcOX8sQIrztPZ6xbXF19zZMi805WqA158zLCL15WnGHL",
"start": 297,
"end": 305
},
{
"userId": "6647632235926503429",
"secUid": "MS4wLjABAAAAM4MY_0Mngt5neJyXf3HiDcYRyCBv_dMx1DU4OpbQNbNThk2QRZLWPKgSidSUqAd8",
"start": 310,
"end": 315
}
],
"musicName": "original sound - natgeo",
"musicId": "7671355506610473742",
"musicAuthor": "National Geographic",
"locationCreated": "ZA",
"descLanguage": "en",
"isAd": false,
"isPaidPartnership": false
}
],
"nextCursor": "1786115938373",
"hasMore": true
}
}Billing metadata is returned in response headers: X-Captapi-Credits (credits charged), X-Captapi-Cache (hit or miss), and X-Captapi-Source. Failed requests (4xx/5xx) are never charged. See the full list of error codes in the error reference.
Response structure
A successful call returns success and a data object with the following fields:
Top-level fields
urlCanonical URL of the item.totalReturnedNumber of items returned in this response.nextCursorCursor to pass for the next page of results. May be null when the platform does not expose deep pagination (e.g. some Facebook Ad Library searches).hasMoreWhether more results are available beyond this page. When true, pass nextCursor to fetch the next page.
Posts
Each item in posts contains:
platformPlatform identifier for this response (matches the endpoint's platform).urlCanonical URL of the item.idId of this posts item.captionPost or creative caption when the platform exposes one.publishedAtPublish date (ISO 8601) when the platform exposes an absolute timestamp.durationSecondsLength in seconds for this item (full media length, or a segment span when the endpoint documents a start/end).thumbnailUrlThumbnail image URL.mediaTypeMedia type label for this item (platform-specific enum).contentTypeContent type. Example: "photo".widthWidth in pixels.heightHeight in pixels.hasWatermarkHas watermark. Example: false.authorAuthor name or handle.engagementEngagement metrics for the item.hashtagsHashtags extracted from the text.mentionsAccounts mentioned in the text.musicNameName of the soundtrack used.musicIdID of the soundtrack used.musicAuthorMusic author. Example: "National Geographic".locationCreatedISO country where the TikTok video was posted/served (item locationCreated). Not the creator's home country — use authorRegion or /tiktok/profile-region for that.descLanguageLanguage code TikTok assigns to the video caption when exposed.isAdWhether the item is a paid promotion.isPaidPartnershipIs paid partnership. Example: false.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| url | string | Yes | TikTok profile URL, @handle, or username, e.g. https://tiktok.com/@username. Not a YouTube channel URL. The URL platform must match this endpoint's platform. Do not pass cross-platform URLs, e.g. YouTube to TikTok, Instagram to Facebook, LinkedIn to X/Twitter, or Pinterest to Rumble. |
| limit | integer | No | How many of the creator's latest videos to return on this page (default 20, max 200). Newest first. Flat 2 credits per call. |
| cursor | string | No | Pagination cursor. Leave empty for the first page; then pass the nextCursor value returned in the previous response (TikTok's max_cursor timestamp, e.g. 1783614676000). A null nextCursor means the end of the list. |
| cache | boolean | No | Set true to serve from the 24h response cache (0 credits on hit). Default false — always fetch fresh. |
Authentication: send your key as Authorization: Bearer capt_live_.... A typical call costs 2 credits. Pass cache=true for a free 24h cache hit; default is always fresh.
How it works
- 1. Sign up — get 100 free credits, no card required.
- 2. Create a key from your dashboard.
- 3. Send one request to
/v1/tiktok/channel-postsand parse the JSON response.
Use cases
Content Pipelines
Ingest a channel's catalog in bulk.
Monitoring
Detect new uploads automatically.
Archiving
Snapshot a creator's library — metadata plus CDN media URLs (re-fetch before mediaUrlsExpireAt).
Analytics
Aggregate performance across many videos.
Frequently asked questions
What does the TikTok Channel Posts API do?+
The TikTok Channel Posts API lets you list items in bulk with metadata from a public TikTok post using one GET request to /v1/tiktok/channel-posts. It returns clean JSON — no OAuth or infrastructure setup required.
How many credits does the TikTok Channel Posts API cost?+
Each successful call costs 2 credits. Pass cache=true to serve from the 24h cache (0 credits on hit); default is always fresh. Selected profile endpoints also accept cacheMaxAge=1d|3d|7d|14d|30d. Failed or empty results are never charged.
Do I need a TikTok API key or OAuth?+
No. A single Captapi key works across every platform Captapi supports — YouTube, TikTok, Instagram, Facebook, Twitter/X, Reddit, Threads, Bluesky, Pinterest, LinkedIn, Rumble, Spotify, Kwai, and more. We handle proxies, rate limits, retries, and authentication for you.
Why did channel-posts take ~94s and then fail while channel-details answered in 2s?+
channel-details is one profile-page parse. channel-posts has to load the post list — TikTok soft-blocks the mobile post API, so the old path stacked a 75s native ladder on a 25s fallback. Native now races mobile and signer only (~16s). Decodo is a dormant third leg: circuit-open after 0-XHR misses, then one half-open probe after the TTL (timings.decodoOpenedAt / decodoRetryAt). The working cover is Apify (~8s when it finishes; 16s client cutoff). A failure is 502 UPSTREAM_UNAVAILABLE with timings{path,nativeMs,apifyMs,apifyStatus,decodoStatus,decodoOpenedAt,decodoRetryAt,…}. A stale pool page stamps degraded + degradedReason plus staleAgeMs / staleTtlMs (6h) / staleFinishedAt. Failures stay 0 credits.
How is viewsIsApproximate set?+
The same display-rounding ladder as /tiktok/top-search. Values under 10 000 are exact (false). At or above 10 000, a multiple of 100 (or of 100 000 at 1M+) is approximate (true). A rounded value cannot carry false, and an exact value cannot carry true.
Can this endpoint serve stale data? How old?+
Yes — when the live post list is blocked, a 200 may be a snapshot up to 6 hours old (staleTtlMs=21600000). Those calls still cost 2 credits and always set degraded=true, degradedReason=extended-timeout-served-stale, plus staleAgeMs and staleFinishedAt so you can see whether the snapshot is ten minutes or five hours old. No in-window snapshot → 502, 0 credits.
Is the TikTok Channel Posts API suitable for production use?+
Yes. It is a stable REST endpoint with predictable JSON and automatic retries. Pass cache=true to serve from the 24h cache (0 credits on hit); default is always fresh. Selected profile endpoints also accept cacheMaxAge=1d|3d|7d|14d|30d. Use it for analytics, monitoring, and content automation.
More TikTok APIs
Ready to use the TikTok Channel Posts API?
Sign up, grab your key, and make your first call in 60 seconds.