Account API — Query Credits & Key Status

One authenticated POST returns your remaining credit balance, concurrent lane count, and the status of every API key under your account. Use it to build credit-aware agents, monitor usage, or gate requests before they hit your quota.

Typical Use Case

Check remaining credits before launching a batch job — stop early if the account is too low instead of hitting a billing error mid-run.

01

Call /api/user/key

Pass your API key as Bearer token. No body required.
02

Read data.remain

This is your current spendable credit balance.
03

Gate your batch job

If remain ≥ estimated_cost, proceed. Otherwise top up or reduce batch size.

Pre-flight credit check · Python pattern

import requests

API_KEY  = "YOUR_API_KEY"
HEADERS  = {"Authorization": f"Bearer {API_KEY}"}
KEY_URL  = "https://www.searchcans.com/api/user/key"

def get_remaining_credits() -> int:
    res = requests.post(KEY_URL, headers=HEADERS, json={})
    res.raise_for_status()
    return res.json()["data"]["remain"]

def run_batch(urls: list[str], cost_per_item: int = 2):
    needed = len(urls) * cost_per_item
    remain = get_remaining_credits()

    if remain < needed:
        raise RuntimeError(
            f"Insufficient credits: need {needed}, have {remain}"
        )

    print(f"Credits OK ({remain} remain). Starting batch…")
    # … your API calls here …

run_batch(my_url_list)

API Endpoint

POST https://www.searchcans.com/api/user/key

Authentication required. Pass your API key as a Bearer token and include Content-Type: application/json with an empty JSON body {} — both are required.

Code Examples

curl -X POST "https://www.searchcans.com/api/user/key" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

import requests

response = requests.post(
    "https://www.searchcans.com/api/user/key",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={}
)
data = response.json()["data"]
print("Credits remaining:", data["remain"])
print("Concurrent lanes:", data["concurrent"])

const response = await fetch("https://www.searchcans.com/api/user/key", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
const { data } = await response.json();
console.log("Credits remaining:", data.remain);
console.log("Concurrent lanes:", data.concurrent);

Example Response

remain concurrent permanentRemain

{
  "code": 0,
  "data": {
    "nickName": "demo_searchcans",
    "email": "demo@searchcans.com",
    "origin": 1,
    "faceUrl": "https://face.searchcans.com/png?seed=u_20608_6c464-7473-40u2-sthh-t28s21f1",
    "id": "u_20608_6c464-7473-40u2-sthh-t28s21f1",
    "type": 3,
    "lang": 2,
    "expire": 0,
    "token": "",
    "refreshToken": "",
    "keys": [
      {
        "uid": "u_20608_6c464-7473-40u2-sthh-t28s21f1",
        "name": "demo_key",
        "email": "demo@searchcans.com",
        "nickName": "demo_searchcans",
        "faceUrl": "https://face.searchcans.com/png?seed=u_20608_6c464-7473-40u2-sthh-t28s21f1",
        "key": "sk_••••••••••••••••••••••",
        "total": -1,
        "remain": 0,
        "type": 0,
        "id": "uk_2069983220161581056_9d613202-c6de-4f1f-a1c7-a64685b25551",
        "active": true
      }
    ],
    "key": "sk_••••••••••••••••••••••",
    "remain": 1098,
    "current": 2,
    "month": 2,
    "total": 2,
    "permanentRemain": 0,
    "permanentCurrent": 0,
    "permanentMonth": 0,
    "permanentTotal": 0,
    "seq": 3180,
    "concurrent": 1,
    "recommend": "RECOMMEND_ID"
  },
  "msg": "success",
  "requestId": null
}

Response Fields

Field	Type	Description
remain	integer	Credits remaining in your account (paid + free combined). Check this before batch jobs.
total	integer	Total credits ever allocated to your account.
current	integer	Credits consumed (all-time cumulative).
month	integer	Credits consumed in the current calendar month.
permanentRemain	integer	Non-expiring bonus credits remaining (from referrals or promotions). Consumed before paid credits.
concurrent	integer	Number of Parallel Lane slots — simultaneous requests without throttling.
keys	array	All API keys under this account, each with its own quota and status.
keys[].key	string	The API key string.
keys[].total	integer	Per-key credit quota. -1 = unlimited (draws from account pool).
keys[].remain	integer	Credits remaining on this specific key (only meaningful when total ≠ -1).
keys[].active	boolean	Whether this key is active and able to make requests.
keys[].name	string	Human-readable label for this key.
nickName	string	Account display name.
email	string	Account email address.
seq	integer	Internal account sequence number.

Understanding the Key Credit Fields

remain

Total usable credits right now. Poll this before large batch jobs to avoid mid-run quota failures.

permanentRemain

Non-expiring bonus credits (referrals, promotions). Consumed first, before paid credits.

concurrent

Parallel Lane slots — how many requests your account can run simultaneously without throttling.

keys[].total = −1

A quota of -1 means the sub-key has no individual cap — it shares the account credit pool.

Integrate Credit Checks into Your Agent Pipeline

Call this endpoint before launching large batch jobs to confirm sufficient credits. A remain value of 0 means the account is exhausted — requests will return a billing error until topped up.

Credits are deducted only on successful HTTP 200 responses. Timeouts, concurrency errors, and auth errors are never charged. See Error Codes for the full billing reference.

Get Your API Key

100 free credits on sign up — no credit card required.

Get Started Free Go to Dashboard