SocialCrawl
EnginesFind creators

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
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.every is 1h, 6h, 12h, 1d, 7d or 30d, and schedule.purpose is creator, which a creator schedule requires. schedule.max_credits_per_run (or max_credits, not both with different values) caps each run; schedule.max_credits_per_month caps a calendar month, schedule.start_at delays the first run and schedule.name labels it.
  • Send it with "dry_run": true first. It creates nothing and answers one run's estimate with data.schedule: the first run's time, the caps, what a month costs (credits_per_month, recommended_max_credits_per_month) and price_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 400 max_credits_below_estimate naming 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 422 IDEMPOTENCY_KEY_PAYLOAD_MISMATCH. The same search sent again as a schedule answers the existing schedule with deduplicated: true; when you changed its cadence or a cap, nothing new is created, differs names the changed fields, and next_step says 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, at data.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 prompt or campaign (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, with drop_reason: delivered_before (read them with state=dropped), so a run spends its max_credits_per_run on new creators and delivers up to limit of them. A run that delivers new creators sends discover.new_accounts with their count, the first 100 ids and "product": "creators" in its data. Receive it by registering POST /v1/webhook-endpoints with { "url": "https://example.com/hooks", "types": ["discover.new_accounts"] }, or poll GET /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/schedules lists it, and its links pause, 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).
  • schedule is refused with handles or author_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.

  1. Save the creators: POST /v1/prism/creators/runs/{run_id}/save (the run's next.save_url) with {} saves every delivered creator, and { "keys": ["tiktok:lafernandaai", "..."] } saves a subset of the account.key values the run delivered. It is free and answers 201 with author_list_ids (one list per 10,000 creators; an account holds at most 500 live stored lists, each kept 30 days) and next.follow. Send an Idempotency-Key: a retry with the same key replays the first answer and saves nothing twice.
  2. Price the follow: POST next.follow.body unchanged to next.follow.dry_run_url. The body is a complete discover schedule that walks the saved creators' own feeds (author_list_id, "authors_match": "walk", their platforms, "schedule": { "every": "1d", "purpose": "creator" }), and its max_credits is 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) and data.schedule.price_rule: each run is billed at the price of the calls it makes, with no premium for scheduling.
  3. Start it: POST the same body to next.follow.url (POST /v1/prism/discover) with an Idempotency-Key, adding schedule.max_credits_per_month for 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.

  1. Store the creators' account keys (account.key of each delivered creator, such as tiktok:lafernandaai) as an author list:
POST /v1/prism/discover/inputs
{
  "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.

  1. Send a discover schedule over that list. Add "dry_run": true first: it creates nothing and shows data.schedule.credits_per_month and recommended_max_credits_per_month.
POST /v1/prism/discover
{
  "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 no keywords and no context has no subject to judge against, so it keeps every post it reads from the listed creators, unjudged (relevance is null on each row); add keywords or context to 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 platforms is not read and is named in _warnings. schedule.purpose is 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 handles to POST /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.

Next steps

On this page