# Billing & Usage API

Check the remaining credit balance for an API key — total, permanent and expiring credits, queued renewals and the next expiry. Free to call: no credits charged, no usage logged. Transaction history and usage logs live in the dashboard.

**GET** `/v1/account/balance`

Habit prefix: GET /api/v1/account/balance is equivalent to /v1/account/balance — same handler, still free.

## Authorize

Authenticate with your sp- API key in the `Authorization: Bearer sp-YOUR_KEY` header; `X-API-Key: sp-YOUR_KEY` is also accepted. Create or rotate keys in [API Keys](https://searchpipe.tech/dashboard/api-keys). The same balance is available to MCP clients as the `searchpipe_account_balance` tool — see the [MCP Server reference](https://searchpipe.tech/docs/mcp).

## Request

`GET` with no parameters and no request body. The endpoint is read-only: it is never billed, never writes a usage log and does not consume rate-limit budget beyond ordinary request accounting — poll it freely for 402 prevention.

### Request example

**curl**

```
curl https://searchpipe.tech/v1/account/balance \n  -H "Authorization: Bearer sp-YOUR_KEY"
```

**Python**

```
import httpx

resp = httpx.get(
    "https://searchpipe.tech/v1/account/balance",
    headers={"Authorization": "Bearer sp-YOUR_KEY"},
    timeout=30,
)
data = resp.json()
print(data["balance"], data["permanent"], data["expiring"])
```

**Node.js**

```
// Node.js 18+: reads the API key from the SEARCHPIPE_API_KEY env var (falls back to the sp-YOUR_KEY placeholder when unset)
const resp = await fetch("https://searchpipe.tech/v1/account/balance", {
  headers: { Authorization: `Bearer ${process.env.SEARCHPIPE_API_KEY ?? "sp-YOUR_KEY"}` },
});
const data = await resp.json();
console.log(data.balance, data.permanent, data.expiring);
```

**Go**

```
package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"time"
)

func main() {
	req, _ := http.NewRequest("GET", "https://searchpipe.tech/v1/account/balance", nil)
	req.Header.Set("Authorization", "Bearer sp-YOUR_KEY")
	client := &http.Client{Timeout: 30 * time.Second}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	var data map[string]any
	if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
		panic(err)
	}
	fmt.Println(data["balance"], data["permanent"], data["expiring"])
}
```

**Java**

```
import java.net.URI;
import java.net.http.*;
import java.time.Duration;

public class SearchPipeBalance {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newBuilder()
            .version(HttpClient.Version.HTTP_1_1)
            .connectTimeout(Duration.ofSeconds(10))
            .build();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://searchpipe.tech/v1/account/balance"))
            .timeout(Duration.ofSeconds(30))
            .header("Authorization", "Bearer sp-YOUR_KEY")
            .GET()
            .build();
        HttpResponse<String> resp =
            client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(resp.body());
    }
}
```

**C# (.NET)**

```
using System.Net.Http.Json;
using System.Text.Json;

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", "sp-YOUR_KEY");

var data = await client.GetFromJsonAsync<JsonElement>("https://searchpipe.tech/v1/account/balance");
Console.WriteLine(data.GetProperty("balance"));
```

## Response

**Response fields**

| Field | Type | Meaning |
| --- | --- | --- |
| `balance` | float | Total balance, including upcoming renewal credits that are not yet effective. |
| `permanent` | float | Permanent credits from recharges and grants. They never expire. |
| `expiring` | float | Subscription credits. They are valid for 30 days from grant. |
| `upcoming` | float | Credited but not yet effective — the renewal queue, available from the next cycle. |
| `next_expiry` | datetime \| null | Nearest expiry time among expiring credits, or null when none. |
| `free_tier_credits` | integer | Free credits per UTC calendar month, renewed on the first sign-in of each month. |
| `unlimited` | boolean | true for admin/owner keys, which are not billed. |

```
{
  "balance": 1250.0,
  "permanent": 1000.0,
  "expiring": 250.0,
  "upcoming": 0.0,
  "next_expiry": "2026-12-15T00:00:00",
  "free_tier_credits": 1000,
  "unlimited": false
}
```

Illustrative example: 1,000 permanent credits plus 250 subscription credits expiring on 2026-12-15.

## Per-call usage

Every billed call reports its own cost, so balance checks are only needed for forecasting: the `X-SearchPipe-Credits` response header and `usage.credits_charged` in the JSON body state what a search, extract or verify call cost (`usage.cached` marks cache hits, which are still billed). Failed calls are refunded automatically. Search depth pricing — fast 0.5, basic 1, advanced 2 credits — is documented on the [Pricing](https://searchpipe.tech/pricing) page and in [Limits & billing](https://searchpipe.tech/docs#limits).

## Dashboard billing & usage

Endpoints for transaction history and usage logs authenticate with your dashboard login (session), not an API key — use the console:

- [Billing](https://searchpipe.tech/dashboard/billing) — balance summary, recharge catalog, subscriptions and orders.
- [Usage](https://searchpipe.tech/dashboard/usage) — per-query usage logs with credits, latency and status, credit batches and transaction history, daily or hourly aggregates, and CSV export.

## Errors

- `401` — missing or invalid API key. Balance checks are the cheapest way to distinguish an auth problem from an empty balance.
- `402` — this endpoint never returns 402, but search, extract and verify do once the balance is exhausted; poll `GET /v1/account/balance` to stay ahead of it. Recharges never expire; subscription credits are valid for 30 days.

## Related pages

[Pricing](https://searchpipe.tech/pricing)[Limits & billing](https://searchpipe.tech/docs#limits)[MCP Server reference](https://searchpipe.tech/docs/mcp)[Search API reference](https://searchpipe.tech/docs/search)[Docs home](https://searchpipe.tech/docs)
