> ## 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 synchronous and available under `nozle.margin`.

```python theme={null}
summary = nozle.margin.summary(
    from_date="2026-07-01",
    to_date="2026-07-31",
)

customers = nozle.margin.by_customer(from_date="2026-07-01")
metrics = nozle.margin.by_metric()
plans = nozle.margin.by_plan()
models = nozle.margin.by_model()
```

## Methods

| Method                         | Endpoint     | Purpose                     |
| ------------------------------ | ------------ | --------------------------- |
| `summary(**params)`            | `/summary`   | Aggregate margin summary.   |
| `by_customer(**params)`        | `/customers` | Margin grouped by customer. |
| `by_metric(**params)`          | `/metrics`   | Margin grouped by Feature.  |
| `by_plan(**params)`            | `/plans`     | Margin grouped by plan.     |
| `by_model(**params)`           | `/models`    | Margin grouped by model.    |
| `trend(granularity, **params)` | `/trend`     | Time-series margin data.    |

All non-`None` keyword arguments are forwarded as string query parameters. Use the parameter names expected by your deployed API.

## Trend granularity

```python theme={null}
trend = nozle.margin.trend(
    granularity="day",
    from_date="2026-07-01",
    to_date="2026-07-31",
)
```

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

## Result typing

Margin responses are typed as `Any` in v0.4.0. Validate or narrow them before relying on their fields.

```python theme={null}
summary = nozle.margin.summary(from_date="2026-07-01")

if not isinstance(summary, dict):
    raise TypeError("Unexpected margin response")
```

<Info>
  The Margin Simulate API is not exposed by the Python SDK in v0.4.0. Call the [Margin simulate API](/api/margin-simulate) directly from your backend.
</Info>