Skip to content
Shortcut: /, ⌘K or Ctrl+K

Operations

List, inspect, wait for, and cancel asynchronous team and project operations.

View as Markdown

Some requests start work that finishes later, such as a campaign send or a production enrollment. Polymorfa tracks that work as an operation. The request that starts it returns an operationId, and the operations routes of the Platform API report its progress:

HTTP
GET  /platform/operations
GET  /platform/operations/{operationId}
GET  /platform/operations/{operationId}/transitions
POST /platform/operations/{operationId}/cancel

Reads require operations:read. Cancellation requires operations:cancel.

A team API key sees team-owned operations and the operations of every project in the team. A project token sees only its own project's operations. When a project token asks for another project, or for an operation outside its project, the API returns 404.

Each route also has a project form under API List project operations, which addresses exactly one project.

Operation fields#

FieldMeaning
idOperation ID.
projectIdOwning project, or null for a team-owned operation.
kindWhat the operation does, for example campaign or production_enrollment.
resourceThe type and id of the resource the operation acts on.
statuspending, running, action_required, cancelling, succeeded, failed, or cancelled.
sequenceIncreases by one on every status transition.
capabilities.cancellabletrue when the operation accepts cancellation right now.
progressThe latest progress code, or null.
errorThe failure code when status is failed, or null.
actionRequiredWhat the operation is waiting for when status is action_required.

succeeded, failed, and cancelled are terminal. A terminal operation doesn't change again.

List operations#

List results come newest first. Filter by projectId, status, kind, resourceType with resourceId, since, and exclusive until:

cURL
curl "https://api.polymorfa.com/platform/operations?status=running&resourceType=campaign&resourceId=$CAMPAIGN_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
TypeScript
for await (const running of await platform.operations.list({ status: "running" })) {
  console.log(running.id, running.kind, running.status);
}

TypeScript:

get(id) reads one operation. The loop fetches the next pages for you.

A page holds at most 100 operations. When more remain, page.nextCursor is set. The cursor carries the filters and the project of the page that issued it, so send it with limit only. Adding a filter, or sending it with a different project, returns 400.

Wait for an operation #

Add wait to hold the request open until something changes. wait accepts 0 to 30 seconds:

cURL
curl "https://api.polymorfa.com/platform/operations/$OPERATION_ID?wait=30" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
TypeScript
const operation = await platform.operations.wait("<operation-id>", {
  maxWaitMs: 10 * 60_000,
});

if (operation.data.status !== "succeeded") {
  console.error(operation.data.status, operation.data.error?.code);
}

TypeScript:

operations.wait returns when the operation succeeds, fails or is cancelled, or when maxWaitMs ends (5 minutes by default).

It returns the latest state either way, so always check status. For one long poll, pass { wait: 30 } to get(id).

The API responds as soon as one of these is true:

  • the operation reaches a terminal status;
  • afterSequence is set and the operation's sequence is greater than it; or
  • the wait ends.

The response is always the operation's state at that moment, with status 200. Check status before you act: an expired wait returns a non-terminal operation. To follow each transition, send the last sequence you saw as afterSequence on the next request.

Read the transition history#

API List operation transitions lists every status change in ascending sequence order, with the progress, error, and action-required snapshot recorded at that transition. In the SDK, call operations.listTransitions(id).

Cancel an operation#

Only running or action-required campaign and production-enrollment operations accept cancellation. Check capabilities.cancellable first, then send an Idempotency-Key:

cURL
curl -X POST "https://api.polymorfa.com/platform/operations/$OPERATION_ID/cancel" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Idempotency-Key: cancel-$OPERATION_ID"
TypeScript
for await (const running of await platform.operations.list({ status: "running" })) {
  if (running.capabilities.cancellable) {
    await platform.operations.cancel(running.id);
  }
}

TypeScript:

cancel creates an idempotency key for each call when you pass none.

The operation moves to cancelling and later reaches cancelled, or another terminal status if it finished first. Wait for it as shown above.

ResponseMeaning
200Cancellation was accepted. The receipt contains the updated operation. A retry with the same key returns the same receipt with idempotency.replayed: true.
404The operation doesn't exist in your team or project.
409 operation_conflictThe operation can't be cancelled now. The body contains the current operation.
422 idempotency_conflictThe key was already used for a different request on this route. Keys are scoped to the route you call.

CLI and MCP#

  • The CLI provides polymorfa operation list, view, wait, watch, and cancel. wait and watch exit 0 when the operation succeeds, 1 when it fails or is cancelled, and 8 when --timeout ends first.
  • The MCP server provides operations_list, operations_get, and operations_wait. It doesn't cancel operations.