Log inStart Free Trial
easyCoexistence Official APIs

Listing a TikTok account's videos through the API

TikTok's API for Business lists an account's public posts with GET /business/video/list/, starting from the newest, up to 20 per page. Name the fields to return, such as item_id, caption, share_url and video_views, and page through with cursor while has_more is true. filters.video_ids picks out particular posts, and each item_id is the ID that comment calls take.

easyCoexistence lists a TikTok account's recent posts with list_social_posts from Claude, ChatGPT or your own code, with each post's item_id, caption, link and counts, and get_social_credentials gives your own code the token for later pages and other fields.

20

Most posts /business/video/list/ returns per page; max_count defaults to 10.

Milliseconds

Unit of cursor, a UTC Unix timestamp; the endpoint returns posts published before it.

item_id

The default field, which a request naming several fields must include, or an error may occur.

40/min

Calls allowed per authorized account on this endpoint, as on each Accounts API endpoint.

What does the endpoint return?

The account's public posts: videos shown on its profile, photo and text posts, and Only show in ads videos, which run as ads without appearing on the profile. media_type tells VIDEO from PHOTO, which covers photo and text posts. Posts TikTok filtered out for violations, such as music copyright, are left out of the list.

How do you call it?

With a GET and URL parameters: business_id, fields as a JSON array, and optionally filters, cursor and max_count, which defaults to 10. The token goes in the Access-Token header, and the developer app needs the Get Account Media permission under TikTok Accounts:

List the latest posts
curl -G 'https://business-api.tiktok.com/open_api/v1.3/business/video/list/' \
  -H 'Access-Token: <ACCESS_TOKEN>' \
  --data-urlencode 'business_id=<OPEN_ID>' \
  --data-urlencode 'fields=["item_id","create_time","media_type","caption","share_url","thumbnail_url","video_views","likes","comments","shares"]' \
  --data-urlencode 'max_count=20'

Which fields describe a post?

Besides the metrics, which run from video_views to impression_sources, the list carries these, all under the video.list scope:

  • item_id: the post's ID, used by comment calls and by filters.video_ids.
  • media_type: VIDEO, or PHOTO for a photo or text post.
  • is_ad: whether the post is being used in an ad.
  • create_time: when the post was published, as Unix seconds in UTC.
  • caption: the post's description, hashtags included.
  • share_url: a shareable link, which behaves differently on mobile and desktop.
  • embed_url: a player link for other sites, which does not play posts set to Friends or Only you.
  • thumbnail_url: a temporary preview image whose expiry sits in its x-expires parameter.
  • video_duration: the length in seconds, to three decimals.

What does a page of results look like?

A videos array in the order TikTok returns it, plus cursor, the value to send for the next page, and has_more, which says whether there is one. create_time arrives as a string of Unix seconds. TikTok's example, trimmed to the descriptive fields and the counts:

A page from /business/video/list/
{
  "code": 0,
  "message": "OK",
  "request_id": "2021080307532501024502410704A7306F",
  "data": {
    "videos": [
      {
        "item_id": "6990565363377392901",
        "create_time": "1627617835",
        "caption": "little coco",
        "share_url": "https://www.tiktok.com/@feather_in_the_w1nd/video/6990565363377392901?utm_campaign=tt4d_open_api&utm_source=6979330045630218242",
        "likes": 10,
        "comments": 2,
        "shares": 0,
        "video_views": 1231
      }
    ],
    "cursor": 0,
    "has_more": false
  }
}

How does pagination work?

By time. cursor defaults to the current moment in milliseconds, so the first page holds the newest posts, and each response returns the cursor for the next request. Pass it while has_more is true. A custom timestamp lists the posts published before that moment, and TikTok's trust and safety rules can make a page shorter than max_count even when more posts remain.

Every page, in Python
import json, requests

API = "https://business-api.tiktok.com/open_api/v1.3"

def all_posts(token: str, business_id: str, fields: list[str]):
    params = {"business_id": business_id, "fields": json.dumps(fields), "max_count": 20}
    while True:
        r = requests.get(f"{API}/business/video/list/", headers={"Access-Token": token},
                         params=params, timeout=30).json()
        if r["code"] != 0:
            raise RuntimeError(f"{r['code']}: {r['message']}")
        yield from r["data"].get("videos", [])
        if not r["data"].get("has_more"):
            return
        params["cursor"] = r["data"]["cursor"]

How do you fetch particular posts?

With filters, a JSON object: video_ids lists the post IDs to return, such as the post_ids from a publishing status. ad_post_only, valid only beside video_ids, keeps just the posts authorized to advertisers for Spark Ads. A filtered request takes the same fields as any other, so one call can return the latest numbers for a handful of known posts.

The filters parameter
filters={"video_ids":["6995316737801538821","8015388216995316737"]}

Which limits apply?

The Accounts API allows 40 calls a minute for each authorized account on this endpoint, and an app's Accounts API calls together get 600 a minute at the Basic level and 1,000 above it. Descriptive fields are real time, counts usually lag 24 to 48 hours, and a post's data stops updating 365 days after it was published.

How does easyCoexistence list the videos?

With list_social_posts, which takes the account_id and an optional limit, from 1 to 20 for TikTok. It returns TikTok's first page: the most recent posts with item_id, create_time, caption, share_url, thumbnail_url, video_views, likes, comments and shares, plus cursor and has_more. Later pages and other fields come from your own code, with the token and business_id from get_social_credentials:

The next page from your own code
GET https://business-api.tiktok.com/open_api/v1.3/business/video/list/
  ?business_id=<BUSINESS_ID>
  &fields=["item_id","media_type","caption","embed_url"]
  &cursor=1793404800000
  &max_count=20
Access-Token: <ACCESS_TOKEN>

Common mistakes

  • Requesting fields without item_id. TikTok's reference warns that a request naming several fields without it may fail.
  • Stopping when a page comes back short. TikTok can return fewer than max_count posts while has_more is still true, so follow has_more instead.
  • Storing thumbnail_url for later. It is a temporary link that expires at the time in its x-expires parameter, so fetch a fresh one when it is needed.
  • Looking for private posts in the list. The endpoint returns public posts only.
Doing this with EasyCoexistence

US$ 9 to US$ 0.75 per connection per month, falling as you add connections, with the first 3 days free.

easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.

Frequently asked questions

How many TikTok videos can the API list at once?

Up to 20 per page from /business/video/list/. max_count sets the page size and defaults to 10; follow cursor for more.

Does the TikTok API list photo posts too?

Yes. /business/video/list/ returns public video, photo and text posts, and media_type tells VIDEO from PHOTO.

Does the TikTok video list include ad-only posts?

Yes. /business/video/list/ also returns Only show in ads videos, which run as ads without appearing on the profile, and is_ad says whether a post is being used in an ad.

Why is a TikTok post missing from the API list?

The endpoint lists public posts, and TikTok leaves out posts filtered for violations such as music copyright.

Keep reading

Connect your first channel in two minutes.

No platform reviews to wait for. Connect WhatsApp, Instagram, TikTok or another channel, then ask your AI to post, reply or report, and watch it work.

  • 3 days free
  • Cancel any time
  • Official APIs only
  • Monitored 24/7

Verified on