> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.wealthatlas.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.wealthatlas.com/_mcp/server.

# Credits & Billing

The Partners API is metered by **Partner API credits**, split into **six
independent buckets** — one per product area:

| Bucket         | Endpoints that charge it                  |
| -------------- | ----------------------------------------- |
| `people`       | `GET /people/{id}`, `POST /people/batch`  |
| `enhancements` | `POST /enhancements`                      |
| `exports`      | `POST /exports`                           |
| `lists`        | `POST /lists/{id}/people`                 |
| `networks`     | `POST /networks/{id}/members/batch`       |
| `searches`     | `GET /search` and natural-language search |

Each endpoint charges **only its own bucket**. The buckets are **strictly
isolated**: running out of `searches` credits returns `402 Payment Required`
on search even if your `people` bucket still has a large balance, and vice
versa. There is no shared/fungible pool — credits never move between buckets.

## How charging works

* **Single-item endpoints** (e.g. `GET /people/{id}`, `GET /search`) cost **1 credit** per request, charged to that endpoint's bucket.
* **Bulk endpoints** (`POST /enhancements`, `POST /exports`, `POST /people/batch`, `POST /lists/{id}/people`, `POST /networks/{id}/members/batch`) cost **1 credit per item** in the request, charged to that endpoint's bucket. If you don't have enough credits in that bucket for the full batch, we process as many items as your bucket balance allows (partial processing).
* Credits are charged **upfront**, before the request runs.
* If the request fails with a **5xx** server error, the credit is
  **automatically refunded**.
* If the request fails with a **4xx** client error, the credit is also
  refunded.
* When your team has **no** credits left, the API returns
  `402 Payment Required` (see below).

## Free endpoints

The following endpoints never consume a credit:

**Utility**

* All health checks (e.g. `GET /people/health`, `GET /search/health`)
* `GET /docs`, `GET /redoc`, and `GET /openapi.json` — the API docs and spec
* `GET /test`
* `GET /credits` — the balance endpoint

**People**

* `GET /people/{id}/metadata` — single person metadata
* `POST /people/metadata/batch` — batch person metadata

**Enhancements**

* `POST /enhancements/results/batch` — get enhancement results
* `GET /enhancements/{id}/progress` — single enhancement progress
* `POST /enhancements/progress/batch` — batch enhancement progress

**Exports**

* `GET /exports` — list past exports

**Lists**

* `GET /lists` — list all lists
* `GET /lists/{id}` — get single list metadata
* `PATCH /lists/{id}` — rename a list
* `POST /lists/{id}/people/remove` — remove people from a list

**Networks**

* `GET /networks` — list all networks
* `PUT /networks/{id}` — rename a network
* `GET /networks/jobs/{job_id}` — check bulk add progress
* `POST /networks/{id}/members/remove` — remove members

## Checking your balance

Call the free `GET /credits` endpoint. It returns the available balance for
each of the six buckets:

```bash
curl https://api.wealthatlas.com/v1/partners/credits \
  -H "x-api-key: $WEALTHATLAS_API_KEY"
```

```json
{
  "people": 4200,
  "enhancements": 1000,
  "exports": 500,
  "lists": 300,
  "networks": 250,
  "searches": 800
}
```

* Each field is the credits remaining **in that bucket** right now.

## Need more credits?

When a bucket is empty, the endpoints that charge that bucket return
`402 Payment Required` — even if your other buckets still have a balance:

```json
{
  "error": "insufficient_partner_api_credits",
  "message": "Your team has run out of Partner API credits. Purchase more credits or wait until your next renewal. See https://developer.wealthatlas.com/credits for details.",
  "bucket": "searches",
  "available_credits": 0
}
```

The `bucket` field names the exhausted bucket so you know which product area
to top up.

To obtain more credits, email [team@wealthatlas.com](mailto:team@wealthatlas.com).