> ## Documentation Index
> Fetch the complete documentation index at: https://docs.geniusforms.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Pricing & Credits
> How API credit-based pricing works
# Pricing & Credits
GeniusForms uses a **credit-based pricing model** for AI operations. CRUD operations (listing forms, reading responses, managing fields) are always free and unlimited — only AI-powered endpoints consume credits.
## Plans
| Plan | Price | AI Credits/Month | Rate Limit (requests/day) |
| ----------- | ------- | ---------------- | ------------------------- |
| **Free** | \$0 | 50 | 1,000 |
| **Builder** | \$19/mo | 500 | 5,000 |
| **Scale** | \$49/mo | 2,500 | 10,000 |
No credit card required for the Free plan.
## Credit Costs
| Endpoint | Credits | Description |
| ------------------------------------ | ------- | ------------------------------------ |
| `POST /forms/generate` | **5** | AI form generation from a prompt |
| `POST /forms/:id/analytics/generate` | **3** | AI-powered analytics report |
| `POST /forms/:id/chat/:id/messages` | **1** | AI chat message about form responses |
| All other endpoints | **0** | CRUD operations — always free |
### What the Free Tier Gets You (50 credits/month)
* \~10 AI-generated forms (50 / 5 credits each)
* OR \~16 analytics reports (50 / 3)
* OR \~50 chat messages (50 / 1)
* OR any mix — plus **unlimited** CRUD operations
## Credit Headers
Every API response includes credit information in the headers:
```
X-Credits-Remaining: 45
X-Credits-Used: 5
X-Monthly-Allowance: 500
```
| Header | Description |
| --------------------- | --------------------------------------------------------- |
| `X-Credits-Remaining` | Credits left in your current billing cycle |
| `X-Credits-Used` | Credits consumed by this request (0 for non-AI endpoints) |
| `X-Monthly-Allowance` | Total monthly credit allowance for your plan |
Use these headers to track your balance without making extra API calls.
## Insufficient Credits (402)
When you don't have enough credits for an AI operation, the API returns a `402 Payment Required` response:
```json theme={null}
{
"error": "insufficient_credits",
"message": "This operation requires 5 credit(s) but you only have 3 remaining. Upgrade your plan for more credits.",
"creditsRemaining": 3,
"creditsRequired": 5,
"tier": "free",
"upgradeUrl": "/settings?tab=api"
}
```
Credits are only deducted when the operation succeeds validation. If you receive a 402, no credits were consumed.
## Rate Limits vs. Credits
Credits and rate limits are **separate systems**:
* **Rate limits** cap total requests per day (all endpoints). Exceeding returns `429 Too Many Requests`.
* **Credits** cap AI operations per month. Exceeding returns `402 Payment Required`.
A Free tier user can make 1,000 requests/day but only 50 AI operations/month. CRUD operations (listing forms, reading responses) never consume credits.
## Monthly Reset
Credits reset automatically on your billing cycle anniversary (30 days from your subscription start date). Unused credits do not roll over.
The reset happens lazily — on your first API call after the cycle ends, your balance is restored to your plan's full allowance.
## Checking Your Usage
### Via API
Use the `GET /usage` endpoint with your API key:
```bash theme={null}
curl https://geniusforms.ai/api/v1/usage \
-H "X-API-Key: YOUR_API_KEY"
```
```json theme={null}
{
"tier": "builder",
"creditsRemaining": 423,
"creditsMonthlyAllowance": 500,
"overageCreditsUsed": 0,
"rateLimitDaily": 5000,
"billingCycleStart": "2026-02-09T00:00:00Z",
"billingCycleEnd": "2026-03-11T00:00:00Z",
"daysRemaining": 14
}
```
### Via Dashboard
Navigate to **Settings → API Keys** in your [dashboard](https://geniusforms.ai/settings). The **Usage & Billing** section shows:
* Current plan and credit balance (with visual progress bar)
* Usage breakdown by endpoint (Form Generation, Analytics, Chat)
* Billing cycle dates
* Paginated usage history log
## Usage History
Retrieve a detailed log of credit consumption:
```bash theme={null}
curl "https://geniusforms.ai/api/v1/usage/history?limit=10&offset=0" \
-H "X-API-Key: YOUR_API_KEY"
```
```json theme={null}
{
"history": [
{
"id": 42,
"endpoint": "forms.generate",
"creditsConsumed": 5,
"formId": 208,
"formName": "Customer Survey",
"createdAt": "2026-02-09T14:30:00Z"
}
],
"total": 1,
"hasMore": false,
"limit": 10,
"offset": 0
}
```
| Query Parameter | Default | Description |
| --------------- | ------- | ------------------------- |
| `limit` | 50 | Results per page (1-100) |
| `offset` | 0 | Number of results to skip |
## Upgrading Your Plan
### From the Dashboard
1. Go to **Settings → API Keys**
2. Click the **Upgrade** button in the Usage & Billing section
3. Select **Builder** ($19/mo) or **Scale** ($49/mo)
4. Complete payment via Stripe Checkout
5. Credits and rate limits update immediately
### Managing Your Subscription
Paid plan users can manage their subscription (update payment method, cancel, view invoices) through the Stripe billing portal, accessible from the Settings page.
### Cancellation
When you cancel a paid plan:
* Your plan downgrades to **Free** at the end of the current billing period
* Credits reset to 50/month
* Rate limit returns to 1,000 requests/day
* All your forms and data remain intact
## Best Practices
Check `X-Credits-Remaining` on each response to track usage without extra API calls.
Listing forms, reading responses, and managing fields costs zero credits.
Check for `insufficient_credits` error and prompt users to upgrade or wait for monthly reset.
Store generated forms and analytics locally to avoid regenerating and spending credits.