# Credits and billing

URL: https://serpel.app/docs/credits-and-billing

Updated: 2026-11-05

Serpel bills by credits: one credit is €0.01, and only paid checks use them: rank checks, AI checks, keyword research and site audit crawls. Reading your data, syncs, reports and opportunities are free. A plan adds monthly credits and higher limits, and you can top up credits at any time.

- **€0.01** per credit: Taxes are included in every price.
- **100** welcome credits: When your email address is confirmed.
- **€5** smallest top-up: 500 credits, no subscription needed.
- **0** credits to read data: Dashboard, CLI, API and MCP.

## How do Serpel credits work?

Every workspace has one credit balance. Credits pay for the work Serpel buys from data providers: live Google results for [rank tracking](https://serpel.app/docs/rank-tracking), ChatGPT answers and Google AI Overviews for [AI visibility](https://serpel.app/docs/ai-visibility), keyword data for [keyword research](https://serpel.app/docs/keyword-research) and pages fetched by the [site audit](https://serpel.app/docs/site-audit) crawler. Everything else, including reading the results again, costs nothing.

Paid operations in a project use the balance of the workspace that owns the project. The same prices apply in the dashboard, the [CLI](https://serpel.app/docs/cli), the [REST API](https://serpel.app/docs/api) and over MCP.

## Which operations use credits?

These are all operations that use credits. The prices come from the same price list that books every charge.

> **Search volume comes with rank checks:** The project setting **Add search volume automatically** is on by default. Rank checks and monitoring runs then also fetch search volume for keywords that have none yet or whose data is older than 30 days, as the operation “Search volume” in the table. Switch the setting off in the project settings if you don’t need it.

| Operation | Unit | Credits |
| --- | --- | --- |
| Rank check right now, up to top 50 | per keyword | 5 |
| Rank check right now, top 100 | per keyword | 9 |
| Scheduled rank check, up to top 50 | per keyword | 2 |
| Scheduled rank check, top 100 | per keyword | 3 |
| AI prompt in ChatGPT | per prompt | 2 |
| Google AI Overview for a prompt | per prompt, only if the project checks AI Overviews | 2 |
| Keyword research for a seed keyword | per run, plus per started block of 50 results | 8 + 4 |
| Keyword research for a domain | per run, plus per started block of 50 results | 4 + 2 |
| List research, list refresh and “Search volume” | per request of up to 700 keywords, plus per started block of 50 keywords | 4 + 2 |
| Site audit crawl | per started block of 20 pages | 1 |
| Monitoring run | the rank checks, AI checks and search volume it runs | sum of all three |

A scheduled rank check waits in the provider’s queue, which is why it costs less than a check right now. A monitoring run started by its schedule uses the scheduled price, a run you start by hand uses the price for right now. The [monitoring guide](https://serpel.app/docs/monitoring-and-reports) explains schedules in detail.

> **Cached results cost the same:** Serpel charges per delivered result. When a result comes from a recent cache instead of a fresh provider call, it still counts as delivered and costs the same. Results that never arrive cost nothing.

## What does a typical month cost?

A few examples, calculated with the current price list. The project settings show the same kind of forecast for your own schedule before you save it.

| Example | Credits | Euro |
| --- | --- | --- |
| 50 keywords, top 50, checked weekly | 100 per run, about 429 a month | about €4.29 a month |
| The same 50 keywords checked right now | 250 | €2.50 |
| 10 AI prompts with Google AI Overviews | 40 per run | €0.40 |
| Search volume for the same 50 keywords, at most once every 30 days | 6 | €0.06 |
| A crawl of 250 pages | 13 | €0.13 |
| Keyword research with 100 results | 16 | €0.16 |

Check any price before you run something with `serpel billing estimate` or `POST /billing/estimate`. An estimate books nothing.

```bash
serpel billing estimate --operation rankCheck --keywords 50 --depth 50 --scheduled
serpel billing estimate --operation crawl --max-pages 250
```

## How is a paid operation charged?

**From estimate to charge**

1. **Estimate** (maximum): Serpel calculates the highest possible price. The dashboard shows it before you start.
2. **Reserve**: The maximum is blocked on your balance. If it doesn’t fit, nothing starts.
3. **Deliver**: Each result that arrives, such as a ranking or a crawled page block, is recorded once.
4. **Settle** (never more): Only what was delivered is charged. The rest of the reservation is released.

You are never charged more than the reserved maximum. Rank checks, AI checks and crawls charge per delivered item: if a provider fails for some keywords, those keywords cost nothing. Keyword research costs its fixed price once the research succeeds. A crawl reserves credits for the page limit of the project and charges only the pages it actually fetched. A reservation left behind by a failed job is released automatically after 30 minutes.

The **Balance** section under **Settings → Billing** shows what is available, the booked balance, what is reserved by running operations and how long your credits last at the current pace. **Settings → Usage** breaks down the last 30 days by feature, by project and by day. In the CLI, `serpel billing balance` shows the same numbers and `serpel billing history` lists the transactions.

## Which plans are there?

You can use Serpel without a subscription and pay only for the credits you buy. A subscription adds monthly credits and raises the limits. The current prices are on the [pricing page](https://serpel.app/pricing).

|  | Free (“No subscription” in the dashboard) | Starter | Pro |
| --- | --- | --- | --- |
| Price per month | €0 | €19 | €49 |
| Credits every month | none | 2,000 | 6,000 |
| Projects | 1 | 5 | 20 |
| Tracked keywords per project | 50 | 200 | 500 |
| AI prompts per project | 10 | 25 | 50 |
| Pages per crawl | 250 | 1,000 | 1,000 |
| Daily monitoring | No | No | Yes |
| AI apps may spend credits over MCP | No | Yes | Yes |

**Monthly credits and purchased credits**

- **Monthly credits** (from a plan): Added when the invoice of each period is paid. Used first, before any other credits. What is left expires when the next period starts or the subscription ends.
- **Purchased, welcome and promo credits** (never expire): Used once the monthly credits are gone. Stay on your balance with or without a subscription. Welcome and promo credits have no cash value.

## How do you subscribe, upgrade or downgrade?

1. **Pick a plan.** Open **Settings → Billing** and choose a plan under **Plans**. Payment runs on a Stripe Checkout page. Before every checkout you confirm that Serpel may start right away, which ends your right of withdrawal once the service has been fully provided.

2. **Change the plan later.** An upgrade takes effect immediately and starts a new billing period with the new monthly credits. It is charged in full from the day you switch, without a credit for the unused time, and the unused part of your current monthly credits stays on your balance. A smaller plan starts with the next period.

3. **Manage payment details and invoices.** The plan card links to the Stripe customer portal, where you update the payment method and download invoices. `serpel billing portal` opens the same portal.

```bash
serpel billing plan
serpel billing subscribe --plan starter --start-now
serpel billing change-plan --plan pro
```

Only the owner of a workspace can buy credits, start or change a subscription and redeem promo codes. Tokens and the CLI need the `billing:write` scope for these actions and `billing:read` to see the balance.

## How do you top up credits?

Top-ups are one-time payments through Stripe and work with or without a subscription. Choose a package under **Settings → Billing → Top up credits**:

| Package | Price incl. taxes |
| --- | --- |
| 500 credits | €5 |
| 1,000 credits | €10 |
| 2,500 credits | €25 |
| 5,000 credits | €50 |

With the CLI or the API you can also pay a custom amount between €5 and €1,000, where one cent buys one credit. The CLI flag `--amount` takes cents, so `--amount 1500` is €15 and buys 1,500 credits. The API field is `amountCents`.

```bash
serpel billing top-up --package credits1000 --start-now
serpel billing top-up --amount 1500 --start-now --no-open
```

## What happens when credits or limits run out?

**Out of credits or over a plan limit**

- **Not enough credits** (nothing is charged): Keyword research and list refresh are refused at once with HTTP 402 `insufficient_credits`. The CLI exits with code 6. A crawl, rank check, AI check or monitoring run you start by hand is queued, then fails when it starts. It shows as failed under **History** and costs nothing. A scheduled run is skipped and the schedule pauses. The workspace owner gets one email. After a top-up the run is due again.
- **Over a plan limit** (HTTP 403): Adding more projects, keywords or prompts than the plan allows fails with `plan_limit`. Checks you start by hand in a project over the limit are refused with `plan_limit`, and its schedules pause without an email. Nothing is deleted. Upgrade or remove items and everything runs again.

Each workspace also has a daily spending limit of 2,000 credits by default, counted across finished charges and open reservations for each day in UTC. Keyword research that would cross it is refused with HTTP 429 and `budget_exceeded`, and a queued job fails when it starts. `serpel billing balance` shows how much of today’s limit is used.

## Can AI agents spend your credits?

Only if you allow it. Over MCP, the tool `research_keywords` is the only one that uses credits. It runs only on Starter or Pro, after the workspace owner switches on **Agents and AI apps** under **Settings → Billing**, and within a daily agent limit of 500 credits by default (adjustable up to 100,000). A single call costs at most 50 credits. The [Claude Code guide](https://serpel.app/docs/mcp/claude-code) covers the details.

```bash
serpel agents allow --daily-limit 200
serpel agents status
```

## How do you redeem a promo code?

Enter the code under **Settings → Billing → Promo code**, or sign up through a link of the form `https://serpel.app/signup?code=YOURCODE` and the credits arrive when you confirm your email address. Codes use capital letters, digits and hyphens. Each promotion can be redeemed once per account, promo credits never expire and have no cash value. To stop guessing, a wrong code always gets the same message and attempts are rate-limited.

## How do you cancel a subscription?

Open **Settings → Billing** and follow the link “Verträge hier kündigen” on the plan card, or go straight to the [cancellation page](https://serpel.app/cancel). The German labels are required by German consumer law. The cancellation takes effect at the end of the current billing period and you get a confirmation email. Until then nothing changes. `serpel billing cancel` does the same from the command line, and `serpel billing resume` withdraws the cancellation before the period ends.

When the subscription ends, the remaining monthly credits expire, purchased and promo credits stay, and the limits of the free plan apply. Projects, keywords and prompts above those limits stay where they are. Their schedules pause and new checks are refused with `plan_limit` until you upgrade or remove items.

## Which API endpoints handle billing?

The billing endpoints of the [REST API](https://serpel.app/docs/api) mirror the dashboard. A summary of the balance, a price estimate and the transaction list need `billing:read`.

```bash
curl https://serpel.app/api/v1/billing/summary \
  -H "Authorization: Bearer $SERPEL_TOKEN"

curl -X POST https://serpel.app/api/v1/billing/estimate \
  -H "Authorization: Bearer $SERPEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"operation":"crawl","params":{"maxPages":250}}'
```

## Where to go next

- [Monitoring and reports](https://serpel.app/docs/monitoring-and-reports): Plan schedules and keep an eye on the monthly forecast.
- [Account and access](https://serpel.app/docs/account): Tokens, connected apps, data export and account deletion.
- [Troubleshooting](https://serpel.app/docs/troubleshooting): What to do about HTTP 402, paused schedules and limits.
- [Pricing](https://serpel.app/pricing): Plans and top-ups at a glance.