Source: https://docs.sogni.ai/api-reference/account-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.

## [#](https://docs.sogni.ai/api-reference/account-and-usage/#account-identity)Account identity

`GET /v2/account/me` returns `data.walletAddress` (checksummed) and `data.username` for the credential's owner, plus `emailVerified`. Use it to find the wallet address an API key belongs to before calling the public [worker analytics](https://docs.sogni.ai/api-reference/worker-analytics/) or [on-chain wallet](https://docs.sogni.ai/api-reference/wallet/) reads. Additional account-settings fields may be present; do not depend on them.

## [#](https://docs.sogni.ai/api-reference/account-and-usage/#generation-account-balance)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.

## [#](https://docs.sogni.ai/api-reference/account-and-usage/#subscription-status)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.

`status` is one of `none`, `trialing`, `active`, `cancel_at_period_end`, `grace_period`, `past_due`, `expired`, or `canceled`. A cancelled plan that is still inside its paid period reports `cancel_at_period_end` with `active: true`; a renewal payment being retried reports `grace_period` with `active: false`.

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.

## [#](https://docs.sogni.ai/api-reference/account-and-usage/#usage-and-fair-use-state)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.

## [#](https://docs.sogni.ai/api-reference/account-and-usage/#worker-subscription-pool-earnings)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`, 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` adds two per-month breakdowns: `byNetwork` and `byWorker` (one row per Fast Worker NFT plus one row for relaxed or Mac work). It **does not filter the dollar totals**, and both breakdowns cover both lanes. Omit it or use `network=all` when you do not need them. `data.USD.subscriptionUnclaimed` on the balance counts only unclaimed claims, so it can differ from `totalUnclaimedUsd`, which also includes claims in progress or failed.

## [#](https://docs.sogni.ai/api-reference/account-and-usage/#polling-guidance)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. On `429`, stop and wait: exceeding a limit can block further requests for several minutes, and `Retry-After` may be absent or longer than the actual wait. 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](https://docs.sogni.ai/api-reference/project-status/), [worker analytics](https://docs.sogni.ai/api-reference/worker-analytics/), and the [on-chain wallet reference](https://docs.sogni.ai/api-reference/wallet/).