List Contracts

Lists the contracts on your account — one per hired AI trainer per job — newest first, each with its milestone timeline. Contracts are created by hiring from a proposal. The AI trainer’s identity stays masked: first name + last initial, country, and profile path (never a full last name or an email — see privacy).

Refunded and cancelled milestones are excluded from the milestone timeline, mirroring the in-app contract view. For the post-hire conversation ID, read a single contract with GET /contracts/{id}.

Requirements: payments:read scope. Works pre-claim.

Request

jobIdstringquery

Only return contracts on this job. Must be a job you own or can access (403 otherwise; 404 if the job doesn’t exist).

statusstringquery

Filter by contract status: active or ended. Omit to list both.

Response

contractsobject[]

contract entry

idstring

Contract ID — use with GET /contracts/{id}, POST /contracts/{id}/milestones, and POST /contracts/{id}/end.

statusstring

active or ended.

titlestring | null

Contract display title.

jobIdstring | null

The job this contract belongs to.

proposalIdstring | null

The proposal the hire came from.

paymentTypestring | null

Payment model: FIXED_PRICE, PAY_PER_HOUR, or PAY_PER_LABEL.

rateUsdnumber | null

Contract rate in USD (per hour / per label for per-unit contracts; total for fixed-price).

estimatedTotalUsdnumber | null

Estimated total contract value in USD.

estimatedVolumenumber | null

Estimated unit volume for per-unit contracts.

hasActiveMilestoneboolean

true when the contract currently has a funded, in-progress milestone.

startDatestring | null

ISO contract start timestamp.

endDatestring | null

ISO contract end timestamp, null while active.

createdAtstring

ISO creation timestamp.

updatedAtstring

ISO last-change timestamp.

freelancerobject

The hired AI trainer: {userId, displayName, country, profilePath}. displayName is masked to first name + last initial ("Maria G."); full last names and emails are never included.

milestonesobject[]

Milestone timeline, ordered by milestone number.

milestone entry

idstring

Milestone ID — use with POST /milestones/{id}/fund and POST /milestones/{id}/approve.

namestring | null

Short milestone name.

descriptionstring | null

Work to deliver.

statusstring | null

NOT_FUNDED, ACTIVE_FUNDED, or COMPLETED.

amountUsdnumber | null

Milestone amount in USD.

volumenumber | null

Unit volume for per-unit milestones.

milestoneNumbernumber | null

Position in the contract’s milestone sequence.

dueDatestring | null

ISO due date.

pendingApprovalboolean

true when the AI trainer has submitted work and the milestone awaits your approval.

needsReviewboolean

true when the milestone is flagged for review.

invoiceIdstring | null

Linked invoice once funded/paid.

createdAtstring

ISO creation timestamp.

Errors

Status	code	Meaning
400	BAD_REQUEST	status is not active or ended (details: {field: "status"})
401	UNAUTHORIZED	Missing or invalid token
403	FORBIDDEN	Missing payments:read scope, or jobId belongs to another account
404	NOT_FOUND	jobId does not exist

Request examples

curlCLIMCP: opentrain_list_contracts

curl

curl -sS "https://app.opentrain.ai/api/public/v1/contracts?status=active" \
  -H "Authorization: Bearer $OT_API_TOKEN"

CLI

opentrain contracts list --status active --json

MCP: opentrain_list_contracts

{
  "status": "active"
}

Response examples

200

{
  "contracts": [
    {
      "id": "<CONTRACT_ID>",
      "status": "active",
      "title": "Spanish Sentiment Labeling Contract",
      "jobId": "<JOB_ID>",
      "proposalId": "<PROPOSAL_ID>",
      "paymentType": "FIXED_PRICE",
      "rateUsd": 300,
      "estimatedTotalUsd": 300,
      "estimatedVolume": null,
      "hasActiveMilestone": true,
      "startDate": "2026-06-12T09:30:00.000Z",
      "endDate": null,
      "createdAt": "2026-06-12T09:30:00.000Z",
      "updatedAt": "2026-06-12T09:30:00.000Z",
      "freelancer": {
        "userId": "<FREELANCER_ID>",
        "displayName": "Maria G.",
        "country": "Spain",
        "profilePath": "/profile/maria-g"
      },
      "milestones": [
        {
          "id": "<MILESTONE_ID>",
          "name": "First labeling batch",
          "description": "Label the first 5,000 posts per the guidelines",
          "status": "ACTIVE_FUNDED",
          "amountUsd": 300,
          "volume": null,
          "milestoneNumber": 1,
          "dueDate": "2026-07-01T00:00:00.000Z",
          "pendingApproval": false,
          "needsReview": false,
          "invoiceId": "<INVOICE_ID>",
          "createdAt": "2026-06-12T09:30:00.000Z"
        }
      ]
    }
  ]
}