← Docs API Reference
Get an API key →
API ReferenceBalances and Usage

Account balances, usage, and earnings

Base URL: https://api.sogni.ai. These read endpoints accept an API key or session access token belonging to the account being queried:

curl --fail-with-body 'https://api.sogni.ai/v4/account/balance' \
  -H "Authorization: Bearer $SOGNI_API_KEY"

An API key is not a read-only credential: keep it on your server. These endpoints use the authenticated wallet, not an arbitrary address parameter. Do not put their responses in a shared/public cache. Missing or invalid credentials return 401; account restrictions may also prevent access.

#Generation-account balance

GET /v4/account/balance returns balances aggregated across Base and Etherlink. Use this for the account's generation balance; /v2/wallet/balance instead reports assets held directly by a public blockchain wallet.

The response is { "status": "success", "data": { ... } } with these fields:

Field Meaning and units
data.sogni.settled Settled generation-account SOGNI, decimal token string.
data.sogni.credit, .debit, .net Server-reported credits, debits, and net SOGNI balance, decimal token strings.
data.sogni.fastUnclaimed, .relaxedUnclaimed Unclaimed worker SOGNI earnings by network, decimal token strings.
data.spark.settled, .credit, .debit, .net Corresponding Spark balances, decimal token strings.
data.spark.fastUnclaimed, .relaxedUnclaimed Present in the common balance shape; currently returned as zero.
data.spark.premiumCredit Premium Spark credit, decimal token string. It is a classification of credit, not an extra amount to add to net.
data.USD.subscriptionUnclaimed Unclaimed subscription-pool earnings, decimal USD string, not Spark or SOGNI.

Token strings are human-unit decimals, not wei. Preserve precision with a decimal library rather than converting financial values to JavaScript Number. Use the returned net instead of reconstructing a balance from unrelated earnings buckets. A balance read is not a reservation or authorization to spend; concurrent jobs and pending settlement can change it. A failed subscription-claim lookup can return zero for the USD bucket while the other balances remain available.

#Subscription status

GET /v1/subscriptions/status returns data.subscription: the current entitlement snapshot, including active, status, plan information when applicable, period bounds, and cancellation-at-period-end state. Optional fields may describe payment-pending or user-actionable billing outcomes.

Treat active as the access indicator. A future cancellation does not itself mean current access has ended. An absent plan is represented by an inactive snapshot, not by a missing HTTP resource. Do not assume optional period or billing fields exist for every account.

#Usage and fair-use state

GET /v1/subscriptions/usage returns:

  • data.usage.periodRenderSpark and periodJobs: usage in the current billing cycle.
  • Optional data.usage.value.daily, .cycle, and .lifetime: delivered plan value, each containing renderSpark, retail-value renderUsd, and jobs. Daily/cycle entries also carry their window bounds and reset timestamps.
  • data.fairUse: the public fair-use state, or null. Use its percentages, reset times, and explicit flags such as fastRenderingPaused and relaxedUnrestricted; do not infer a private allowance from delivered value.
  • Optional promotional-credit information, which can be null.

Delivered value is not an account balance, an invoice, or remaining spendable credit. The daily plan-value window is anchored to the entitlement, not necessarily a calendar-day boundary.

GET /v1/subscriptions/usage/history?days=30 returns data.days and data.totals for the account's daily render activity across payment models. days defaults to 30 and is clamped to 7–90. Each daily row contains date, jobs, planJobs, planSpark, planUsd, sparkSpent, and paidSparkSpent. The date is a UTC calendar date, unlike the entitlement-anchored window above. UTC midnight is 5 PM PT on the preceding date during daylight time, or 4 PM PT during standard time. Missing activity is represented by zero-valued rows.

#Worker subscription-pool earnings

GET /v1/subscriptions/worker/earnings?months=3 reads the authenticated worker's earnings and claim state. It does not claim or transfer money. months defaults to 12 and is clamped to 1–24.

The response contains data.summary and data.months. Monthly entries can include yourRenderSpark, yourSharePct, estimatedPayoutUsd, claim, byWorker, and ledgerMissing. Open-month estimates may change. A finalized month with ledgerMissing: true does not promise a forthcoming payment.

Summary totalEstimatedUsd covers live estimates in the requested window; totalFinalizedUsd, totalUnclaimedUsd, and totalClaimedUsd describe all-time claim-ledger totals. Do not assume every summary field is limited by months. Monetary fields ending in Usd are dollar values. Fields ending in MicroUsdc use millionths of a dollar and can be integer strings.

Optional network=fast or network=relaxed requests a byNetwork breakdown; it does not filter the dollar totals, and that breakdown contains both lanes. Omit it or use network=all when you do not need the breakdown.

#Polling guidance

Refresh balances after relevant activity and at a moderate interval, such as 30–60 seconds. Usage and earnings do not need project-status polling frequency; prefer once per minute or on demand. Honor 429 and Retry-After, back off on temporary errors, and keep the last good value visibly marked as stale rather than showing a failed read as zero.

Public plan discovery is also available at GET /v1/subscriptions/plans. Use returned catalog values rather than hard-coding prices into an integration. See project status, worker analytics, and the on-chain wallet reference.