# Credits and caching

Get started

How requests are priced, reserved and charged, how to read what you paid, and how to get free cache hits.

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`](https://staging-fly.socialtap.dev/docs/errors/index.md#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`](https://staging-fly.socialtap.dev/docs/errors/index.md#insufficient_credits) instead and costs nothing. A failed request releases everything.

A request that succeeds after you hang up (a timeout, a closed connection) is still charged. Its result is cached: retry with `max_age` to get it as a free cache hit.

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`](https://staging-fly.socialtap.dev/docs/errors/index.md#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.

| Endpoint | Balance needed to start | Most one request can cost |
| --- | --- | --- |
| [Facebook Post API](https://staging-fly.socialtap.dev/docs/reference/facebook/post/index.md) | 1 credit | 1 credit |
| [Facebook Ad Library Search API](https://staging-fly.socialtap.dev/docs/reference/facebook/search_ads/index.md) | 1 credit | 1 credit |
| [Facebook Video Transcript API](https://staging-fly.socialtap.dev/docs/reference/facebook/transcript/index.md) | 1 credit | 122 credits |
| [Instagram Post API](https://staging-fly.socialtap.dev/docs/reference/instagram/post/index.md) | 1 credit | 1 credit |
| [Instagram Posts API](https://staging-fly.socialtap.dev/docs/reference/instagram/posts/index.md) | 1 credit | 1 credit |
| [Instagram Profile API](https://staging-fly.socialtap.dev/docs/reference/instagram/profile/index.md) | 1 credit | 1 credit |
| [Instagram Reels Transcript API](https://staging-fly.socialtap.dev/docs/reference/instagram/transcript/index.md) | 1 credit | 122 credits |
| [Rumble Comments API](https://staging-fly.socialtap.dev/docs/reference/rumble/comments/index.md) | 1 credit | 1 credit |
| [Rumble Video API](https://staging-fly.socialtap.dev/docs/reference/rumble/post/index.md) | 1 credit | 1 credit |
| [Rumble Channel Videos API](https://staging-fly.socialtap.dev/docs/reference/rumble/posts/index.md) | 1 credit | 1 credit |
| [Rumble Channel API](https://staging-fly.socialtap.dev/docs/reference/rumble/profile/index.md) | 1 credit | 1 credit |
| [Rumble Search API](https://staging-fly.socialtap.dev/docs/reference/rumble/search_posts/index.md) | 1 credit | 1 credit |
| [Rumble Transcript API](https://staging-fly.socialtap.dev/docs/reference/rumble/transcript/index.md) | 1 credit | 122 credits |
| [Threads Profile API](https://staging-fly.socialtap.dev/docs/reference/threads/profile/index.md) | 1 credit | 1 credit |
| [TikTok Comments API](https://staging-fly.socialtap.dev/docs/reference/tiktok/comments/index.md) | 1 credit | 1 credit |
| [TikTok Post API](https://staging-fly.socialtap.dev/docs/reference/tiktok/post/index.md) | 1 credit | 1 credit |
| [TikTok Posts API](https://staging-fly.socialtap.dev/docs/reference/tiktok/posts/index.md) | 1 credit | 1 credit |
| [TikTok Profile API](https://staging-fly.socialtap.dev/docs/reference/tiktok/profile/index.md) | 1 credit | 1 credit |
| [TikTok Transcript API](https://staging-fly.socialtap.dev/docs/reference/tiktok/transcript/index.md) | 1 credit | 122 credits |
| [YouTube Comments API](https://staging-fly.socialtap.dev/docs/reference/youtube/comments/index.md) | 1 credit | 1 credit |
| [YouTube Video API](https://staging-fly.socialtap.dev/docs/reference/youtube/post/index.md) | 1 credit | 1 credit |
| [YouTube Channel Videos API](https://staging-fly.socialtap.dev/docs/reference/youtube/posts/index.md) | 1 credit | 1 credit |
| [YouTube Channel API](https://staging-fly.socialtap.dev/docs/reference/youtube/profile/index.md) | 1 credit | 1 credit |
| [YouTube Transcript API](https://staging-fly.socialtap.dev/docs/reference/youtube/transcript/index.md) | 1 credit | 122 credits |

## 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.

| Endpoint | Source | Price per successful request | Per 1,000 requests |
| --- | --- | --- | --- |
| [Facebook Post API](https://staging-fly.socialtap.dev/apis/facebook/post/index.md) | Public page `page` | 1 credit | $0.75–$1.45 |
| [Facebook Ad Library Search API](https://staging-fly.socialtap.dev/apis/facebook/search_ads/index.md) | Platform API `api` | 1 credit | $0.75–$1.45 |
| [Facebook Video Transcript API](https://staging-fly.socialtap.dev/apis/facebook/transcript/index.md) | Captions `captions` | 1 credit | $0.75–$1.45 |
| [Facebook Video Transcript API](https://staging-fly.socialtap.dev/apis/facebook/transcript/index.md) | Speech-to-text `asr` | 2 credits + 2 per started minute of media<br>up to 122 credits (60 started minutes of media) | $1.50–$2.90 + $1.50–$2.90 per started minute of media |
| [Instagram Post API](https://staging-fly.socialtap.dev/apis/instagram/post/index.md) | Public page `page` | 1 credit | $0.75–$1.45 |
| [Instagram Posts API](https://staging-fly.socialtap.dev/apis/instagram/posts/index.md) | Any source | 1 credit | $0.75–$1.45 |
| [Instagram Profile API](https://staging-fly.socialtap.dev/apis/instagram/profile/index.md) | Public page `page` | 1 credit | $0.75–$1.45 |
| [Instagram Reels Transcript API](https://staging-fly.socialtap.dev/apis/instagram/transcript/index.md) | Captions `captions` | 1 credit | $0.75–$1.45 |
| [Instagram Reels Transcript API](https://staging-fly.socialtap.dev/apis/instagram/transcript/index.md) | Speech-to-text `asr` | 2 credits + 2 per started minute of media<br>up to 122 credits (60 started minutes of media) | $1.50–$2.90 + $1.50–$2.90 per started minute of media |
| [Rumble Comments API](https://staging-fly.socialtap.dev/apis/rumble/comments/index.md) | Platform API `api` | 1 credit | $0.75–$1.45 |
| [Rumble Video API](https://staging-fly.socialtap.dev/apis/rumble/post/index.md) | Public page `page` | 1 credit | $0.75–$1.45 |
| [Rumble Channel Videos API](https://staging-fly.socialtap.dev/apis/rumble/posts/index.md) | Any source | 1 credit | $0.75–$1.45 |
| [Rumble Channel API](https://staging-fly.socialtap.dev/apis/rumble/profile/index.md) | Public page `page` | 1 credit | $0.75–$1.45 |
| [Rumble Search API](https://staging-fly.socialtap.dev/apis/rumble/search_posts/index.md) | Public page `page` | 1 credit | $0.75–$1.45 |
| [Rumble Transcript API](https://staging-fly.socialtap.dev/apis/rumble/transcript/index.md) | Captions `captions` | 1 credit | $0.75–$1.45 |
| [Rumble Transcript API](https://staging-fly.socialtap.dev/apis/rumble/transcript/index.md) | Speech-to-text `asr` | 2 credits + 2 per started minute of media<br>up to 122 credits (60 started minutes of media) | $1.50–$2.90 + $1.50–$2.90 per started minute of media |
| [Threads Profile API](https://staging-fly.socialtap.dev/apis/threads/profile/index.md) | Platform API `api` | 1 credit | $0.75–$1.45 |
| [Threads Profile API](https://staging-fly.socialtap.dev/apis/threads/profile/index.md) | Public page `page` | 1 credit | $0.75–$1.45 |
| [TikTok Comments API](https://staging-fly.socialtap.dev/apis/tiktok/comments/index.md) | Platform API `api` | 1 credit | $0.75–$1.45 |
| [TikTok Post API](https://staging-fly.socialtap.dev/apis/tiktok/post/index.md) | Public page `page` | 1 credit | $0.75–$1.45 |
| [TikTok Posts API](https://staging-fly.socialtap.dev/apis/tiktok/posts/index.md) | Any source | 1 credit | $0.75–$1.45 |
| [TikTok Profile API](https://staging-fly.socialtap.dev/apis/tiktok/profile/index.md) | Public page `page` | 1 credit | $0.75–$1.45 |
| [TikTok Transcript API](https://staging-fly.socialtap.dev/apis/tiktok/transcript/index.md) | Captions `captions` | 1 credit | $0.75–$1.45 |
| [TikTok Transcript API](https://staging-fly.socialtap.dev/apis/tiktok/transcript/index.md) | Speech-to-text `asr` | 2 credits + 2 per started minute of media<br>up to 122 credits (60 started minutes of media) | $1.50–$2.90 + $1.50–$2.90 per started minute of media |
| [YouTube Comments API](https://staging-fly.socialtap.dev/apis/youtube/comments/index.md) | Platform API `api` | 1 credit | $0.75–$1.45 |
| [YouTube Video API](https://staging-fly.socialtap.dev/apis/youtube/post/index.md) | Platform API `api` | 1 credit | $0.75–$1.45 |
| [YouTube Video API](https://staging-fly.socialtap.dev/apis/youtube/post/index.md) | Public page `page` | 1 credit | $0.75–$1.45 |
| [YouTube Channel Videos API](https://staging-fly.socialtap.dev/apis/youtube/posts/index.md) | Any source | 1 credit | $0.75–$1.45 |
| [YouTube Channel API](https://staging-fly.socialtap.dev/apis/youtube/profile/index.md) | Any source | 1 credit | $0.75–$1.45 |
| [YouTube Transcript API](https://staging-fly.socialtap.dev/apis/youtube/transcript/index.md) | Captions `captions` | 1 credit | $0.75–$1.45 |
| [YouTube Transcript API](https://staging-fly.socialtap.dev/apis/youtube/transcript/index.md) | Speech-to-text `asr` | 2 credits + 2 per started minute of media<br>up to 122 credits (60 started minutes of media) | $1.50–$2.90 + $1.50–$2.90 per started minute of media |

### Sources

| meta.source | Source | What it means |
| --- | --- | --- |
| `captions` | Captions | The platform's own caption track (uploaded or auto-generated). |
| `asr` | Speech-to-text | Transcribed by SocialTap from the media's audio when the platform has no captions. |
| `api` | Platform API | The platform's public, logged-out API. |
| `page` | Public page | Data embedded in the platform's public web page. |

## Packs

| Credits | Price | Per 1,000 credits |
| --- | --- | --- |
| 20,000 | $29 | $1.45 |
| 80,000 | $99 | $1.24 |
| 400,000 | $399 | $1.00 |
| 2,000,000 | $1,499 | $0.75 |

Buy a pack in the [dashboard](https://staging-fly.socialtap.dev/dashboard/), or with `POST /v1/billing/checkout`: it answers a Stripe Checkout URL to open and pay; the credits are added when the payment completes. Read your balance with `GET /v1/account`.

## Caching

Every endpoint accepts these options:

| Parameter | Type | Description |
| --- | --- | --- |
| `max_age` | `integer`<br>min 0 | Accept a cached response up to this many seconds old. Cache hits cost 0 credits. Omit to always fetch fresh. The Cache-Control: max-age=N request header is equivalent; max_age wins when both are sent. |
| `fields` | `string` | Return only these fields of each item: comma-separated paths in the schema's notation (id,text,metrics.view_count,segments\[\].text; a parent path keeps the whole object). Unknown paths are rejected. Applied after the cache, so it changes neither the price nor cache hits; page and meta are always returned whole. |

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.

> [!TIP]
>
> Send `max_age` whenever slightly stale data is fine, for example when several of your users ask for the same item: every cache hit is free.

---

[HTML version](https://staging-fly.socialtap.dev/docs/credits/) · [Docs index for AI agents](https://staging-fly.socialtap.dev/llms.txt) · [All docs in one file](https://staging-fly.socialtap.dev/llms-full.txt)