Skip to main content
GET
/
api
/
partner
/
v1
/
contracts
/
{contractId}
/
budget
curl -sS "https://app.opentrain.ai/api/partner/v1/contracts/<CONTRACT_ID>/budget" \
  -H "Authorization: Bearer $OT_PARTNER_TOKEN"

{
  "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"
}
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

​
contractId
string
required
The OpenTrain contract to read.

​
Response

​
contractId
string
The contract this budget describes.
​
paymentType
string | null
PAY_PER_HOUR, PAY_PER_LABEL, or FIXED_PRICE. Determines the volume unit (hours, labels) — FIXED_PRICE contracts never deplete.
​
state
string
OK (below 80% consumed), LOW (consumedFraction ≥ 0.8), or DEPLETED (≥ 1.0). Always OK for FIXED_PRICE or when nothing is funded.
​
fundedVolume
number
Total volume (hours or labels) across funded and completed milestones.
​
fundedAmountUsd
number
Total USD across those milestones.
​
consumed
object
Raw consumption totals across all reported usage and OpenTrain first-party work: seconds, hours, labels, tasks.
​
consumedVolume
number
Consumption in the contract’s volume unit — hours for PAY_PER_HOUR, labels for PAY_PER_LABEL.
​
remainingVolume
number
fundedVolume - consumedVolume, floored at 0.
​
consumedFraction
number
consumedVolume / fundedVolume, rounded to 4 decimals. 0 when nothing is funded.
​
activeMilestone
object | null
The current funded milestone (id, name, amountUsd, volume, status), or null if none is active.
​
lastUsageAt
string | null
ISO 8601 timestamp of the most recent usage report or first-party work record — null if no work has been recorded.

​
Errors

StatuscodeMeaning
401UNAUTHORIZEDMissing, invalid, or revoked token
403FORBIDDENToken lacks contracts:read
404NOT_FOUNDContract not found, or its job is not linked by this install
curl -sS "https://app.opentrain.ai/api/partner/v1/contracts/<CONTRACT_ID>/budget" \
  -H "Authorization: Bearer $OT_PARTNER_TOKEN"

{
  "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"
}