# Pricing (/docs/listening/pricing)

How a dry run computes a listener's monthly cost in credits and money, how to set its cap from a budget, and how listeners will be billed

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.

```bash title="cURL"
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:

```text title="Formula"
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:

```json title="Cap example"
{
  "keywords": ["Acme"],
  "platforms": ["reddit"],
  "schedule": { "every": "1h", "name": "Acme on Reddit", "max_credits_per_run": 2 }
}
```

| Field | October 2026, Starter list price |
| --- | --- |
| `credits_per_month` | 744 |
| `max_credits_per_slot` | 3 |
| `depth_range_credits_per_month[1]` | 2,232 |
| `money_per_month` | £13.39 |
| `recommended_max_credits_per_month` | 2,455 |

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](/docs/credits.md) 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.

- [Quickstart](/docs/listening/quickstart.md): Send a dry run and read the answer
- [Lanes](/docs/listening/lanes.md): Which lanes refund empty pages
- [Credits](/docs/credits.md): Packs and the price per credit