Skip to main content

​
Cancel Process

Use POST /processes/{process_id}/cancel to request process-aware cancellation. 
POST /processes/{process_id}/cancel

​
When To Use It

Use this endpoint when you need cancellation semantics for the public process model. This is not the same as the legacy queue-item POST /cancel endpoint.

​
Request Example

curl -X POST "$PHONEFARM_BASE_URL/processes/$PROCESS_ID/cancel" \
  -H "Authorization: Bearer $PHONEFARM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "operator requested stop",
    "strategy": "soft_then_force",
    "force_after_seconds": 10,
    "requested_by": {
      "system": "ugc-tracker",
      "user": "operator@example.com",
      "metadata": {}
    }
  }'

​
Request Fields

FieldTypeRequiredNotes
reasonstringyesHuman-readable cancel reason.
requested_byobjectyesCaller identity payload.
strategystringnosoft, hard, or soft_then_force. Defaults to soft_then_force.
force_after_secondsintegernoDefaults to 10. Must be >= 0.

​
Strategies

StrategyMeaning
softMark work cancelled and rely on cooperative stop behavior only.
hardIssue immediate termination against active executing work when available.
soft_then_forceRequest cooperative stop first, then escalate after the delay window.

​
Response Example

{
  "status": "cancel_requested",
  "cancelled_queue_item_ids": ["7c1a07f6-1d55-4f79-a403-8a8420f1b62b"],
  "active_queue_item_ids": [],
  "active_target": {
    "process_id": "3e6f2e7b-4e3c-4c7c-b8d7-0c53d83f9870",
    "phone_id": "phone_01",
    "account_id": "account_user095916355",
    "queue_item_id": null,
    "capability_request_id": "3e6f2e7b-4e3c-4c7c-b8d7-0c53d83f9870"
  },
  "termination": {
    "process_id": "3e6f2e7b-4e3c-4c7c-b8d7-0c53d83f9870",
    "status": "not_needed",
    "terminate_issued": false,
    "container": null
  },
  "process": {
    "process_id": "3e6f2e7b-4e3c-4c7c-b8d7-0c53d83f9870",
    "status": "cancelled"
  }
}

​
Behavior Notes

  • Terminal processes return ignored_terminal.
  • Pending child queue items are cancelled immediately when eligible.
  • Executing work may require control-plane termination depending on strategy and current runtime state.
  • Public callers should treat cancel as a state transition request and re-read the returned process object.

​
Idempotency

This endpoint is stateful rather than idempotent-by-key. Repeated requests may produce different results based on current process state.

​
Failure Modes

Status codeMeaning
401Missing or invalid bearer token.
404Process not found.
422Invalid payload, unknown strategy, or invalid force_after_seconds.
500Unexpected cancellation error.