credits.get_ledger

await sdk.credits.get_ledger(
    entry_type=None,
    from_time=None,
    to_time=None,
    limit=100,
    offset=0,
)

Returns a paginated view of the credit ledger for the caller’s wallet. Every credit movement (top-ups, redemptions, debits from usage, expirations) produces a ledger entry. The client-facing ledger does not expose USD amounts or internal rate detail. Useful for building an in-product usage history view, reconciling charges, or auditing recent debits after a spike in usage.

Parameters

string

Filter to a single entry type. Common values include "credit" (additions to the wallet) and "debit" (deductions for usage). Omit to return all entry types.

datetime

Inclusive lower bound on created_at. Omit to start from the beginning of history.

datetime

Inclusive upper bound on created_at. Omit to read up to the present.

int

default:"100"

Maximum number of entries to return in this page.

int

default:"0"

Number of entries to skip. Combine with limit to walk the full ledger.

Returns

CreditLedgerPage with one page of entries plus pagination metadata.

List[CreditLedgerEntry]

The ledger rows for this page. Each CreditLedgerEntry has:

ledger_id (string): stable identifier for the row.
entry_type (string): "credit", "debit", or similar.
delta (float): signed credit change (positive for credits added, negative for usage).
metric_type (string | None): the metered metric that produced the entry (e.g. "llm_input_tokens"), when applicable.
category (string | None): coarse grouping for the entry (e.g. "ingestion", "retrieval"), when applicable.
created_at (datetime): when the entry was recorded.

int

Total number of entries matching the filters (across all pages).

int

Echo of the limit used for this page.

int

Echo of the offset used for this page.

Example

from datetime import datetime, timedelta, timezone

from maximem_synap import MaximemSynapSDK

sdk = MaximemSynapSDK(api_key="synap_your_key_here")
await sdk.initialize()

# Show debits from the last 7 days
since = datetime.now(timezone.utc) - timedelta(days=7)

page = await sdk.credits.get_ledger(
    entry_type="debit",
    from_time=since,
    limit=50,
)

print(f"{page.total} debit entries in the last 7 days")
for entry in page.entries:
    print(
        f"  {entry.created_at.isoformat()}  "
        f"{entry.delta:+.2f}  "
        f"{entry.category or '-'}  ({entry.metric_type or '-'})"
    )

Raises

SynapAuthError: when the API key is missing or invalid.
SynapValidationError: when limit or offset are out of range.

Introduction

Lifecycle

Memory ingestion

Memory management

Conversation

Conversation context

Scoped context

User profile

Real-time streaming

Cache management

Credits & billing

Reference

Limits & Pricing

Parameters

Returns

Example

Raises

See also

​Parameters

​Returns

​Example

​Raises

​See also

Parameters

Returns

Example

Raises

See also