Usage Records

Usage records are timestamped data points stored in a MongoDB timeseries collection. They are the source of truth for all usage tracking in SolvaPay — limit checks, billing calculations, and analytics dashboards all query from the same data stream.

Record Structure

Each usage record contains:

Field	Type	Description
`timestamp`	`Date`	When the event occurred
`metadata.providerId`	`ObjectId`	The provider that owns this event
`metadata.meterName`	`string`	Which meter this record belongs to (e.g. `requests`)
`metadata.customerRef`	`string`	The customer who triggered the event
`value`	`number`	Numeric value (defaults to `1` for counters)
`properties`	`object?`	Arbitrary key-value tags for filtering and analysis

Usage records are immutable. Once recorded, they cannot be modified or deleted. MongoDB’s timeseries engine automatically compresses and indexes records by metadata and time for efficient aggregation.

Recording Usage

Usage is recorded via UsageService.recordUsage(), which writes to the Usage timeseries collection.

Via SDK Endpoint

Record usage directly from your backend using the SDK API:

# Record a single event
POST /v1/sdk/meter-events
{
  "customerRef": "cus_abc123",
  "value": 1,
  "properties": {
    "endpoint": "/api/v1/search",
    "method": "GET"
  }
}

# Record events in bulk
POST /v1/sdk/meter-events/bulk
{
  "records": [
    { "customerRef": "cus_abc123", "value": 1 },
    { "customerRef": "cus_def456", "value": 1 }
  ]
}

Via Usage Endpoint

The usage endpoint records generic usage events (not direct meter-name events):

POST /v1/sdk/usages
{
  "customerRef": "cus_abc123",
  "actionType": "api_call",
  "units": 1,
  "outcome": "success",
  "productRef": "prd_P9Q0R1S2"
}

Use /v1/sdk/meter-events when you need explicit meterName + value semantics.

Via NATS Event Bus

For internal services, usage can be published over NATS:

// Record a single usage record
await nats.publish('solvapay.meter.record', {
  meterName: 'requests',
  userId: 'cus_abc123',
  value: 1,
  properties: { endpoint: '/search' }
})

// Record usage in bulk
await nats.publish('solvapay.meter.recordBulk', {
  events: [
    { meterName: 'requests', userId: 'cus_abc123', value: 1 },
    { meterName: 'requests', userId: 'cus_def456', value: 1 }
  ]
})

Automatic MCP Tool Tracking

Every MCP tool call through the SolvaPay proxy automatically records a usage record against the provider’s requests meter. No SDK integration needed — the proxy records usage with the outcome as a property:

{
  "meterName": "requests",
  "customerRef": "cus_abc123",
  "value": 1,
  "properties": {
    "outcome": "success"
  }
}

This happens fire-and-forget so it never blocks the tool call response.

Querying Usage

Aggregated Usage

Query total usage for a specific meter and customer within a time range:

GET /ui/meters/mtr_XXXXXXXX/usage?from=2025-01-01&to=2025-02-01&customerRef=cus_abc123

Time-Bucketed Aggregation

Get usage broken down by time intervals for charting:

GET /ui/meters/mtr_XXXXXXXX/usage?from=2025-01-01&to=2025-02-01&granularity=day

Supported granularities: hour, day, week, month. When no customerRef is specified, the aggregation runs across all customers.

Analytics Queries

The Usage timeseries powers several analytics views:

Query	Description
Overall daily stats	Total usage records per day
Usage by customer	Total usage grouped by customer

How Usage Powers Billing and Limits

Limit Checking

When a customer makes a request to a protected endpoint, the system:

Finds the customer’s active purchase for the product
Looks up the plan to get the limit
Resolves the plan’s auto-assigned requests meter
Queries UsageService.sumForMeter() for usage from periodStart to now
Compares the total against the plan’s hard cap

If usage exceeds the limit, the request is denied with a paywall response including a checkout URL.

Request → Find Purchase → Resolve Requests Meter
                              ↓
                    Query Usage timeseries
                    (sum from periodStart to now)
                              ↓
                    used >= limit? → Paywall
                    used < limit?  → Allow + Record Usage

End-of-Period Billing

For post-paid and hybrid plans, a daily cron job:

Finds purchases with expired billing periods
Queries the Usage timeseries for total usage in the period
Subtracts free units from the total
Applies the plan’s pricing (flat rate or tiered)
Creates a payment intent for the calculated amount

See Billing for the full billing flow.

Record Properties

The optional properties field supports arbitrary key-value pairs for filtering and analysis:

{
  "meterName": "requests",
  "customerRef": "cus_abc123",
  "value": 1,
  "properties": {
    "endpoint": "/api/v1/search",
    "method": "POST",
    "region": "us-east-1",
    "status": 200
  }
}

Properties are stored with the usage record and available in analytics queries. Use them to add context like API endpoints, tool names, regions, or response codes.

Environment Isolation

Usage records are stored in environment-specific collections:

Usage_sandbox — sandbox environment records
Usage_live — live environment records

Records in sandbox never mix with live data. The environment is determined by the provider’s configuration.

Next Steps

Meters — meter definitions
Plans — how plans use meters for limit enforcement
Billing — end-of-period usage billing

Get started

Guides

No-code MCP integration

Plans and billing

Webhooks

Admin MCP Server

Changelog

Record Structure

Recording Usage

Via SDK Endpoint

Via Usage Endpoint

Via NATS Event Bus

Automatic MCP Tool Tracking

Querying Usage

Aggregated Usage

Time-Bucketed Aggregation

Analytics Queries

How Usage Powers Billing and Limits

Limit Checking

End-of-Period Billing

Record Properties

Environment Isolation

Next Steps

​Record Structure

​Recording Usage

​Via SDK Endpoint

​Via Usage Endpoint

​Via NATS Event Bus

​Automatic MCP Tool Tracking

​Querying Usage

​Aggregated Usage

​Time-Bucketed Aggregation

​Analytics Queries

​How Usage Powers Billing and Limits

​Limit Checking

​End-of-Period Billing

​Record Properties

​Environment Isolation

​Next Steps

Record Structure

Recording Usage

Via SDK Endpoint

Via Usage Endpoint

Via NATS Event Bus

Automatic MCP Tool Tracking

Querying Usage

Aggregated Usage

Time-Bucketed Aggregation

Analytics Queries

How Usage Powers Billing and Limits

Limit Checking

End-of-Period Billing

Record Properties

Environment Isolation

Next Steps