Compute units

Usage is measured on compute rather than on calls, because two requests can differ by orders of magnitude in the work they cause. The formula is simple enough to predict before you send anything — and simple in a way that is worth understanding, because it is not the way most people guess.

The formula

Contracts in the active version, times months the grid spans, times segment combinations evaluated. That last factor is one today, and will stay one until this API grows a way to ask for a segment sweep — it is in the formula so that adding one later is a number rather than a repricing.

measured against the service

contracts   axis months   units
─────────   ───────────   ─────
        1            14      14
        2            14      28
        1             3       3
      380            50   19000

Counting requests instead would price a one-contract query and a forty-thousand-contract query identically, which is why it is not done that way.

Why it is a rectangle

Every contract is charged for every month on the axis — not for the months it individually covers. A contract running three months of a sixty-month axis costs the same as one running all sixty.

That sounds worse than it is, because you do not choose the axis. It is derived from your data: the earliest signature to the furthest commitment. A dataset of short contracts has a short axis and a small bill. The rectangle only bites when one long contract stretches the axis under many short ones — and in that dataset, the engine really is computing every one of those cells.

Two consequences worth designing around. A dataset whose axis is stretched by a single outlying contract costs more for every query, so splitting genuinely unrelated books into separate datasets is cheaper as well as clearer. And a horizon far in the future does not lengthen the axis — the axis comes from the contracts.

Where the number appears

On the response that incurred it. Every metrics response carries the charge as a header, and it is the same number recorded against your account — computed once, so a header and an invoice cannot drift apart.

on every metrics response

POST /v1/datasets/{id}/metrics
< 200 OK
< X-Plantactic-Compute-Units: 19000

# 380 contracts x a 50-month axis

Exports are the exception, and it is a gap rather than a subtlety. An export runs a grid query and is metered exactly like one, but it returns 202 before the work happens, so there is no response to put the header on and none is added when it finishes. If you instrument spend from response headers, exports are invisible to that instrumentation.

There is also no self-service usage total. Usage is recorded per request; seeing it aggregated is a support request today — support@plantactic.com.

Nothing is refused for cost

There is no quota and no rate limiting. No endpoint answers 429, no budget is checked before a query runs, and nothing is rejected for being expensive. Usage is recorded after the work, not admitted before it.

Two things follow, and the second is the one that costs money. First, do not build a backoff for a status this API does not send — build one for the network, which is real. Second, a query you did not mean to run is charged rather than blocked. There is no ceiling behind you, so a loop that re-queries a large dataset in a tight retry will keep being served, and will keep metering, for as long as it runs.

Controlling what you spend

Cache on your side. A grid computed against a given version can never go stale, because versions are immutable. There is no ETag and no 304 here, so the caching is entirely yours to do — Querying metrics covers the awkward part, which is that the grid does not carry the version id you would want to key on.
Do not poll a grid. Nothing about it changes until you upload a new version, and you know when you do that.
Keep unrelated books in separate datasets. One long contract stretches the axis for everything beside it.
Test mode is never billed. Develop against a ptx_test_ key and the meter does not run at all — Test mode.