Report Usage

Reports work done on your platform against an OpenTrain contract. Entries are cumulative per-worker, per-day totals: each entry replaces the stored totals for its (worker, workDate), so re-POSTing the same report — or a corrected one — is idempotent and never double counts. Fields omitted from an entry keep their previously stored values.

The response includes the recomputed budget. Crossing the 80% / 100% consumption thresholds emits milestone.budget_low / milestone.budget_depleted webhooks.

Requirements: usage:write 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 attribute usage to.

entriesobject[]bodyrequired

1–100 usage entries. One entry per (worker, day).

Entry fields

workDatestringbodyrequired

Calendar day the work happened, as YYYY-MM-DD (UTC). Cannot be in the future.

workerOpentrainUserIdstringbody

OpenTrain user ID of the worker. Defaults to the contract’s hired AI trainer; if provided, it must match a participant on the contract.

totalSecondsnumberbody

Cumulative seconds worked that day, 0–86400. Consumes budget on PAY_PER_HOUR contracts (hours = seconds / 3600).

tasksCompletedintegerbody

Cumulative tasks completed that day. Non-negative. Informational on all payment types.

labelsCompletedintegerbody

Cumulative labels completed that day. Non-negative. Consumes budget on PAY_PER_LABEL contracts.

externalReportIdstringbody

Your report identifier for audit, max 200 characters.

Response

contractIdstring

The contract the usage was recorded against.

acceptedinteger

Number of entries upserted.

budgetobject

The recomputed budget — same shape as GET /contracts/{contractId}/budget.

Errors

Status	code	Meaning
400	BAD_REQUEST	Invalid entries: missing/malformed workDate, future date, totalSeconds out of range, negative counts, more than 100 entries, or workerOpentrainUserId not a participant on this contract
401	UNAUTHORIZED	Missing, invalid, or revoked token
403	FORBIDDEN	Token lacks usage:write
404	NOT_FOUND	Contract not found, or its job is not linked by this install
409	CONFLICT	Contract has no hired AI trainer to attribute usage to

Request examples

curl

curl -sS -X POST "https://app.opentrain.ai/api/partner/v1/contracts/<CONTRACT_ID>/usage" \
  -H "Authorization: Bearer $OT_PARTNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [
      {
        "workDate": "2026-06-12",
        "totalSeconds": 14400,
        "tasksCompleted": 52,
        "labelsCompleted": 410,
        "externalReportId": "daily-report-8841"
      }
    ]
  }'

Response examples

200

{
  "contractId": "<CONTRACT_ID>",
  "accepted": 1,
  "budget": {
    "contractId": "<CONTRACT_ID>",
    "paymentType": "PAY_PER_HOUR",
    "state": "OK",
    "fundedVolume": 40,
    "fundedAmountUsd": 560,
    "consumed": { "seconds": 100800, "hours": 28, "labels": 410, "tasks": 52 },
    "consumedVolume": 28,
    "remainingVolume": 12,
    "consumedFraction": 0.7,
    "activeMilestone": {
      "id": "<MILESTONE_ID>",
      "name": "Week 2",
      "amountUsd": 280,
      "volume": 20,
      "status": "ACTIVE_FUNDED"
    },
    "lastUsageAt": "2026-06-12T18:00:00.000Z"
  }
}