Pricing

Every dry run returns the listener's monthly cost at data.estimate, in credits and in money: the most a month can bill, and the typical month, which is usually less. The dry run itself costs 0 credits. This page shows how the estimate is computed, how to turn a budget into a cap, and how listeners will be billed once they ship in LRel2a.

curl -X POST "https://www.socialcrawl.dev/v1/listening/streams?dry_run=1" \
  -H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"keywords": ["Acme", "Acme Cloud"], "platforms": ["youtube", "reddit", "x", "news"], "schedule": {"every": "1h", "name": "Acme brand"}}'

How is the estimate computed?

A search term is searched once on every chosen lane, at every slot of the schedule. The typical month reads one page per search; the most a month can bill reads each lane's page cap on every search, with every check billed:

searches_per_slot                  = search terms × lanes
credits_per_month                  = search terms × slots_in_month × 1 page × price per page, summed over lanes
depth_range_credits_per_month      = [credits_per_month, the same sum at each lane's max_pages]
max_credits_per_slot               = search terms × max_pages × price per page, summed over lanes
recommended_max_credits_per_month  = ((slots in a 31-day month − 1) × max_credits_per_slot + max_credits_per_run) × 1.1, rounded up
money_per_month                    = depth_range_credits_per_month[1] × money_per_credit

max_credits_per_run is schedule.max_credits_per_run when you send it, else max_credits_per_slot. The recommended cap covers every slot of the longest month at one slot's maximum, with the last slot at your per-run cap, plus 10%.

For the request above in October 2026: "Acme" and "Acme Cloud" are 2 search terms on 4 lanes, so searches_per_slot is 8. October has 744 hourly slots, and each of these lanes costs 1 credit a page, so the typical month is 2 × 4 × 744 = 5,952 credits (credits_per_month), or 8 credits an hour. The page cap is 3 on YouTube, Reddit and X and 1 on Google News, so one slot costs at most 2 × (3 + 3 + 3 + 1) = 20 credits (max_credits_per_slot) and a month can bill at most 744 × 20 = 14,880 credits (depth_range_credits_per_month[1]). With no max_credits_per_run, the recommended cap is (743 × 20 + 20) × 1.1 = 16,368 credits.

A schedule.max_credits_per_run changes only the last slot of the recommendation. This listener watches one keyword on Reddit and caps each check at 2 credits:

{
  "keywords": ["Acme"],
  "platforms": ["reddit"],
  "schedule": { "every": "1h", "name": "Acme on Reddit", "max_credits_per_run": 2 }
}

The recommended cap is (743 × 3 + 2) × 1.1 = 2,454.1, rounded up to 2,455 credits.

Months are UTC calendar months, and slots_in_month counts every slot of the current month at the listener's every, so the figure is the same whichever day you ask. data.estimate.by_platform gives the same numbers per lane, and data.estimate.by_group per group; a search term two groups share is counted once.

What is a credit worth in money?

money_per_credit is the price of the account's active pack divided by its credits, with basis: "active_pack". An account that has never bought a pack sees the Starter list price, with basis: "starter_list". The amount is in GBP. money_per_month prices the most a month can bill: at the Starter list price of £0.006 a credit, the example's 14,880 credits are £89.28 a month. The typical month of 5,952 credits is about £35.71. See credits for the packs.

How do I set the cap from a budget?

schedule.max_credits_per_month is a cap in credits, and it is never exceeded once listeners run. There is no budget field. For a budget in money:

1. Convert the budget to GBP if it is in another currency, and tell the user which rate you used.
2. Divide it by money_per_credit and round down. A £20 budget at £0.006 a credit is 3,333 credits.
3. Never go below max_credits_per_slot, the cost of one full check. A cap below it answers budget_below_one_check with the smallest value that works in suggested_value.

Show the user money_per_month, money_per_credit and the cap, and get a yes before the listener is created. Every dry run's next_step states the money, the typical month, the recommended cap and this formula in one paragraph.

How will listeners be billed?

Listeners ship in LRel2a. Each page a check fetches is an API call made as the listener's key and billed like the same call made with that key yourself. On a newest-first lane, a page none of whose rows is new to the listener, or that has no rows, is refunded with the reason no_new_items; a page that brings at least one new row bills exactly as the same API call does, whether or not the judge keeps that row. Pages on top-results and time-window lanes are billed like the same call. The monthly cap counts net spend, after refunds.

Neither figure subtracts a refund. empty_pages_refunded in by_platform marks the lanes where an empty page is refunded, and next_step names them, for example: "Show the user up to £89.28 a month (14,880 credits if every search reads its lane's page cap), usually less: about 5,952 credits at one page a search, and pages that find nothing new on reddit/search and twitter/search/tweets are refunded (no_new_items)."

A dry run that includes X (twitter/search/tweets) or LinkedIn (linkedin/search/posts) carries this warning for each: "a share of scheduled checks is skipped, with nothing billed, when the only source that answers costs more than the check; that share is measured once listeners run." Neither figure subtracts those skips.

Three differences from discover, on purpose

• sponsored defaults to exclude on a listener: posts marked as ads or paid partnerships are dropped. Discover's default is keep. Send sponsored: "keep" to receive them.
• Judging is included in the price of each check, with no surcharge. Discover bills judging separately.
• A listener's spend (from LRel2a) carries month, credits_gross, credits_refunded and credits_net, because refunds make gross and net differ. A discover schedule's carries month and credits_spent.

Each dry run states the first two in warnings when they apply to the body you sent.