> ## 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.

```go theme={null}
import nozle "github.com/nozle-dev/nozle-go"

client := nozle.New("") // reads NOZLE_SECRET_KEY

filters := url.Values{"from_date": {"2026-07-01"}, "to_date": {"2026-07-31"}}
summary, err := client.MarginSummary(ctx, filters)
trend, err := client.MarginTrend(ctx, "day", filters)
_ = summary
_ = trend
_ = err
```

`MarginByCustomer`, `MarginByMetric`, `MarginByPlan`, and `MarginByModel` call their corresponding Engine `/api/v1/margin/*` endpoints. Results are `json.RawMessage`; decode into a shape appropriate for your deployed report schema. Trend granularity accepts `hour`, `day`, `week`, or `month`.

## Date filters

`from_date` and `to_date` are aliases for the API's `from` and `to` (you can also send `from` and `to`). Each takes a `YYYY-MM-DD` date or an RFC3339 timestamp. A plain date `to_date` includes that whole day; an RFC3339 value is an exclusive instant. If you send only one end, the API derives the other (only `to_date`: the month before it; only `from_date`: until now). An unparseable value, or an end that is not after the start, returns `400` with `{"code": "invalid_date_range", "error": "..."}`.

## Methods

| Method | Endpoint | Purpose |
| - | - | - |
| `MarginSummary` | `/margin/summary` | Aggregate margin. |
| `MarginByCustomer` | `/margin/customers` | Group by customer. |
| `MarginByMetric` | `/margin/metrics` | Group by Feature. |
| `MarginByPlan` | `/margin/plans` | Group by plan. |
| `MarginByModel` | `/margin/models` | Group by model. |
| `MarginTrend` | `/margin/trend` | Time series. |

All methods take `url.Values` for deployed API query parameters. `MarginTrend` also takes a granularity: an empty string is sent as `day`, and any other value outside `hour`, `day`, `week`, and `month` (for example `year`) returns `nozle: margin.trend: invalid granularity` without a request. Check the raw JSON shape before depending on report fields. Margin simulation is a separate [REST API](/api/margin-simulate).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.