Margin queries

Margin methods are available under nozle.margin and call GET /api/v1/margin/*.

import { Nozle } from '@nozle-js/node'

const nozle = new Nozle() // reads NOZLE_SECRET_KEY

const range = {
  from: '2026-07-01',
  to: '2026-07-31',
}

const summary = await nozle.margin.summary(range)
const customers = await nozle.margin.byCustomer(range)
const metrics = await nozle.margin.byMetric(range)
const plans = await nozle.margin.byPlan(range)
const models = await nozle.margin.byModel(range)

Methods

Method	Endpoint	Purpose
`summary(params?)`	`/summary`	Aggregate margin summary.
`byCustomer(params?)`	`/customers`	Margin grouped by customer.
`byMetric(params?)`	`/metrics`	Margin grouped by Feature.
`byPlan(params?)`	`/plans`	Margin grouped by plan.
`byModel(params?)`	`/models`	Margin grouped by model.
`trend(params?)`	`/trend`	Time-series margin data.

Date filters

All methods accept optional from and to strings: a YYYY-MM-DD date or an RFC3339 timestamp. A plain date to includes that whole day; an RFC3339 to is an exclusive instant. If you send only one end, the API derives the other (only to: the month before it; only from: until now). Additional string query parameters are forwarded as provided.

const result = await nozle.margin.byCustomer({
  from: '2026-07-01T00:00:00Z',
  to: '2026-08-01T00:00:00Z',
})

Invalid ranges

An unparseable date, or an end that is not after the start, makes the API answer 400. The SDK throws a NozleApiError with the usual margin/summary failed: 400 Bad Request message and the response code on err.code.

import { NozleApiError } from '@nozle-js/node'

try {
  await nozle.margin.summary({ from: '2026-07-31', to: '2026-07-01' })
} catch (err) {
  if (err instanceof NozleApiError && err.code === 'invalid_date_range') {
    // ask for a corrected range
  }
}

Trend granularity

const trend = await nozle.margin.trend({
  from: '2026-07-01',
  to: '2026-07-31',
  granularity: 'day',
})

granularity accepts hour, day, week, or month and defaults to day.

Result typing

Margin methods return payloads as unknown; narrow them in your application or validate them with your schema library before use.

const summary = await nozle.margin.summary(range)

if (!isMarginSummary(summary)) {
  throw new Error('Unexpected margin response')
}

The Node SDK does not expose the Margin Simulate API. Call the Margin simulate API directly from your backend when needed.

Setup

Billing

Customers

Entitlements

Margin Intelligence

LLM Usage

Margin queries

Methods

Date filters

Invalid ranges

Trend granularity

Result typing

​Methods

​Date filters

​Invalid ranges

​Trend granularity

​Result typing

Methods

Date filters

Invalid ranges

Trend granularity

Result typing