Report Usage

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"
      }
    ]
  }'

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

POST

api

partner

contracts

{contractId}

usage

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"
      }
    ]
  }'

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

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

contractId

string

required

The OpenTrain contract to attribute usage to.

entries

object[]

required

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

Show Entry fields

workDate

string

required

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

workerOpentrainUserId

string

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

totalSeconds

number

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

tasksCompleted

integer

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

labelsCompleted

integer

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

externalReportId

string

Your report identifier for audit, max 200 characters.

Response

contractId

string

The contract the usage was recorded against.

accepted

integer

Number of entries upserted.

budget

object

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

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"
      }
    ]
  }'

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

Get Contract Budget

List Webhook Endpoints

⌘I

Getting started

Connect your agent

Core concepts

Guides

API reference

CLI

MCP server

Annotation platforms

Request

Response

Errors

​Request

​Response

​Errors

Request

Response

Errors