`synth_ai.research.account`

client.research.account — org account, billing, usage, and BYOK reads. These backend routes live under /api/v1 (and /api/members), not under /smr, so this namespace calls them through the session client’s internal _request_json layer, which applies the same base URL and Authorization: Bearer <api_key> header as every other SDK call. Mutations are limited to BYOK key management and subscription.cancel.

Classes

`AccountBalance`

Typed BalanceResponse (org_id, balance_cents, balance_dollars). Methods:

`from_wire`

from_wire(cls, payload: object) -> AccountBalance

`AccountTierLimits`

Typed TierLimitsResponse (tier name plus its limits payload). Methods:

`from_wire`

from_wire(cls, payload: object) -> AccountTierLimits

`AccountByokStatus`

Typed BYOK status (byok_enabled, plan_type, provider key coverage). Methods:

`from_wire`

from_wire(cls, payload: object) -> AccountByokStatus

`AccountReadinessCta`

Typed AccountReadinessCta (call-to-action for a failing check). Methods:

`from_wire`

from_wire(cls, payload: object) -> AccountReadinessCta

`AccountReadinessCheck`

Typed AccountReadinessCheck (one readiness gate with optional CTA). Methods:

`from_wire`

from_wire(cls, payload: object) -> AccountReadinessCheck

`AccountReadiness`

Typed AccountReadinessResponse (org-level launch readiness with CTAs). Methods:

`from_wire`

from_wire(cls, payload: object) -> AccountReadiness

`AccountIdentity`

Typed MeResponse (org and user resolution for the API key). Methods:

`from_wire`

from_wire(cls, payload: object) -> AccountIdentity

`ResearchAccountBalanceAPI`

Org credit balance and usage summary. Methods:

`get`

get(self) -> AccountBalance

Read the current credit balance. Backend route: GET /api/v1/balance/current.

`usage`

usage(self) -> dict[str, Any]

Read the token/GPU usage summary. Backend route: GET /api/v1/balance/usage.

`ResearchAccountCreditsAPI`

Credits ledger reads. Methods:

`transactions`

transactions(self) -> dict[str, Any]

List purchase/usage transactions, most recent first. Backend route: GET /api/v1/credits/transactions (query cursor, limit).

`ResearchAccountTiersAPI`

Default rate limits per subscription tier. Methods:

`list`

list(self) -> tuple[AccountTierLimits, ...]

List default limits for all tiers. Backend route: GET /api/v1/usage/tiers.

`get`

get(self, tier: str) -> AccountTierLimits

Read default limits for one tier. Backend route: GET /api/v1/usage/tiers/{tier}.

`ResearchAccountByokAPI`

Bring-your-own-key provider key management. Methods:

`list`

list(self) -> dict[str, Any]

List stored provider key metadata. Backend route: GET /api/v1/byok/keys.

`create`

create(self) -> dict[str, Any]

Store a provider key (ciphertext encrypted with crypto.public_key). Backend route: POST /api/v1/byok/keys.

`get`

get(self, provider: str) -> dict[str, Any]

Read stored key metadata for one provider. Backend route: GET /api/v1/byok/keys/{provider}.

`delete`

delete(self, provider: str) -> dict[str, Any]

Delete the stored key for one provider. Backend route: DELETE /api/v1/byok/keys/{provider}.

`validate`

validate(self, provider: str) -> dict[str, Any]

Validate the stored key against the provider’s API. Backend route: POST /api/v1/byok/keys/{provider}/validate.

`status`

status(self) -> AccountByokStatus

Read BYOK enablement and provider key coverage. Backend route: GET /api/v1/byok/status.

`ApiKeyRedactedRow`

Typed redacted key row (prefix + last4 only; never the secret). Methods:

`from_wire`

from_wire(cls, payload: object) -> ApiKeyRedactedRow

`MintedApiKey`

ONE-TIME mint/rotate result. key is the full sk_synth_user_... secret and is shown exactly once — the backend never returns it again (listings are redacted). Store it immediately; treat this object as sensitive material. Methods:

`from_wire`

from_wire(cls, payload: object) -> MintedApiKey

`ApiKeyDeactivated`

Typed delete result (soft deactivation; the row is kept inactive). Methods:

`from_wire`

from_wire(cls, payload: object) -> ApiKeyDeactivated

`ResearchAccountKeysAPI`

Synth API-key lifecycle (list redacted, mint, rotate, deactivate). Requires backend routes /api/v1/auth/keys (backend PR feat/api-key-lifecycle-routes-20260720); the caller’s API key is the principal, and every operation is scoped to that key’s (user, org). Methods:

`list`

list(self) -> tuple[ApiKeyRedactedRow, ...]

List the caller’s active keys, redacted (prefix + last4 only). Backend route: GET /api/v1/auth/keys.

`create`

create(self) -> MintedApiKey

Mint a new key; the full secret is returned exactly once. Backend route: POST /api/v1/auth/keys. Returns 409 if an active key already exists (use :meth:rotate). name is refused by the backend today (no name column); pass it only once naming ships.

`rotate`

rotate(self, key_id: str) -> MintedApiKey

Rotate: deactivate key_id and mint a replacement. The old secret stops validating within the backend auth-cache TTL. Backend route: POST /api/v1/auth/keys/{key_id}/rotate. The new secret is returned exactly once.

`delete`

delete(self, key_id: str) -> ApiKeyDeactivated

Deactivate key_id (soft delete; the backend keeps the row inactive). Backend route: DELETE /api/v1/auth/keys/{key_id}.

`ResearchAccountMembersAPI`

Org member listing. Methods:

`list`

list(self) -> dict[str, Any]

List org members with app-user details. Backend route: GET /api/members (mounted with the /api prefix, not /api/v1; query limit, offset).

`ResearchAccountSubscriptionAPI`

Subscription lifecycle (cancel only). Methods:

`cancel`

cancel(self) -> dict[str, Any]

Cancel the subscription at the end of the current billing period. Backend route: POST /api/v1/subscription/cancel.

`ResearchAccountCryptoAPI`

Public-key material for client-side key encryption. Methods:

`public_key`

public_key(self) -> dict[str, Any]

Read the app public key used to encrypt BYOK keys. Backend route: GET /api/v1/crypto/public-key.

`ResearchAccountAPI`

Org account namespace: balance, credits, usage, BYOK, members, identity. Methods:

`balance`

balance(self) -> ResearchAccountBalanceAPI

Org credit balance and usage summary.

`credits`

credits(self) -> ResearchAccountCreditsAPI

Credits ledger transactions.

`tiers`

tiers(self) -> ResearchAccountTiersAPI

Default per-tier rate limits.

`byok`

byok(self) -> ResearchAccountByokAPI

Provider key (BYOK) management.

`keys`

keys(self) -> ResearchAccountKeysAPI

Synth API-key lifecycle (list redacted / mint / rotate / deactivate).

`members`

members(self) -> ResearchAccountMembersAPI

Org member listing.

`subscription`

subscription(self) -> ResearchAccountSubscriptionAPI

Subscription lifecycle (cancel).

`crypto`

crypto(self) -> ResearchAccountCryptoAPI

Public-key material for BYOK encryption.

`usage`

usage(self) -> dict[str, Any]

Read current org usage counters. Backend route: GET /api/v1/usage.

`user_limits`

user_limits(self) -> dict[str, Any]

Read effective limits for the authenticated user. Backend route: GET /api/v1/usage/user-limits.

`overview`

overview(self) -> dict[str, Any]

Read the entitlements + usage + spend overview. Backend route: GET /api/v1/usage/overview (query days 1-365, include_projects).

`readiness`

readiness(self) -> AccountReadiness

Read org account readiness checks (balance, runway, tier headroom, BYOK). Backend route: GET /api/v1/account/readiness.

`me`

me(self) -> AccountIdentity

Resolve the org/user identity for the API key. Backend route: GET /api/v1/me.

​synth_ai.research.account

​Classes

​AccountBalance

​from_wire

​AccountTierLimits

​from_wire

​AccountByokStatus

​from_wire

​AccountReadinessCta

​from_wire

​AccountReadinessCheck

​from_wire

​AccountReadiness

​from_wire

​AccountIdentity

​from_wire

​ResearchAccountBalanceAPI

​get

​usage

​ResearchAccountCreditsAPI

​transactions

​ResearchAccountTiersAPI

​list

​get

​ResearchAccountByokAPI

​list

​create

​get

​delete

​validate

​status

​ApiKeyRedactedRow

​from_wire

​MintedApiKey

​from_wire

​ApiKeyDeactivated

​from_wire

​ResearchAccountKeysAPI

​list

​create

​rotate

​delete

​ResearchAccountMembersAPI

​list

​ResearchAccountSubscriptionAPI

​cancel

​ResearchAccountCryptoAPI

​public_key

​ResearchAccountAPI

​balance

​credits

​tiers

​byok

​keys

​members

​subscription

​crypto

​usage

​user_limits

​overview

​readiness

​me

`synth_ai.research.account`

Classes

`AccountBalance`

`from_wire`

`AccountTierLimits`

`from_wire`

`AccountByokStatus`

`from_wire`

`AccountReadinessCta`

`from_wire`

`AccountReadinessCheck`

`from_wire`

`AccountReadiness`

`from_wire`

`AccountIdentity`

`from_wire`

`ResearchAccountBalanceAPI`

`get`

`usage`

`ResearchAccountCreditsAPI`

`transactions`

`ResearchAccountTiersAPI`

`list`

`get`

`ResearchAccountByokAPI`

`list`

`create`

`get`

`delete`

`validate`

`status`

`ApiKeyRedactedRow`

`from_wire`

`MintedApiKey`

`from_wire`

`ApiKeyDeactivated`

`from_wire`

`ResearchAccountKeysAPI`

`list`

`create`

`rotate`

`delete`

`ResearchAccountMembersAPI`

`list`

`ResearchAccountSubscriptionAPI`

`cancel`

`ResearchAccountCryptoAPI`

`public_key`

`ResearchAccountAPI`

`balance`

`credits`

`tiers`

`byok`

`keys`

`members`

`subscription`

`crypto`

`usage`

`user_limits`

`overview`

`readiness`

`me`