Cancel pending (and optionally running) migration jobs for an entity

Operational queue cleanup. Sets status='cancelled' on every pending migration job for the entity, and (optionally) every running job. A cancelled job is distinct from a failed job: monitoring should not treat it as an error, and the audit reason is recorded in the job’s errors[] JSONB so the cancellation context is preserved.

Common use cases:

• The entity is being abandoned for a fresh entity, so the queue is contaminated.
• A buggy bulk-submit needs to be drained before a clean re-run.
• The runner is being redeployed and in-flight jobs should not be claimed mid-update.

Body parameters.

• reason (optional string) — audit note stored in each cancelled job’s errors array. Defaults to "admin_cancelled".
• include_running (optional boolean) — also cancel running jobs. Default false. Risky for live runs (cancels in-flight work); use only when you’ve confirmed nothing meaningful is in flight.

Scope: migration:write.

POST /entities/{entity_id}/migration/jobs/cancel

cURL

cleanup

curl --request POST \
  --url https://api.arcuserp.com/v1/entities/{entity_id}/migration/jobs/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "queue_cleanup_2026_05_22_abandoned_for_new_entity"
}
'

200

{
  "object": "migration_jobs_cancel_result",
  "entity_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "cancelled": 123,
  "job_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "reason": "<string>",
  "include_running": true
}

Authorizations

Authorization · string · header · required

API key issued per entity via Settings > Developers > API Keys. Each key carries scopes (e.g. orders:read, products:write). Bearer token format: Authorization: Bearer ark_live_ent_Test keys use ark_test_ent_. Both are issued per entity
via Settings > Developers > API Keys.

Path Parameters

entity_id · string<uuid> · required

Body

application/json

reason · string

Audit note stored in each cancelled job's errors[] JSONB. Defaults to 'admin_cancelled'.

Example:

"queue_cleanup_after_entity_abandoned"

include_running · boolean · default: false

Also cancel 'running' jobs. Default false. Risky for live runs.

Example:

false

Response

200

application/json

Cancel result with the list of cancelled job IDs

object · enum<string>

Available options: migration_jobs_cancel_result

entity_id · string<uuid>

cancelled · integer

Number of jobs transitioned to 'cancelled'.

job_ids · string<uuid>[]

IDs of jobs that were cancelled (in created_at order).

reason · string

include_running · boolean