Skip to content
CleanScript
CleanScript

Creator posts

List a creator's recent posts, and check for new ones on a schedule.

View as Markdown

List a creator's posts

GET /v1/posts returns a creator's recent posts, newest first. author is a profile or channel link in any form (youtube.com/@name, /channel/UC…, tiktok.com/@name, instagram.com/name), or a handle such as @Fireship with platform.

curl -G https://api.cleanscript.ai/v1/posts \
  -H "Authorization: Bearer $CLEANSCRIPT_API_KEY" \
  --data-urlencode "author=https://www.youtube.com/@Fireship" \
  -d limit=5

The response has the creator (author, with followers) and posts. Each post is the same object every route returns, so its url goes straight into /v1/transcript or /v1/extract.

Options

  • limit: how many posts, 12 by default. One call returns at most 30 on YouTube, 35 on TikTok and 12 on Instagram.
  • since: only posts published on or after a date, YYYY-MM-DD.
  • platform: needed only when author is a handle.

A call costs 1 credit. The list can be up to 10 minutes old. The same call within 10 minutes is free. On YouTube it holds videos, not Shorts, without descriptions, likes or comments, and with rounded view counts (the transcript call returns exact ones), and the dates of older videos are approximate. A profile that doesn't exist or is private returns author_not_found, with details.reason.

Check for new posts

To follow creators, run a job on a schedule (daily is plenty for most):

  1. Call /v1/posts with since set to the date of your last check. On YouTube, go one day further back, since its dates are approximate.
  2. Skip posts whose id you have already seen: since is a date, so a post from the day of your last check comes back again.
  3. Send each new post's url to /v1/transcript or /v1/extract, and store the result with the post id.
from cleanscript_ai import CleanScript

client = CleanScript()
seen = set(load_seen_ids())  # your storage

for creator in ["https://www.youtube.com/@Fireship", "https://www.tiktok.com/@nytimes"]:
    listing = client.posts(creator, since=last_check_date)
    for post in listing.posts:
        if post.id in seen:
            continue
        fields = client.extract(post.url, preset="mentions")
        save(post, fields)  # your storage
        seen.add(post.id)

Each check costs 1 credit per creator, plus the transcripts or fields of the new posts. For many creators, see Batches & automations.