Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.maximem.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​
entry_type
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.
​
from_time
datetime
Inclusive lower bound on created_at. Omit to start from the beginning of history.
​
to_time
datetime
Inclusive upper bound on created_at. Omit to read up to the present.
​
limit
int
default:"100"
Maximum number of entries to return in this page.
​
offset
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.
​
entries
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.
​
total
int
Total number of entries matching the filters (across all pages).
​
limit
int
Echo of the limit used for this page.
​
offset
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.

​
See also