# Follow creators (/docs/recipes/follow-creators) 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. ```bash title="Terminal" export SOCIALCRAWL_API_KEY=YOUR_API_KEY ``` Paste this prompt into your coding agent: ```text title="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: ```bash title="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 | Call | What it gives | Credits | | --- | --- | --- | | `GET /v1/prism/discover` with `authors_match=walk` | Each creator's posts in the window | Each feed page at its platform's price, often 1 | | `POST /v1/prism/post-stats` | Current numbers for up to 100 post URLs | 1 a URL, 2 on Instagram, 5 on LinkedIn | | `POST /v1/prism/profiles` | Up to 50 profiles | 1 a row, 5 on LinkedIn | ## Steps ### Step 1: walk the creators' feeds **cURL** ```bash title="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** ```python title="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. ```json title="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** ```bash title="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** ```python title="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** ```bash title="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** ```python title="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 | Part | Credits | | --- | --- | | A dry run of any call | 0 | | The walk, one page per creator | 1 on TikTok, Instagram and YouTube | | Refreshing one post's numbers | 1, or 2 on Instagram | | One profile | 1, or 5 on LinkedIn | What the example runs measured on 18/11/2026: | Run | Calls | Credits | | --- | --- | --- | | The three steps | 3 paid, 1 dry run | 8 | | The full program straight after: the walk again, then numbers for the 3 posts it stored | 2 | 5 | 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 **Full program (Python)** ```python title="Python" # follow_creators.py: the new posts of the creators you follow, and fresh numbers on the posts you keep. # Run once a day: SOCIALCRAWL_API_KEY=... python3 follow_creators.py (Python 3.9+, nothing to install) import json import os import sqlite3 import urllib.parse import urllib.request KEY = os.environ["SOCIALCRAWL_API_KEY"] BASE = "https://www.socialcrawl.dev/v1" CREATORS = "tiktok:charlidamelio,instagram:nasa,youtube:NASA" def call(path, params=None, body=None): url = f"{BASE}/{path}" + ("?" + urllib.parse.urlencode(params) if params else "") data = json.dumps(body).encode() if body is not None else None req = urllib.request.Request(url, data=data, headers={"x-api-key": KEY, "content-type": "application/json"}) with urllib.request.urlopen(req, timeout=120) as res: return json.load(res) db = sqlite3.connect("follow.db") db.execute("CREATE TABLE IF NOT EXISTS posts (url TEXT PRIMARY KEY, author TEXT, published_at TEXT, views INTEGER, likes INTEGER)") db.execute("CREATE TABLE IF NOT EXISTS state (k TEXT PRIMARY KEY, v TEXT)") row = db.execute("SELECT v FROM state WHERE k = 'watermark'").fetchone() spent = 0 # 1. Walk each creator's own feed for the last two days, from the last watermark. params = {"authors": CREATORS, "authors_match": "walk", "relevance": "off", "platforms": "tiktok,instagram,youtube", "period": "2d", "max_credits": "30"} if row: params["since_watermark"] = row[0] answer = call("prism/discover", params) spent += answer.get("credits_used", 0) new = 0 for item in answer["data"]["items"]: cur = db.execute("INSERT OR IGNORE INTO posts VALUES (?, ?, ?, NULL, NULL)", (item["url"], (item.get("author") or {}).get("username"), item.get("published_at"))) new += cur.rowcount watermark = (answer["data"].get("next") or {}).get("watermark") if watermark: db.execute("INSERT OR REPLACE INTO state VALUES ('watermark', ?)", (watermark,)) # 2. Refresh the numbers on the newest 100 stored posts in one call. urls = [r[0] for r in db.execute("SELECT url FROM posts ORDER BY published_at DESC LIMIT 100")] if urls: stats = call("prism/post-stats", body={"urls": urls}) spent += stats.get("credits_used", 0) for r in stats["data"]["results"]: e = r.get("engagement") or {} db.execute("UPDATE posts SET views = ?, likes = ? WHERE url = ?", (e.get("views"), e.get("likes"), r.get("url"))) db.commit() for url, author, views, likes in db.execute("SELECT url, author, views, likes FROM posts ORDER BY published_at DESC LIMIT 10"): print(f"{author or '?':14} views={views} likes={likes} {url}") print(f"{new} new posts, {len(urls)} refreshed, {spent} credits") ``` **Agent brief** ```text title="Agent brief" Goal: each day, the new posts of tiktok:charlidamelio, instagram:nasa and youtube:NASA, with fresh numbers on the posts already stored. Read https://www.socialcrawl.dev/docs/recipes/follow-creators.md first. 1. Dry-run the walk with dry_run=true. Send max_credits=30. Stop and ask if a day's calls would pass 40 credits. 2. Call GET /v1/prism/discover with authors, authors_match=walk, relevance=off and period=2d, plus since_watermark from the last run. 3. Store each post by URL and save data.next.watermark. 4. Send the newest 100 stored URLs to POST /v1/prism/post-stats and store the numbers with today's date. 5. Report the new posts only. ``` ## Next steps - [Campaign creators](/docs/recipes/campaign-creators.md): Find the creators to follow in the first place. - [Discover](/docs/prism/discover.md): Every Discover parameter, including authors and the watermark. - [Batch calls](/docs/batch.md): Profiles and post numbers for many accounts in one call.