# Follow and watch creators (/docs/prism/creators-follow) 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. ```bash title="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: ```json { "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`](/docs/idempotency.md): 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=`). 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](#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: ```json title="POST /v1/prism/discover/inputs" { "kind": "authors", "authors": ["tiktok:lafernandaai", "instagram:", "..."] } ``` 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. 2. 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`. ```json title="POST /v1/prism/discover" { "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=`, then `GET /v1/prism/discover/runs/{run_id}`). The [discover schedules](/docs/prism/discover-groups.md#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](/docs/recipes/follow-creators.md) 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](/docs/webhooks.md). ## Next steps - [Request fields](/docs/prism/creators.md): Every field, price and error of creator search. - [Follow creators cookbook](/docs/recipes/follow-creators.md): The same job as a worked run. - [Events feed](/docs/events.md): Read every event in order with a cursor.