Get Contract Budget

Returns the contract’s current budget: funded milestone volume versus consumed work, and the resulting OK / LOW / DEPLETED state. Read-only and side-effect-free — polling it never emits events. Use it to reconcile after downtime or to render budget status in your UI; the usage-sync guide explains how the numbers are computed.

Requirements: contracts:read scope, and the contract’s job must be referenced by a project link on the calling token’s install.

Request

contractIdstringpathrequired

The OpenTrain contract to read.

Response

contractIdstring

The contract this budget describes.

paymentTypestring | null

PAY_PER_HOUR, PAY_PER_LABEL, or FIXED_PRICE. Determines the volume unit (hours, labels) — FIXED_PRICE contracts never deplete.

statestring

OK (below 80% consumed), LOW (consumedFraction ≥ 0.8), or DEPLETED (≥ 1.0). Always OK for FIXED_PRICE or when nothing is funded.

fundedVolumenumber

Total volume (hours or labels) across funded and completed milestones.

fundedAmountUsdnumber

Total USD across those milestones.

consumedobject

Raw consumption totals across all reported usage and OpenTrain first-party work: seconds, hours, labels, tasks.

consumedVolumenumber

Consumption in the contract’s volume unit — hours for PAY_PER_HOUR, labels for PAY_PER_LABEL.

remainingVolumenumber

fundedVolume - consumedVolume, floored at 0.

consumedFractionnumber

consumedVolume / fundedVolume, rounded to 4 decimals. 0 when nothing is funded.

activeMilestoneobject | null

The current funded milestone (id, name, amountUsd, volume, status), or null if none is active.

lastUsageAtstring | null

ISO 8601 timestamp of the most recent usage report or first-party work record — null if no work has been recorded.

Errors

Status	code	Meaning
401	UNAUTHORIZED	Missing, invalid, or revoked token
403	FORBIDDEN	Token lacks contracts:read
404	NOT_FOUND	Contract not found, or its job is not linked by this install

Request examples

curl

curl -sS "https://app.opentrain.ai/api/partner/v1/contracts/<CONTRACT_ID>/budget" \
  -H "Authorization: Bearer $OT_PARTNER_TOKEN"

Response examples

200

{
  "contractId": "<CONTRACT_ID>",
  "paymentType": "PAY_PER_HOUR",
  "state": "LOW",
  "fundedVolume": 40,
  "fundedAmountUsd": 560,
  "consumed": { "seconds": 118800, "hours": 33, "labels": 0, "tasks": 87 },
  "consumedVolume": 33,
  "remainingVolume": 7,
  "consumedFraction": 0.825,
  "activeMilestone": {
    "id": "<MILESTONE_ID>",
    "name": "Week 2",
    "amountUsd": 280,
    "volume": 20,
    "status": "ACTIVE_FUNDED"
  },
  "lastUsageAt": "2026-06-12T18:00:00.000Z"
}