Docs menu

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. 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

Response fields
FieldTypeMeaning
balancefloatTotal balance, including upcoming renewal credits that are not yet effective.
permanentfloatPermanent credits from recharges and grants. They never expire.
expiringfloatSubscription credits. They are valid for 30 days from grant.
upcomingfloatCredited but not yet effective — the renewal queue, available from the next cycle.
next_expirydatetime | nullNearest expiry time among expiring credits, or null when none.
free_tier_creditsintegerFree credits per UTC calendar month, renewed on the first sign-in of each month.
unlimitedbooleantrue 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:

  • Billing — balance summary, recharge catalog, subscriptions and orders.
  • 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.