Usage metering

Usage describes resource quantities and observations within an authorized workspace and project. Keep each value's unit, source, time window and completeness; a quantity is not a monetary amount.

Resource availability

Capacity search precedes allocation. A supported GPU type can still wait for a free machine. Read the Job timeline and events to distinguish waiting, allocation, ready, stop requested and confirmed release.

Meters and units

Meter	Quantity	Native unit	Readable unit
gpu.<GPU type>	Inference or workspace sampling GPU count × policy window	GPU-millisecond	GPU-hour
train.gpu.<GPU type>	Training GPU count × policy window	GPU-millisecond	GPU-hour
cpu.vcpu	Allocated vCPUs × policy window	vCPU-millisecond	vCPU-hour
cpu.mem	Allocated memory × policy window	MiB-millisecond	GiB-hour
storage.bytes	Retained checkpoint bytes × observation interval	byte-hour	GB-month (10⁹ bytes × 730 hours)

Use the actual allocated shape, not the requested shape or utilization percentage. Eight GPUs over an observed half-hour interval represent four GPU-hours. Do not sum native quantities across different meters. Current checkpoint bytes are a capacity snapshot, not bytes integrated over time.

Lifecycle and observations

1. Read allocation and ready timestamps separately; startup is not training or generation time.
2. After a stop, the Job's cleanup Operation and terminal state confirm the release. Lost resources may have only a last successful heartbeat.
3. Policy-adjusted quantities exposed by existing APIs can differ from wall-clock duration. Preserve the server's status and window; do not reconstruct observed runtime from a policy quantity.
4. Existing training gpu.usage_hours is policy-window duration in hours, without multiplying GPU count; it is not aggregate GPU-hours. Keep this distinct from gpu.gpu_hours when supplied.
5. Project training usage is cumulative across its recorded Jobs. The existing training usage endpoint's date parameters do not make it a date-filtered report. Job and Trial lifecycle observations retain their own timestamps.
6. A missing value was not observed. A missing monetary field leaves the known resource or token quantity in place. The cost, estimate and status fields keep their API contract; settled charges are in the account ledger.

Read project usage with an API Key

A project Key with the Read only or Project automation preset has billing.read for its own project. It can read that project's recorded usage over HTTP:

curl --fail-with-body --silent --show-error -G \
  "https://api.envloop.ai/v1/projects/$ENVLOOP_PROJECT_ID/billing/usage" \
  -H "Authorization: Bearer $ENVLOOP_API_KEY" \
  --data-urlencode "start=2026-11-01T00:00:00Z" \
  --data-urlencode "end=2026-11-02T00:00:00Z" \
  --data-urlencode "group_by=meter"

• Set ENVLOOP_PROJECT_ID to the project the Key belongs to (el auth status shows it). The response covers only that project.
• start and end are required ISO 8601 timestamps with a timezone, such as 2026-11-01T00:00:00Z or 2026-11-01T08:00:00+08:00. A timestamp without a timezone, or one that cannot be parsed, returns 422 INVALID_BILLING_WINDOW; the message names the parameter, start or end. end is exclusive. URL-encode the parameters so that a + offset is not read as a space.
• group_by is day (default), meter, product, sku or endpoint. Another value returns 422 INVALID_GROUP_BY.
• Each item has the group key, quantity in the native unit of its meters (Meters and units), gpu_seconds, and the recorded amount fields of the existing API. Group by meter before comparing quantities, because native units differ between meters.

API Keys cannot read workspace finances. Requests for the workspace balance or workspace-wide usage, including the CLI's workspace account command, return 403 ACCESS_DENIED (“requires a human billing grant”) with a Key; use the project route above instead. To see the balance, sign in to the Console as a workspace member with the Billing, Admin or Owner role and open MANAGE → Billing. Project members can open MANAGE → Usage for the project.

LLM tokens

Captured model requests can report input, cache-read, cache-write, output and reasoning tokens. Preserve the reported categories: reasoning may be included in output, so do not add it twice. Job/Trial traces cover captured requests only and may omit external calls.

Relay usage is attributed to the authorized project and request time interval, with an exclusive end. Client-supplied session or request labels are not used to attribute usage to a Job or Trial. Calls using a separate provider key or endpoint may have a different observation source. Keep source and completeness when comparing totals.

Storage

Retained checkpoint size is recorded after durable persistence. An upload still in progress is not a durable checkpoint. A checkpoint leaves retained usage after deletion is requested or TTL expires; physical file removal can happen later. Inspect the cleanup Operation before declaring cleanup complete. See Checkpoints.

Sampling and resource release

Supported inference-backed sampling has its own replica lifecycle. A replica may remain allocated between requests and stop after inactivity. Shared workspace replicas are not attributed to one project. Public interactive sampler factories remain removed; use the supported inference workflow.