> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nozle.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Margin queries

> Query summary, customer, metric, plan, model, and trend margin data.

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

```ts theme={null}
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. Additional string query parameters are forwarded as provided.

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

## Trend granularity

```ts theme={null}
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

Version `0.4.0` returns margin payloads as `unknown`; narrow them in your application or validate them with your schema library before use.

```ts theme={null}
const summary = await nozle.margin.summary(range)

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

<Info>
  The Margin Simulate API is not exposed by the Node SDK in version `0.4.0`. Call the [Margin simulate API](/api/margin-simulate) directly from your backend when needed.
</Info>