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. (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). Habit-specific shortcuts live under Related below.

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
booking_communication_summaryBookings → Communication → SummaryBookings — AI conversation summary, FAQ — WhatsApp and email per booking
faq_generationAccount Settings → FAQs FAQ GeneratorFAQs — Run FAQ Generator
ticket_priority_analysisAccount Settings → Ticket priority Analyze ticketsTicket priority — Analyze past tickets
cashflow_invoice_analysisOperations → Cash Flows AI Analysis on a cash-flow attachmentOperations — AI Invoice Analysis

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.

AI usage section cross-reference​

Use the endpoints and fields above. Related integrator pages are linked inline where useful.

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

Operator habit hubs​

Day-to-day operator habits (lockout catch-up, pending receipts, payment triage, handoffs, and related playbooks) live on the Common Workflows habit hub.

Deep-link anchors for habit hubs

Lockout catch-up after password recovery​

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​

Deeper concept reads​

Deeper workflow reads​

Key glossary terms​

Module documentation hubs​

Pair with other AI usage guide sections

for screen-by-screen follow-up after polling usage.

  • 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)