Credits and caching

SocialTap is prepaid: you buy credits, and each successful request spends some of them. One balance covers every endpoint on every platform.

• Failed requests are free: errors cost 0 credits.
• Cache hits are free: responses served from the cache cost 0 credits.
• Credits never expire.
• One credit balance for every endpoint and platform.

How a request is charged

1. Reserve. Before calling the platform, SocialTap checks that your balance covers the endpoint's minimum price and sets that minimum aside, nothing more. If the balance is below the minimum, the request fails immediately with insufficient_credits.
2. Fetch. Endpoints try their sources cheapest first and stop at the first one that works. The source that produced the result is reported as meta.source (see sources). Right before a source that costs more than what is set aside (a price that grows with the size of the item), SocialTap sets aside more of your balance: the exact price when the size of the item is known in advance, otherwise as much as your balance allows, and it then processes only as much of the item as that pays for. A source your balance can't pay for is skipped.
3. Charge. The price of the result is charged and the rest released. If the result would cost more than your balance covers, the request fails with insufficient_credits instead and costs nothing. A failed request releases everything.

What you paid is in meta.credits_charged and in the x-credits-charged header. x-credits-remaining is your account balance right after this request was charged; other requests of yours still in flight may lower it further, so with requests in parallel treat it as an upper bound. Both headers are on every response to an authenticated request, errors included (with a charge of 0); a unauthorized response has neither.

Reservations

A request starts only if your balance covers the endpoint's minimum, and only that minimum is set aside when it starts. More is set aside just before costlier work, and only what that work needs. Requests running in parallel therefore don't each lock up the most they could cost: your balance has to cover their minimums, plus the actual price of whatever costlier work they reach.

Prices that grow with the size of the item have a ceiling, because items above a size limit are refused; that ceiling is the most one request can cost.

Prices

A price is either flat ("1 credit") or a base plus a per-unit amount, for sources whose cost grows with the size of the item; the unit is part of the price.

Sources

Packs

Caching

Every endpoint accepts these options:

With max_age=N, SocialTap may answer from a stored response that is at most N seconds old. Cached responses have meta.is_cached set to true and are free. Use it whenever slightly stale data is fine, for example when several of your users ask for the same item.