Poll Updates

Fetches everything that happened on your account since your last poll in one cheap call, instead of re-reading every resource. Events are returned oldest first; pass the returned nextCursor on the next poll to receive only newer events. Payloads carry IDs only — fetch details with the matching read endpoint.

Webhooks push these same events; the recommended architecture uses the webhook as the trigger and this feed as the source of truth — see stay in sync. For tokenless public marketplace changes, use GET /jobs/changes instead.

Requirements: at least one of proposals:read, messages:read, or payments:read — each event type is visible only with its scope (below). Works pre-claim.

Event types

type	Required scope	Key data fields
proposal.received	proposals:read	proposalId, jobId
proposal.status_changed	proposals:read	proposalId, status
message.received	messages:read	conversationId, messageId
contract.created	payments:read	contractId, jobId, proposalId
milestone.status_changed	payments:read	milestoneId, contractId, status
payment.pending	payments:read	invoiceId, milestoneId, contractId
approval.confirmed	payments:read	approvalId, status
contract.budget_state_changed	payments:read	contractId, previousState, state, paymentType, fundedVolume, consumedVolume, remainingVolume, consumedFraction

Event types your token cannot read are silently filtered out of the feed; they are not an error. A token with none of the three scopes gets 403.

Request

cursorstringquery

The nextCursor from your previous poll (a numeric event ID). Omit on the first poll to start from the beginning of your account’s event history.

limitintegerquery

Default: 50

Max events to return, 1–200.

Response

eventsobject[]

event

idstring

Monotonically increasing numeric event ID — this is what cursors point at.

typestring

One of the eight event types above.

apiVersionstring

v1.

createdAtstring

ISO timestamp of the event.

resourceIdstring

ID of the primary affected resource (e.g. the proposal ID for proposal.received).

jobIdstring | null

The related job, when the event is job-linked.

dataobject

IDs-only payload (see the table above) — never message bodies or other content.

nextCursorstring | null

Persist this and pass it as cursor on the next poll. When the page is empty it echoes your input cursor (null on a first poll with no events).

hasMoreboolean

true when more events already exist beyond this page — poll again immediately with nextCursor.

Errors

Status	code	Meaning
400	BAD_REQUEST	cursor is not a numeric event ID (details.field: "cursor"), or limit outside 1–200 (details.field: "limit")
401	UNAUTHORIZED	Missing or invalid token
403	FORBIDDEN	Token has none of proposals:read, messages:read, payments:read (details.requiredScopes, details.grantedScopes)

Request examples

curlCLIMCP: opentrain_poll_updates

curl

curl -sS "https://app.opentrain.ai/api/public/v1/updates?cursor=$LAST_CURSOR&limit=50" \
  -H "Authorization: Bearer $OT_API_TOKEN"

CLI

opentrain updates poll --cursor <LAST_CURSOR> --json

MCP: opentrain_poll_updates

{
  "cursor": "<LAST_CURSOR>"
}

Response examples

200

{
  "events": [
    {
      "id": "1042",
      "type": "proposal.received",
      "apiVersion": "v1",
      "createdAt": "2026-06-12T10:00:00.000Z",
      "resourceId": "<PROPOSAL_ID>",
      "jobId": "<JOB_ID>",
      "data": {
        "proposalId": "<PROPOSAL_ID>",
        "jobId": "<JOB_ID>"
      }
    },
    {
      "id": "1043",
      "type": "approval.confirmed",
      "apiVersion": "v1",
      "createdAt": "2026-06-12T10:05:00.000Z",
      "resourceId": "<APPROVAL_ID>",
      "jobId": "<JOB_ID>",
      "data": {
        "approvalId": "<APPROVAL_ID>",
        "status": "confirmed"
      }
    }
  ],
  "nextCursor": "1043",
  "hasMore": false
}