TikTok User Stories API

Endpoint

GET /v1/tiktok/user/stories

Parameters

username

TikTok username, with or without leading @ (max 100 characters). Provide exactly one of username, user_id, or url.

user_id

Numeric TikTok user ID, as returned by Search Users or User Profile. Provide exactly one of username, user_id, or url.

url

TikTok profile URL, e.g. https://www.tiktok.com/@tiktok (max 500 characters). Provide exactly one of username, user_id, or url.

pages

Number of pages to fetch, 1-1000 (default: 1). Each page returns up to 30 stories.

get_sentiment

Set to true to add AI emotion analysis (+$0.001/page)

Response fields

stories

Array of the user's live stories

video_id

Numeric video ID

title

Video caption

url

Direct link to the video

date

Publication date and time

date_timestamp

Publication date as a Unix timestamp

author

Author's TikTok username

source

"TikTok"

domain

"tiktok.com"

snippet

Video caption text

region

2-letter region code the video was posted from

play_count

Number of plays/views

likes

Number of likes

comments

Number of comments

Number of shares

downloads

Number of downloads

saves

Number of saves (favorites)

duration

Video duration in seconds (0 for photo posts)

is_ad

Whether the video is an ad

is_pinned

Whether the video is pinned to the author's profile

author_name

Author's display name

author_id

Author's numeric user ID

author_avatar

Author's avatar URL

author_url

Link to the author's profile

cover

Video cover/thumbnail URL

dynamic_cover

Animated cover URL

origin_cover

Original cover frame URL

video_url

Watermark-free playback/download URL (temporary)

video_url_watermarked

Watermarked playback URL (temporary)

size

File size of the watermark-free video in bytes

size_watermarked

File size of the watermarked video in bytes

images

Image URLs for photo posts; empty for videos

music_id

ID of the sound used

music_title

Title of the sound used

music_author

Artist of the sound used

music_url

Playback URL of the sound

music_cover

Cover image of the sound

music_album

Album of the sound, or empty string

music_original

Whether the sound is an original sound

music_duration

Sound duration in seconds

mentioned_user_ids

Numeric IDs of the users mentioned in the caption

sentiment

Emotion analysis: emotions, dominant_emotion, emotional_intensity, polarity (when get_sentiment=true)

username

The user's username

pages

Number of pages returned

count

Number of results returned

Example Request

curl "https://apidirect.io/v1/tiktok/user/stories?username=jamescharles"   -H "X-API-Key: YOUR_API_KEY"

import requests

response = requests.get(
    "https://apidirect.io/v1/tiktok/user/stories",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"username": "jamescharles"}
)
print(response.json())

Example Response

{
  "stories": [
    {
      "video_id": "7695841671082216717",
      "title": "",
      "url": "https://www.tiktok.com/@jamescharles/video/7695841671082216717",
      "date": "2026-10-12 17:56:33",
      "date_timestamp": 1791827793,
      "author": "jamescharles",
      "source": "TikTok",
      "domain": "tiktok.com",
      "snippet": "",
      "region": "US",
      "play_count": 55471,
      "likes": 1352,
      "comments": 0,
      "shares": 25,
      "downloads": 0,
      "saves": 0,
      "duration": 7,
      "is_ad": false,
      "is_pinned": false,
      "author_name": "James Charles",
      "author_id": "190068318278651904",
      "author_avatar": "https://p16-common-sign.tiktokcdn-eu.com/.../avatar.jpeg",
      "author_url": "https://www.tiktok.com/@jamescharles",
      "cover": "https://p16-common-sign.tiktokcdn-eu.com/.../cover.jpeg",
      "dynamic_cover": "https://p16-common-sign.tiktokcdn-eu.com/.../dynamic_cover.webp",
      "origin_cover": "https://p16-common-sign.tiktokcdn-eu.com/.../origin_cover.jpeg",
      "video_url": "https://v19.tiktokcdn-eu.com/.../video.mp4",
      "video_url_watermarked": "https://v19.tiktokcdn-eu.com/.../video_wm.mp4",
      "size": 10246341,
      "size_watermarked": 9402354,
      "images": [],
      "music_id": "7695565970584193805",
      "music_title": "original sound - darth.amidalaa",
      "music_author": "darth amidala",
      "music_url": "https://sf16-music.tiktokcdn-eu.com/.../music.mp3",
      "music_cover": "https://p16-common-sign.tiktokcdn-eu.com/.../music_cover.jpeg",
      "music_album": "",
      "music_original": true,
      "music_duration": 7,
      "mentioned_user_ids": []
    }
  ],
  "username": "jamescharles",
  "pages": 1,
  "count": 3
}

Frequently asked questions

Why is the list empty?

Stories expire after 24 hours, so most accounts have none live at any given moment.

Can I look up a user by URL or user ID?

Yes. Provide exactly one of username, user_id, or url.

How does pricing work?

You only pay for successful requests. The TikTok User Stories API costs $0.006 per page. There are no monthly fees or commitments. You get 50 free requests per endpoint every month.

Do I need a credit card to start?

No. You can sign up and use the free tier (50 requests/endpoint/month) without adding a payment method. You only need to add a card when you want to exceed the free tier.

Are there rate limits?

Yes, there's a concurrency limit of 10 simultaneous requests per endpoint per user. If you need more, just get in touch.