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.
/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. The same balance is available to MCP clients as the searchpipe_account_balance tool — see the MCP Server reference.
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 https://searchpipe.tech/v1/account/balance \n -H "Authorization: Bearer sp-YOUR_KEY"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 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);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"])
}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());
}
}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
| 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 page and in Limits & billing.
Dashboard billing & usage
Endpoints for transaction history and usage logs authenticate with your dashboard login (session), not an API key — use the console:
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; pollGET /v1/account/balanceto stay ahead of it. Recharges never expire; subscription credits are valid for 30 days.