# Credits and billing

**1 credit** unlocks 1 store: a row in an app's list, or a store's full app stack; counts are free, re-pulls within **7 days** are free, and you pay only for stores found.

## What costs what

| Request | Credits |
| --- | --- |
| [`GET /v1/apps/{slug}/companies`](https://installgraph.com/docs/reference/list-app-companies.md) | 1 per store in the page |
| [`GET /v1/companies/{domain}`](https://installgraph.com/docs/reference/get-company.md) | 1 per store found; `include=history` adds 1 |
| [`GET /v1/events`](https://installgraph.com/docs/reference/list-events.md) | 1 per distinct store in the page |
| [`POST /v1/webhooks`](https://installgraph.com/docs/reference/create-webhook.md) | 10 per change delivered; creating, listing and testing are free ([Webhooks](https://installgraph.com/docs/webhooks.md)) |
| [`GET /v1/apps/{slug}/companies/count`](https://installgraph.com/docs/reference/count-app-companies.md) | Free |
| [`GET /v1/apps`](https://installgraph.com/docs/reference/list-apps.md), [`GET /v1/industries`](https://installgraph.com/docs/reference/list-industries.md), [`GET /v1/usage`](https://installgraph.com/docs/reference/get-usage.md), [`GET /v1/pricing`](https://installgraph.com/docs/reference/get-pricing.md) | Free |

[`GET /v1/pricing`](https://installgraph.com/docs/reference/get-pricing.md) returns this table as JSON, with no key.

## Rules

1. **Charged only for stores found.** An empty page or an error costs nothing.
2. **Re-pulls are free for 7 days.** The same store for the same kind of request (a row from the same app's list, a lookup, or history) is free again within 7 days; `meta.freeRepulls` counts them. Scans are weekly, so a re-pull inside that window returns the same data.
3. **Counts are free and unlimited**, so narrow a query before you pay for rows.
4. **Store lookups that miss** (`404`) are free up to 2 × your lookups that found a store in the last 30 days + 100, then cost 1 credit each.
5. **A page the balance cannot fully cover is cut** to the rows you can pay for; `pagination.nextCursor` resumes after the last one.
6. **Credits expire after 12 months.** Each credit expires 12 months after it was added, and the oldest are spent first. They are non-refundable and not transferable.

## Seeing what you spent

Every response carries:

| Header | Body | Meaning |
| --- | --- | --- |
| `X-Credits-Charged` | `meta.creditsUsed` | Credits this request cost |
| `X-Credits-Remaining` | `meta.creditsRemaining` | Balance afterwards (`null` for unlimited keys) |
| | `meta.freeRepulls` | Stores served free as re-pulls |

[`GET /v1/usage`](https://installgraph.com/docs/reference/get-usage.md) shows the balance and the last 30 days by endpoint.

## Packs

| Credits | Price | $ per 1,000 stores | Pack id (API) |
| ---: | ---: | ---: | --- |
| 500 | $50 | $100 | `starter` |
| 2,500 | $150 | $60 | `growth` |
| 10,000 | $400 | $40 | `pro` |
| 40,000 | $1,000 | $25 | `scale` |

A company email gets up to 50 free credits: 25 at sign-up, 25 when the email is verified (once per company domain). Webmail gets none. Buy on your [account page](https://installgraph.com/account) (Stripe Checkout). Auto top-up, off by default, rebuys a chosen pack on the saved card when the balance runs low. Full detail: [Pricing](https://installgraph.com/pricing).

## Limits

Per account per rolling 30 days: 40,000 distinct stores (`402 usage_cap_reached`) and $1,000 of purchases (`402 spend_cap_reached`). For more, [talk to us](https://installgraph.com/talk-to-us).

## Running out

A billed request the balance cannot cover answers `402 insufficient_credits` and charges nothing. The error carries `offers`, so a script or agent can act on it:

```json
{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this request (balance 0). Buy a credit pack, or turn on auto top-up.",
    "requestId": "6f1c2a9e-4b7d-4e2a-9c51-0d3b8e7f2a14",
    "balance": 0,
    "offers": {
      "pack": { "id": "starter", "name": "Starter", "priceUsd": 50, "credits": 500, "buyUrl": "https://installgraph.com/account?buy=starter" },
      "talkToUs": { "url": "https://installgraph.com/talk-to-us", "for": "More than $1,000 or 40,000 stores in 30 days, the full dataset, or a changes feed." },
      "pricing": "https://installgraph.com/pricing"
    }
  }
}
```

Either send a person to `offers.pack.buyUrl`, or, if the account owner has turned on agent purchases, buy with [`POST /v1/billing/purchase`](https://installgraph.com/docs/reference/agent-purchase.md).