Skip to main content

AI usage (token cost visibility)

First-time workspace setup

These routes use the same management session as the browser — complete Getting Started — Recommended Setup Sequence steps 1–3 (Users, Preferences) before scripting POST /auth/login. Pair with Management session authentication for JWT + refresh cookie examples. There is no management-frontend screen for this ledger today; external clients poll HTTP or build internal dashboards. Workflow pairing: Setup sequence after go-live (hub: API Reference — Setup sequence after go-live).

Finding your way in this guide

Start with Who can call these routes, then Endpoints for GET /ai-usage and GET /ai-usage/summary. Filter with Query parameters; interpret rows in Response fields and Feature values. Contrast Management session (operator JWT) with partner Authentication (integration Bearer keys). Non-linear operator habits (Lockout catch-up, Pending manual receipt approval, Reject/revert mistaken receipts, Portfolio segmentation by tenant category, Notification row-click navigation, Payment alert to receivables triage, Confirmation alert triage, Finance debt receivables triage, Handling a Late Payment collections, Finance Income status drill-down, Cash flow forecast drill-down) have matching Related subsections below. Full pairing matrix: AI usage section cross-reference · API Reference — API guide cross-reference.

Vivin records every LLM call that flows through the shared metered Anthropic chokepoint into an append-only ai_usage ledger — one row per model invocation, scoped to the owning accountId. These Core API routes expose that ledger to signed-in operators for cost visibility and internal reporting.

Recording is best-effort: a failed insert never breaks the AI feature that produced the call. Costs are Vivin's internal provider cost in USD (not tenant-facing billing).

Who can call these routes​

RequirementDetail
AuthManagement JWT from Management session authentication (Authorization: Bearer <JWT>)
Permissionaccount_settings.module — same gate as Account Settings tabs
TenancyEvery query is filtered to the signed-in user's accountId; you cannot read another workspace's usage

401 / 403 responses follow Error handling. Do not call these routes with partner integration Bearer keys.

Endpoints​

GET /ai-usage​

Returns a paginated list of individual AI calls for the signed-in account, newest first.

GET /ai-usage?page=1&limit=50 HTTP/1.1
Host: api.vivin.app
Authorization: Bearer <JWT>

Response (200) — paginated envelope:

{
  "items": [
    {
      "id": "…",
      "accountId": "…",
      "feature": "landlord_chat",
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514",
      "inputTokens": 1200,
      "outputTokens": 340,
      "cacheCreationInputTokens": 0,
      "cacheReadInputTokens": 0,
      "totalTokens": 1540,
      "cost": 0.004512,
      "currency": "USD",
      "pricingSnapshot": {
        "currency": "USD",
        "perMTok": { "input": 3, "output": 15 }
      },
      "userId": "…",
      "source": "Frontend",
      "conversationId": "…",
      "referenceId": null,
      "metadata": null,
      "createdAt": "2026-07-01T14:22:11.000Z"
    }
  ],
  "total": 128,
  "page": 1,
  "limit": 50
}

Use this route when you need call-level drill-down (conversation id, model id, per-call token splits, optional referenceId such as a utility bill id).

GET /ai-usage/summary​

Returns aggregate totals plus a per-feature / per-model breakdown for the signed-in account.

GET /ai-usage/summary?from=2026-06-01T00:00:00.000Z&to=2026-06-30T23:59:59.999Z HTTP/1.1
Host: api.vivin.app
Authorization: Bearer <JWT>

Response (200) — summary envelope:

{
  "currency": "USD",
  "totals": {
    "calls": 42,
    "inputTokens": 88000,
    "outputTokens": 12000,
    "cacheCreationInputTokens": 0,
    "cacheReadInputTokens": 4000,
    "totalTokens": 104000,
    "cost": 0.312
  },
  "breakdown": [
    {
      "feature": "landlord_chat",
      "model": "claude-sonnet-4-20250514",
      "calls": 38,
      "inputTokens": 82000,
      "outputTokens": 11000,
      "cacheCreationInputTokens": 0,
      "cacheReadInputTokens": 4000,
      "totalTokens": 97000,
      "cost": 0.285,
      "pricePerMTok": { "input": 3, "output": 15 }
    },
    {
      "feature": "utility_bill_extraction",
      "model": "claude-sonnet-4-20250514",
      "calls": 4,
      "inputTokens": 6000,
      "outputTokens": 1000,
      "cacheCreationInputTokens": 0,
      "cacheReadInputTokens": 0,
      "totalTokens": 7000,
      "cost": 0.027,
      "pricePerMTok": { "input": 3, "output": 15 }
    }
  ]
}

Use this route for month-end roll-ups or dashboards. Breakdown rows include the current price per million tokens map entry for each model (pricePerMTok); individual list rows also store a pricingSnapshot so historical costs stay reproducible if rates change later.

Query parameters​

Both routes accept the same filter query string (pagination applies only to GET /ai-usage):

ParameterTypeDescription
fromISO date-timeInclusive lower bound on createdAt
toISO date-timeInclusive upper bound on createdAt
featureenumRestrict to one product feature — see Feature values
pageinteger ≥ 1Page number for GET /ai-usage (default 1)
limitinteger 1–200Page size for GET /ai-usage (default 50, max 200)

Example — landlord chat only, June 2026:

curl -sS -b cookies.txt -H "Authorization: Bearer ${VIVIN_JWT}" \
  'https://api.vivin.app/ai-usage/summary?feature=landlord_chat&from=2026-06-01T00:00:00.000Z&to=2026-06-30T23:59:59.999Z'

Response fields​

FieldMeaning
featureProduct surface that invoked the model — Feature values
providerLLM vendor (today anthropic)
modelModel id string passed to the provider
inputTokens / outputTokensUncached input and output token counts
cacheCreationInputTokens / cacheReadInputTokensAnthropic prompt-cache write and read tokens when applicable
totalTokensSum of the four token counters (convenience for sorting and display)
cost / currencyVivin internal provider cost ( USD today)
pricingSnapshotPer-MTok rates used to compute cost on that row
userIdOperator who triggered the call when recorded
sourceOrigin label when set (for example Frontend, Whatsapp)
conversationIdAI Chat thread id when the call came from /ai-chat
referenceIdOptional domain key (for example a utility bill id)
metadataOptional JSON bag for feature-specific context
createdAtWhen the call was recorded (UTC)

Rows with accountId: null exist only for system/global calls with no tenant context (for example the shared utility-bill mailbox). GET /ai-usage never returns those rows to operator sessions — only the signed-in account's usage.

Feature values​

Persisted string values in ai_usage.feature (append-only — do not rename existing values):

ValueProduct surfaceOperator docs
landlord_chatAI Chat (/ai-chat) and embedded Landlord MCP tool loops in-processAutomation & AI — Management AI Assistant
utility_bill_extractionUtilities Upload PDF / AI invoice readerAutomation & AI — AI Invoice Reader, Entering Monthly Utility Bills

New AI features add new enum values when they start calling the metered service.

Command-line example​

After Management session login:

# Paginated call log (newest first)
curl -sS -b cookies.txt -H "Authorization: Bearer ${VIVIN_JWT}" \
  'https://api.vivin.app/ai-usage?limit=10' | jq .

# Month-end summary by feature and model
curl -sS -b cookies.txt -H "Authorization: Bearer ${VIVIN_JWT}" \
  'https://api.vivin.app/ai-usage/summary?from=2026-06-01T00:00:00.000Z&to=2026-06-30T23:59:59.999Z' | jq .

Replace api.vivin.app with your API host (http://localhost:3000 when running Core API locally with a full env).

AI usage section cross-reference​

| Topic | Pair with | | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Who can call these routes | Management session, Users and roles — Role permissions | | Endpoints | Error handling (401 / 403), Core Swagger /api when enabled — Management session — Core API Swagger | | Feature values | AI Chat module, Utilities — Bills tab, Landlord MCP (external clients use MCP tools, not this ledger, for operational automation) | | Cost review habit | Portfolio KPI review (reconcile AI spend with utility and chat adoption) | | Settings gates | Users and roles (account_settings.module), Integrations (Bearer vs JWT contrast), Subscription (platform billing vs internal AI cost), Payments, Invoicing & Utilities (utility_bill_extraction driver), General Information, Owners, Contract templates, Services, Categories, Tenant categories (segment filters vs account-scoped ledger), My Profile (JWT refresh after lockout), Interface language (JWT refresh after lockout — locale independent), Integration field capability (partner matrix vs JWT ledger), Account Settings hub (setup tabs + account_settings.module gate) | | Module & concept surfaces | Modules hub (screen workspaces + AI cost review habit), Listings (utility_bill_extraction), Audit (landlord_chat during manual-block hygiene), Booking engine details (partner Bearer vs JWT), Legacy /properties URLs, Booking Lifecycle, Integrations & Distribution, Deep Links, Tenant Portal (not metered), Payment Allocation (month-end reconciliation habit), Services Marketplace (ancillary income review), Create New menu (utility_bill_extraction from Upload Utility Bills) | | Partner API contrast | Creating Bookings, Listings & Availability, Webhooks & Notifications, iCal feeds, Full listing feeds, Booking Lifecycle & Validations, Booking engine integration — integration Bearer keys return 401 | | Notification row-click navigation | Poll usage after alert triage sessions | API Reference — Notification row-click navigation, Common Workflows — Notification row-click navigation, Notifications module — Notification row-click navigation | | Payment alert to receivables triage | Token metering vs payment overdue row-click | API Reference — Payment alert to receivables triage, Common Workflows — Payment alert to receivables triage, Handling a Late Payment — Step 1 | | Confirmation alert triage | Usage spikes during confirmation-week triage | API Reference — Confirmation alert triage, Common Workflows — Confirmation alert triage, Processing a New Booking — Step 5b | | Finance debt receivables triage | Portfolio reads after receivables triage | API Reference — Finance debt receivables triage, Common Workflows — Finance debt receivables triage, Finance module — Finance debt receivables triage | | Handling a Late Payment collections | Integration surface vs operator collections Steps 1–6 | | Finance Income status drill-down | Assistant answers vs Income segment modals | API Reference — Finance Income status drill-down, Common Workflows — Finance Income status drill-down, FAQ — Finance Income status drill-down hub | | Cash flow forecast drill-down | Collections context vs forecast bar-click | API Reference — Cash flow forecast drill-down, Common Workflows — Cash flow forecast drill-down, FAQ — Cash flow forecast drill-down hub |

Setup sequence after go-live​

  • Steps 1–3 — Operator account and account_settings.module before first GET /ai-usage poll
  • After go-live — Use /ai-usage/summary for internal cost dashboards; validate landlord_chat spikes against AI Chat adoption and utility_bill_extraction against Entering Monthly Utility Bills volume

Lockout catch-up after password recovery​

When sign-in was restored mid-month, refresh the management JWT (Resetting a Management User Password — Step 3) before polling usage — expired tokens return 401, not partial data.

Pending manual receipt approval​

Unrelated to AI metering — see Finance — Pending manual payments.

Reject/revert mistaken receipts​

Unrelated to AI metering — see Payment Allocation — Correcting mistaken receipts.

Portfolio segmentation by tenant category​

AI usage is account-scoped, not tenant-category-scoped — segment operational follow-up with Bookings — Other filters when chat or utility AI activity clusters on one tenant segment.

Notification row-click navigation​

Pair with other AI usage guide sections

GET /ai-usage metering does not replace /notifications row-click — poll token cost after operator alert triage, not instead of inbox navigation. Hub parity: API Reference — Notification row-click navigation. Full pairing matrix: AI usage section cross-reference · API guide cross-reference.

Payment alert to receivables triage​

Pair with other AI usage guide sections

Landlord MCP or assistant summaries about overdue balances still require payment overdue row-click into booking Transactions before collections outreach. Hub parity: API Reference — Payment alert to receivables triage. Full pairing matrix: AI usage section cross-reference · API guide cross-reference.

Confirmation alert triage​

Pair with other AI usage guide sections

High landlord_chat usage during confirmation week pairs with Upcoming alert triage — assistant output does not approve confirmation receipts. Hub parity: API Reference — Confirmation alert triage. Full pairing matrix: AI usage section cross-reference · API guide cross-reference.

Finance debt receivables triage​

Pair with other AI usage guide sections

AI portfolio summaries are not a substitute for Finance → Overview → Debt Aging Top debtors after partner import alert triage. Hub parity: API Reference — Finance debt receivables triage. Full pairing matrix: AI usage section cross-reference · API guide cross-reference.

Handling a Late Payment collections​

Pair with other API Reference hub sections

Partner integration reads on Ai Usage do not replace operator collections — payment overdue in-app rows still need Handling a Late Payment — Steps 1–6 after receivables triage. Hub parity: Common Workflows — Handling a Late Payment collections hub. Full pairing matrix: ai-usage-section-cross-reference · API guide cross-reference.

Finance Income status drill-down​

Pair with other AI usage guide sections

Management JWT GET /ai-usage pairs with operator Income chart segment clicks — chat answers do not open month-scoped payment-line modals. Hub parity: API Reference — Finance Income status drill-down. Full pairing matrix: AI usage section cross-reference · API guide cross-reference.

Cash flow forecast drill-down​

Pair with other AI usage guide sections

Token-cost reads during month-end reconciliation — contrast assistant collections narrative with Cash flow forecast bar-click modals on Finance → Overview. Hub parity: API Reference — Cash flow forecast drill-down. Full pairing matrix: AI usage section cross-reference · API guide cross-reference.

Deeper concept reads​

Deeper workflow reads​

Key glossary terms​

Pair with other AI usage guide sections

Glossary rows pair with Glossary cluster cross-reference and month-end reconciliation habits. Full pairing matrix: AI usage section cross-reference.

Module documentation hubs​

Pair with other AI usage guide sections

Module hubs pair with Modules — Module cross-reference for screen-by-screen follow-up after polling usage. Full pairing matrix: AI usage section cross-reference.

  • AI Chat module — landlord_chat volume driver for in-management assistant sessions (hub)
  • Utilities module — utility_bill_extraction volume driver on Bills tab PDF upload (hub)
  • Dashboard module — Same-day KPI snapshot before month-end cost review (hub)
  • Analytics module — Month-range portfolio charts to contextualize AI adoption spikes (hub)
  • Finance module — Deposits and Transactions tabs paired with month-end /ai-usage/summary review (hub)
  • Bookings module — Deposit tab lifecycle pills when reconciling deposit shortfalls alongside AI spend (hub)
  • Operations module — Ticket triage when landlord_chat surfaces maintenance context (hub)
  • Account Settings — account_settings.module gate and workspace setup before first GET /ai-usage poll (hub)