# Creator posts

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

## 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`.

```bash
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
```

```python
listing = client.posts("https://www.youtube.com/@Fireship", limit=5)
for post in listing.posts:
    print(post.published_at, post.title, post.url)
```

```typescript
const listing = await client.posts("https://www.youtube.com/@Fireship", { limit: 5 })
for (const post of listing.posts) console.log(post.published_at, post.title, post.url)
```

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`.

```python
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)
```

```typescript
import { CleanScript } from "cleanscript"

const client = new CleanScript()
const seen = new Set(await loadSeenIds()) // your storage

for (const creator of ["https://www.youtube.com/@Fireship", "https://www.tiktok.com/@nytimes"]) {
  const listing = await client.posts(creator, { since: lastCheckDate })
  for (const post of listing.posts) {
    if (seen.has(post.id)) continue
    const fields = await client.extract(post.url, { preset: "mentions" })
    await 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](https://cleanscript.ai/docs/automations.md).