Skip to main content
GET
Margin Trend
Base URL: https://api.nozle.app/engine/api/v1. Get margin trend over time. Auth: sk_ only. With API key permissions, the key needs analytic:read; without it the call returns 403 with code: permission_denied.
All margin endpoints require a secret key (sk_). These endpoints expose cost data that should never be visible to your end users.
string
Start of the range, inclusive: a date (YYYY-MM-DD, which starts at 00:00 UTC that day) or an RFC3339 timestamp such as 2026-07-01T09:30:00Z. from_date is accepted as an alias.
string
End of the range: a date (YYYY-MM-DD) includes that whole day, so to=2026-07-31 covers all of July 31. An RFC3339 timestamp is used as given and is exclusive: it is the instant the range stops at. to_date is accepted as an alias.
string
Time bucket size: hour, day, week, or month (default: day). Any other value returns 400 with code invalid_granularity.
The endpoint reads only from, to, from_date, to_date and granularity. Any other query parameter is ignored without an error.

Date range

from and to take a YYYY-MM-DD date or an RFC3339 timestamp, and you can mix the two. The Python and Go SDKs send from_date and to_date, which the API treats the same way. If you send both from and from_date (or to and to_date), from and to win. When you leave an end out, the API fills it in: The API answers 400 with code invalid_date_range when a value cannot be parsed, or when the end of the range is not after its start. Equal dates are valid (they cover one day); an RFC3339 to equal to from is not.
An unparseable value returns "error": "from must be an RFC3339 timestamp or a date (YYYY-MM-DD)" (or to, with the parameter that failed).

Response

period is the start of the bucket: YYYY-MM-DD for week and month, YYYY-MM-DD HH:MM:SS for hour and day. margin_percent is 0 when the bucket has no revenue. When no events fall in the range, trend is an empty array.