> For the complete documentation index, see [llms.txt](https://docs.pullbay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pullbay.com/documentation/plans-and-usage/credits.md).
# Credits
## Understanding the Credit-Based Billing Model
Credits are the currency of Pullbay. They represent a prepaid balance that you purchase and spend as you make API requests. When you make a successful API request, credits are deducted based on the data returned. This credit-based API billing model offers transparency, predictability, and flexibility—no surprise bills, no hidden fees, just pay for what you use.
Think of credits like a prepaid account:
1. You add credits to your account (one-time purchase, auto-reload, or plan allocation)
2. Each successful API request costs a certain number of credits
3. When your balance runs low, top up and continue using the API
### Why Credits?
**No surprise bills** — You know exactly what you're paying before making requests.\
**Predictable costs** — The same request always costs the same number of credits.\
**Scale as needed** — Use more data? Purchase more credits. Use less? Your unused credits remain valid.\
**Flexible spending** — Pay only for successful requests. No charges for failed requests.
***
## How Credit Consumption Works
Credits are consumed based on the **amount and complexity of data returned** from a successful API request, not the number of requests made.
### Credit Consumption Rules
| Scenario | Credit Cost |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Successful request with data** | Based on data volume and complexity. Typically 1 credit per "unit" of data (e.g., 1 credit per page of reviews). |
| **Failed request (4xx/5xx)** | **0 credits** — No charge for errors. |
| **Partial success** | **Only charged for returned data** — If you request 100 reviews but only 50 return, you pay for 50. |
| **Empty result set** | **Minimum charge applies** — Usually 1 credit (we still processed your request). |
| **Rate limit exceeded (429)** | **0 credits** — No charge when you hit your plan's rate limit. |
### How Consumption Is Calculated
Credit cost varies by endpoint and is determined by:
1. **Data Volume** — The number of items returned (reviews, ratings, listings, etc.)
2. **Data Complexity** — How much processing is required to extract and normalize the data
3. **Source Difficulty** — Some sources require more intensive resource usage than others
For example, the **Apple App Store reviews endpoint** typically consumes:
* **1 credit** per request for a single page of \~10 reviews
* **3 credits** to fetch 3 pages of reviews automatically
### Example: Fetching App Store Reviews
Let's say you're building a competitive intelligence tool and need to monitor competitor reviews daily.
**Scenario:** You fetch reviews for 5 different apps, requesting the latest 50 reviews per app.
```
App 1: Fetch 50 reviews = 5 credits (1 page = 1 credit, 5 pages of 10 = 5 credits)
App 2: Fetch 50 reviews = 5 credits
App 3: Fetch 50 reviews = 5 credits
App 4: Fetch 50 reviews = 5 credits
App 5: Fetch 50 reviews = 5 credits
───────────────────────
Total daily cost: 25 credits (per day)
Monthly cost: 25 × 30 = 750 credits
```
This is a very modest credit usage — well within the monthly allocation of any paid plan.
***
## Credit Balance & Account Management
### Viewing Your Credit Balance
Your current credit balance is displayed in:
* Dashboard home page
* API response headers (`X-Credits-Remaining`)
* Billing section with historical usage
### Credit Expiration & Validity
**Plan credits** — Renew each billing cycle. Any unused credits expire at the end of the month.\
**One-time top-up credits** — Never expire. They remain in your account indefinitely.\
**Free tier credits** — Non-renewing. Once exhausted, you must upgrade to a paid plan.
### Low Credit Warnings
When your balance falls below 10% of your plan's allocation, Pullbay sends email warnings. When balance reaches 0, requests are rejected with a `402 Payment Required` status code until you add more credits.
***
## Adding Credits to Your Account
There are three ways to add credits:
{% stepper %}
{% step %}
### One-Time Top-Up
Purchase additional credits on-demand without upgrading your plan.
* Available in your dashboard under **Billing → Add Credits**
* Minimum: 1,000 credits
* Credits never expire
* Useful for temporary spikes in usage
{% endstep %}
{% step %}
### Auto-Reload
Enable automatic credit replenishment when your balance falls below a threshold.
* Set a minimum credit threshold (e.g., "auto-reload when I reach 2,000 credits")
* Define a reload amount (e.g., "add 10,000 credits")
* Prevents service interruption
* Can be disabled anytime
{% endstep %}
{% step %}
### Plan Credits
Each paid plan includes a monthly credit allocation that renews automatically.
Each paid plan includes a monthly credit allocation — see the [Plans guide](broken://pages/d42df7cbba9fd5a924ac96071d54aa509c4e2cf5) or your [dashboard](https://app.pullbay.com/) for specific amounts and pricing.
* **Free plan**: A one-time allocation (non-renewing)
* **Paid plans**: Monthly allocation that renews each billing cycle
Upgrade or downgrade your plan anytime. Changes take effect immediately.
{% endstep %}
{% endstepper %}
***
## Credit Costs by Endpoint
Different endpoints consume different amounts of credits based on data complexity and volume.
### Apple App Store Service
| Endpoint | Credit Cost | Notes |
| -------------------------- | -------------------------------- | ------------------------------------------------------- |
| `/app-store/reviews` | 1 credit per page (\~10 reviews) | Paginated endpoint. Use standard or managed pagination. |
| `/app-store/ratings` | 1 credit per request | Returns app rating summary data. |
| `/app-store/metadata` | 1 credit per request | Returns app title, category, version, etc. |
| `/app-store/pricing` | 1 credit per request | Returns current and historical pricing. |
| `/app-store/release-notes` | 1 credit per version | Costs scale with number of releases returned. |
### Example Calculations
**Scenario 1: Fetch single page of reviews**
```
GET /v1/app-store/reviews?app_id=12345&limit=10
Cost: 1 credit
```
**Scenario 2: Fetch all reviews automatically**
```
GET /v1/app-store/reviews/all?app_id=12345
Cost: ~30-50 credits (depends on total reviews for the app)
```
**Scenario 3: Fetch app ratings and metadata**
```
GET /v1/app-store/ratings?app_id=12345 → 1 credit
GET /v1/app-store/metadata?app_id=12345 → 1 credit
Total: 2 credits
```
***
## Monitoring Credit Usage
### API Response Headers
Every successful API response includes credit information:
```
HTTP/1.1 200 OK
X-Credits-Used: 1
X-Credits-Remaining: 9,999
X-Credits-Limit: 10,000
```
### Usage Dashboard
The Pullbay dashboard displays:
* **Real-time credit balance**
* **Historical usage graph** (daily/weekly/monthly)
* **Cost breakdown by endpoint**
* **Projected monthly spend** (based on current usage)
* **Usage alerts** (when approaching plan limit)
### Billing API
Query your credit usage programmatically:
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://api.pullbay.com/v1/billing/usage?period=month
```
Response:
```json
{
"period": "month",
"start_date": "2026-04-01",
"end_date": "2026-04-13",
"credits_used": 1,247,
"credits_remaining": 8,753,
"endpoints": {
"app-store/reviews": 1200,
"app-store/ratings": 47
}
}
```
***
## Tips for Optimizing Credit Usage
### 1. Use Pagination Wisely
Standard pagination (`limit`, `offset`) gives you control but costs more. Use it when you need partial data.
```bash
# Costs 1 credit (fetch 10 items)
GET /v1/app-store/reviews?app_id=123&limit=10
# Costs more but fetches everything automatically
GET /v1/app-store/reviews/all?app_id=123
```
### 2. Batch Requests
Combine multiple smaller requests into fewer larger ones when possible.
### 3. Cache Results Locally
Store API responses in your database. Don't re-request data you already have.
```python
# Good: Cache results
if reviews_in_db_are_fresh():
use_cached_reviews()
else:
new_reviews = fetch_from_pullbay() # Uses credits
update_cache(new_reviews)
```
### 4. Set Up Auto-Reload
Enable auto-reload to prevent service interruptions without overspending.
### 5. Monitor Usage Trends
Check your dashboard weekly. If usage is higher than expected, adjust your request frequency.
***
## Frequently Asked Questions
Are credits refunded for failed requests?
No. Failed requests (4xx/5xx errors) do not consume credits. Only successful requests that return data consume credits. This protects you from unexpected charges due to API errors or issues on our side.
However, if a request partially succeeds (some data returned), you're charged only for the data that was successfully returned.
Do credits expire?
**Plan credits** expire at the end of each billing cycle. Unused monthly credits do not roll over.
**One-time top-up credits** never expire. Once purchased, they remain in your account indefinitely until spent.
**Free tier credits** (100 credits on the Free plan) are non-renewing and expire if you downgrade or close your account.
Can I set a credit spending limit?
Not directly, but you can:
1. **Set up auto-reload** with a high threshold to get warnings when approaching limits
2. **Downgrade to a lower plan** to reduce your monthly credit allocation
3. **Contact support** to request a custom spending cap (enterprise plans only)
What happens if I run out of credits?
When your balance reaches 0, all API requests return a `402 Payment Required` status code with the message "Insufficient credits."
To resume service, you must:
1. Add credits via one-time top-up
2. Upgrade to a paid plan
3. Wait for your next billing cycle (if on a paid plan with auto-renew)
Can I get a credit refund?
Refunds are not provided for spent credits. However:
* **Unused plan credits** expire at the end of the billing cycle
* **One-time top-up credits** can be transferred to another account (contact support)
* **Service-level credits** may be issued if we experience extended downtime (SLA violations)
How are credits charged if I use the API at 11:50 PM and my plan renews at midnight?
Credits are deducted from your current balance immediately upon request, regardless of billing cycle timing. Your plan credits renew at the exact time specified in your billing settings (usually midnight in your timezone).
Example:
* Current balance: 500 credits
* One request costs 100 credits
* At 11:50 PM: Balance becomes 400 credits
* At midnight: Plan renews, balance becomes 400 + 10,000 = 10,400 credits
Can I pause my plan and keep my credits?
No. Downgrading or canceling your plan removes active plan credits. However:
* One-time top-up credits remain in your account
* You can re-activate your plan anytime to resume plan credit allocation
* Contact support for account suspension options
What if my usage is inconsistent?
That's fine. Use the **Free plan** for testing, upgrade to **Starter** for development, and scale to **Growth** or **Scale** as you grow. You can change plans anytime, and changes take effect immediately.
Auto-reload is helpful for unpredictable usage patterns.
How do I know the cost before making a request?
Most endpoints publish their credit costs in the API documentation. You can also:
1. Check the **Costs by Endpoint** section in the [API Reference](broken://pages/cfff7c6859021edc5e8bd10c718b4d3c17f9a784)
2. Make a test request on the Free plan and check the `X-Credits-Used` response header
3. Use the [pricing calculator](https://pullbay.com/pricing) on the website
Can I see a detailed billing breakdown?
Yes. The **Billing** section of your dashboard shows:
* Daily credit consumption
* Usage by endpoint
* Projected monthly spend
* Historical cost trends
* Invoice history (for paid plans)
***
## Next Steps
* [View All Plans](broken://pages/d5482620747d408b41ca754dc15117b11d1adb89) — Compare plan credits and limits
* [API Reference](broken://pages/cfff7c6859021edc5e8bd10c718b4d3c17f9a784) — See credit costs for each endpoint
* [Billing Settings](broken://pages/0935f56a04a9447661004315d69fefde744a56cd) — Manage your credits in the dashboard
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.pullbay.com/documentation/plans-and-usage/credits.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.