Follow creators and hear when they post
Save the creators you found, follow them and watch a niche for new ones
There are two ways to keep a creator list fresh. Watch a niche, and the same search runs on a schedule and reports only creators it has not delivered before. Or follow the creators you already found, and hear when they post. Price either one free with dry_run first.
curl -X POST "https://www.socialcrawl.dev/v1/prism/creators" \
-H "x-api-key: sc_your_key_here" \
-H "Content-Type: application/json" \
-d '{"keywords": ["home espresso", "latte art"], "platforms": ["tiktok", "instagram"], "min_followers": 10000, "limit": 20, "schedule": {"every": "7d", "purpose": "creator", "max_credits_per_run": 300}, "dry_run": true}'Watch a niche for new creators
Send a search to POST /v1/prism/creators with schedule, and the same search runs again on a cadence and tells you only about creators it has not delivered before:
{
"keywords": ["home espresso", "latte art"],
"platforms": ["tiktok", "instagram"],
"min_followers": 10000,
"limit": 20,
"schedule": { "every": "7d", "purpose": "creator", "max_credits_per_run": 300 }
}schedule.everyis1h,6h,12h,1d,7dor30d, andschedule.purposeiscreator, which a creator schedule requires.schedule.max_credits_per_run(ormax_credits, not both with different values) caps each run;schedule.max_credits_per_monthcaps a calendar month,schedule.start_atdelays the first run andschedule.namelabels it.- Send it with
"dry_run": truefirst. It creates nothing and answers one run's estimate withdata.schedule: the first run's time, the caps, what a month costs (credits_per_month,recommended_max_credits_per_month) andprice_rule. Each run is billed at the price of the calls it makes, the same as sending the search yourself, with no premium for scheduling. A per-run cap below one run's estimate is a free 400max_credits_below_estimatenaming the cap you sent and the value to send. - Send the real POST with an
Idempotency-Key: a retry with the same key replays the first answer and creates nothing twice, and a different body under the same key is a 422IDEMPOTENCY_KEY_PAYLOAD_MISMATCH. The same search sent again as a schedule answers the existing schedule withdeduplicated: true; when you changed its cadence or a cap, nothing new is created,differsnames the changed fields, andnext_stepsays how to change the existing schedule (its caps through its resume link, or delete it and send the request again). - The first run starts at once and is the baseline: the answer is its run (
data.run) and the schedule (data.schedule), and its creators are read like any run's, atdata.schedule.links.runs_url(GET /v1/prism/creators/runs?schedule_id=<schedule_id>). It sends no event. - Each later run is the same creator search, with the same compiled
promptorcampaign(never compiled again) and the same filters and judging. A creator an earlier run of the schedule delivered is dropped before it is looked up, withdrop_reason: delivered_before(read them withstate=dropped), so a run spends itsmax_credits_per_runon new creators and delivers up tolimitof them. A run that delivers new creators sendsdiscover.new_accountswith their count, the first 100 ids and"product": "creators"in its data. Receive it by registeringPOST /v1/webhook-endpointswith{ "url": "https://example.com/hooks", "types": ["discover.new_accounts"] }, or pollGET /v1/events?types=discover.new_accounts&wait_s=25, then read the creators from the run the event names. - A scheduled run keeps its creators for
retention_days, 30 when you send none, and the schedule remembers what its runs delivered for as long as they are kept: a creator last delivered by a run that has expired can be delivered again as new. - A schedule is a discover schedule:
GET /v1/prism/discover/scheduleslists it, and itslinkspause, resume and delete it. A run still running or paused when the next is due skips that slot, and three skips in a row pause the schedule. A key holds at most 20 schedules that watch creators (creator schedules and follows together). scheduleis refused withhandlesorauthor_list_id: the creators you send never change, so their schedule would never report a new one. To hear when those creators post, follow them as below.
Follow creators and hear when they post
A run is one-off unless you send it with schedule (watch a niche for new creators). To repeat a search once, send it again (an identical request within 24 hours of completion returns the stored run free; after that it is a new run and bills like one). To hear when creators you already found post, follow them with the route below. A sentence that says "posts every week" compiles to min_posts_per_week=1, a filter on how often a creator posts, not a repeat; check it in data.request.compiled.
A creator run that delivered creators hands off to a follow, and nothing has to be typed again: its data.next carries next.save_url and next.follow.
- Save the creators:
POST /v1/prism/creators/runs/{run_id}/save(the run'snext.save_url) with{}saves every delivered creator, and{ "keys": ["tiktok:lafernandaai", "..."] }saves a subset of theaccount.keyvalues the run delivered. It is free and answers201withauthor_list_ids(one list per 10,000 creators; an account holds at most 500 live stored lists, each kept 30 days) andnext.follow. Send anIdempotency-Key: a retry with the same key replays the first answer and saves nothing twice. - Price the follow: POST
next.follow.bodyunchanged tonext.follow.dry_run_url. The body is a complete discover schedule that walks the saved creators' own feeds (author_list_id,"authors_match": "walk", theirplatforms,"schedule": { "every": "1d", "purpose": "creator" }), and itsmax_creditsis the cap of each scheduled run. The dry run creates nothing; it shows what one run and a month cost (data.schedule.credits_per_month,recommended_max_credits_per_month) anddata.schedule.price_rule: each run is billed at the price of the calls it makes, with no premium for scheduling. - Start it: POST the same body to
next.follow.url(POST /v1/prism/discover) with anIdempotency-Key, addingschedule.max_credits_per_monthfor a monthly cap.
Each run of a follow that finds new posts sends discover.new_rows with "product": "creators" in its data; next.follow.notify names the event, the event feed and the webhooks route. A run read's own next.follow lists the delivered creators inline, so it can be sent without saving first, for up to 1,000 creators. A run that delivered more than 1,000 offers next.save_url and no inline next.follow, and its next_step says to save first: the save answer's next.follow follows the saved list by author_list_id, up to 10,000 creators. A follow body that lists more than 1,000 creators inline is a free 400 that names the saved-list form.
The same follow by hand
Without save, the same follow is two calls on discover, both free to price first.
- Store the creators' account keys (
account.keyof each delivered creator, such astiktok:lafernandaai) as an author list:
{
"kind": "authors",
"authors": ["tiktok:lafernandaai", "instagram:<handle>", "..."]
}It answers 201 with author_list_id. A list holds 1 to 10,000 handles, is free, belongs to your account, and expires after 30 days.
- Send a discover schedule over that list. Add
"dry_run": truefirst: it creates nothing and showsdata.schedule.credits_per_monthandrecommended_max_credits_per_month.
{
"author_list_id": "<author_list_id>",
"authors_match": "walk",
"platforms": ["tiktok", "instagram"],
"period": "7d",
"schedule": {
"every": "1d",
"max_credits_per_run": 50,
"name": "Liked creators",
"purpose": "creator"
},
"dry_run": true
}authors_match: "walk"reads each creator's own feed in the window. A walk with nokeywordsand nocontexthas no subject to judge against, so it keeps every post it reads from the listed creators, unjudged (relevanceis null on each row); addkeywordsorcontextto keep only the posts about a subject.- Each run costs one page of each creator's feed per platform, at that feed's page price. The first run starts at once; each later run starts from the previous run's watermark and delivers only posts not delivered before. The shortest cadence is
1h; a key holds at most 20 schedules. - A creator on a platform missing from
platformsis not read and is named in_warnings.schedule.purposeis required with an author list. - The rows are the creators' posts as discover returns them, not creator-measured rows. To measure the creators themselves again, send the same keys as
handlestoPOST /v1/prism/creators.
Send the real POST with max_credits_per_month (the dry run recommends one) and an Idempotency-Key. A settled run that has new posts sends discover.new_rows with the count and the first 100 new ids. Receive it by registering POST /v1/webhook-endpoints with { "url": "https://example.com/hooks", "types": ["discover.new_rows"] }, or poll GET /v1/events?types=discover.new_rows&wait_s=25, then read the posts from the run (GET /v1/prism/discover/runs?schedule_id=<schedule_id>, then GET /v1/prism/discover/runs/{run_id}). The discover schedules section holds the pause, resume and caps.
Monitors (POST /v1/monitors with webhook_rows: "new") re-run one read of one account or post, so a list of 30 creators would be 30 monitors, over the Free (3) and Starter (10) limits; use the discover schedule for a list.
Which page is for you?
This page is the reference for watching and following. The follow creators cookbook is a worked run of the same job from start to finish, with the answers it got. Every event a follow sends is listed with the other webhook events.
