SocialCrawl
Cookbooks

Follow a list of creators and get only their new posts

Read the recent posts of the creators on your list in one call, refresh the numbers on the posts you keep, and store only what is new

Send your list of creators and get back the posts each one published in the last two days. Then refresh the numbers on the posts you already keep, and add new creators in bulk. The example follows charlidamelio on TikTok and NASA on Instagram and YouTube.

Measured on 18/11/2026: the walk returned 3 posts from the last two days for 3 credits. Refreshing two posts cost 3 credits and reading two profiles cost 2.

Start in five minutes

Set your key once. Every block on this page reads it.

Terminal
export SOCIALCRAWL_API_KEY=YOUR_API_KEY

Paste this prompt into your coding agent:

Prompt
Read https://www.socialcrawl.dev/docs/recipes/follow-creators.md and follow it to get the new posts of tiktok:charlidamelio, instagram:nasa and youtube:NASA. Use the key in SOCIALCRAWL_API_KEY. Price each call with a dry run first (dry_run=true or dry_run=1), which is free. Send max_credits=30 on the walk, and stop and ask me before a day's calls pass 40 credits.

Or price the daily walk yourself. A dry run plans it for 0 credits:

cURL
curl -G "https://www.socialcrawl.dev/v1/prism/discover" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  --data-urlencode "authors=tiktok:charlidamelio,instagram:nasa,youtube:NASA" \
  --data-urlencode "authors_match=walk" \
  --data-urlencode "relevance=off" \
  --data-urlencode "platforms=tiktok,instagram,youtube" \
  --data-urlencode "period=2d" \
  --data-urlencode "max_credits=30" \
  --data-urlencode "dry_run=true"

On 18/11/2026 it quoted exactly 3 credits: one page of posts for each creator.

How it works

  • You list each creator as platform:handle.
  • One call reads each creator's own feed for the window you set. It does not search.
  • Each answer carries a watermark. Send it back next time, and only newer posts come back.
  • A second call refreshes the views and likes of up to 100 stored posts at once.
  • A third call reads up to 50 profiles at once, when someone adds creators to the list.

What you need

CallWhat it givesCredits
GET /v1/prism/discover with authors_match=walkEach creator's posts in the windowEach feed page at its platform's price, often 1
POST /v1/prism/post-statsCurrent numbers for up to 100 post URLs1 a URL, 2 on Instagram, 5 on LinkedIn
POST /v1/prism/profilesUp to 50 profiles1 a row, 5 on LinkedIn

Steps

Step 1: walk the creators' feeds

cURL
curl -G "https://www.socialcrawl.dev/v1/prism/discover" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  --data-urlencode "authors=tiktok:charlidamelio,instagram:nasa,youtube:NASA" \
  --data-urlencode "authors_match=walk" \
  --data-urlencode "relevance=off" \
  --data-urlencode "platforms=tiktok,instagram,youtube" \
  --data-urlencode "period=2d" \
  --data-urlencode "max_credits=30"
Python
import json, os, urllib.parse, urllib.request

params = {"authors": "tiktok:charlidamelio,instagram:nasa,youtube:NASA", "authors_match": "walk",
          "relevance": "off", "platforms": "tiktok,instagram,youtube", "period": "2d", "max_credits": "30"}
url = "https://www.socialcrawl.dev/v1/prism/discover?" + urllib.parse.urlencode(params)
req = urllib.request.Request(url, headers={"x-api-key": os.environ["SOCIALCRAWL_API_KEY"]})
data = json.load(urllib.request.urlopen(req, timeout=120))["data"]
for post in data["items"]:
    print(post["published_at"], post["author"]["username"], post["url"])
print("next watermark:", data["next"]["watermark"])
  • authors_match=walk reads each creator's own posts. The default, filter, searches a topic and keeps only these authors' rows.
  • relevance=off keeps every post. Add keywords instead to keep only the posts about a topic.
  • period=2d keeps two days, so a daily run overlaps by one day and misses nothing.
  • Each post already carries engagement, its views and likes at the time in measured_at. Store them as the post's first reading.
Response (trimmed)
{
  "data": {
    "items": [
      {
        "platform": "tiktok",
        "url": "https://www.tiktok.com/@charlidamelio/video/7709289375825169678",
        "published_at": "2026-11-17T23:41:19.000Z",
        "author": { "username": "charlidamelio", "key": "tiktok:charlidamelio" }
      }
    ],
    "next": { "watermark": "eyJ2IjoxLCJ3Ijoi..." }
  }
}

A post made with another account can come back under that account's name. One of NASA's reels in the run carried empirestatebldg as its author.

Step 2: refresh the numbers on stored posts

cURL
curl -X POST "https://www.socialcrawl.dev/v1/prism/post-stats" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  -H "content-type: application/json" \
  -d '{"urls":["https://www.instagram.com/reel/DfpowZdlfMz/","https://www.tiktok.com/@nasa/video/7705995616794561805"]}'
Python
import json, os, urllib.request

body = {"urls": ["https://www.instagram.com/reel/DfpowZdlfMz/",
                 "https://www.tiktok.com/@nasa/video/7705995616794561805"]}
req = urllib.request.Request("https://www.socialcrawl.dev/v1/prism/post-stats", data=json.dumps(body).encode(),
                             headers={"x-api-key": os.environ["SOCIALCRAWL_API_KEY"], "content-type": "application/json"})
data = json.load(urllib.request.urlopen(req, timeout=120))["data"]
for row in data["results"]:
    print(row["status"], row["url"], row["engagement"])
  • Send up to 100 URLs from any mix of platforms.
  • A URL whose post is gone is refunded, so you pay only for rows that came back with numbers.

Step 3: read profiles in bulk

When someone adds creators to the list, read their profiles in one call.

cURL
curl -X POST "https://www.socialcrawl.dev/v1/prism/profiles" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  -H "content-type: application/json" \
  -d '{"items":[{"platform":"instagram","handle":"nasa"},{"platform":"tiktok","handle":"charlidamelio"}]}'
Python
import json, os, urllib.request

body = {"items": [{"platform": "instagram", "handle": "nasa"}, {"platform": "tiktok", "handle": "charlidamelio"}]}
req = urllib.request.Request("https://www.socialcrawl.dev/v1/prism/profiles", data=json.dumps(body).encode(),
                             headers={"x-api-key": os.environ["SOCIALCRAWL_API_KEY"], "content-type": "application/json"})
data = json.load(urllib.request.urlopen(req, timeout=120))["data"]
for row in data["results"]:
    author = row["data"]["author"] if row["status"] == "ok" else {}
    print(row["status"], row["platform"], author.get("username"), author.get("followers"))
  • A handle that is not found is refunded.
  • Add "include": "posts" to get each creator's latest posts in the same call, for one more posts page each.

Store only what is new

Key each post on its URL. Save data.next.watermark after every walk and send it back as since_watermark on the next one. The walk then returns only posts newer than the last run, so a quiet day returns nothing new. The walk still costs one page per creator. Keep the numbers from step 2 with the date you read them, so you can chart how a post grew.

What it costs

PartCredits
A dry run of any call0
The walk, one page per creator1 on TikTok, Instagram and YouTube
Refreshing one post's numbers1, or 2 on Instagram
One profile1, or 5 on LinkedIn

What the example runs measured on 18/11/2026:

RunCallsCredits
The three steps3 paid, 1 dry run8
The full program straight after: the walk again, then numbers for the 3 posts it stored25

The second walk found the first run of the same request and returned it for free. The 3 posts were one on TikTok and two on Instagram, so the refresh cost 1 + 2 + 2.

Tips, and what not to use

  • Price the walk again whenever the list grows. It costs one page per creator per run, so 50 creators cost about 50 credits a run.
  • For lists longer than a URL holds, store the list once with POST /v1/prism/discover/inputs and send its author_list_id.
  • Refresh only the posts you still report on, such as the last two weeks. Each refresh is billed.
  • Do not call each creator's profile every day to find new posts. The walk reads their feeds in one call and returns only the posts in your window.

Full program and agent brief

Next steps