---
title: "Stop the runs of a playtable"
method: POST
path: "/api/playtables/{sid}/cancel-runs"
tags: ["playtables"]
---

# Stop the runs of a playtable

`POST /api/playtables/{sid}/cancel-runs`

## Request

- Base URL: `https://beta.getsales.io/playtables/v1`
- URL: `https://beta.getsales.io/playtables/v1/api/playtables/{sid}/cancel-runs`
- Auth: HTTP bearer and API key in header `Team-SID`

Stop everything running on one table (Stop all): every unfinished run of it, on every tab, active and waiting, is cancelled through the runs' cancel, waiting ones first. Queued cells go back; cells a worker holds finish and are charged (in_flight_cells_count); no refunds. Call with dry_run:true first and tell the user the numbers. Nothing running: runs []. Formula fills are not runs. One column: cancel_playtable_field_runs; one run: cancel_playtable_run (both on /mcp/playtables/columns).

Contract:
- MCP tool `cancel_playtable_runs`, registry package `mcp.playtables/playtables`, mount `playtables.tables`.
- Operation `action`, response envelope `action`.
- Flags: dangerous: the MCP layer gates it behind a preview/commit token, and the effect cannot be undone through this API.

## Path parameters

- `sid` string, required: The table (pt_tb_…) whose runs stop, every tab of it. Another team's is 403.

## Request body

- CancelPlaytableRunsRequest: Request body of `cancel_playtable_runs`.
  - `dry_run` boolean: true: answer the counts (the runs, the queued cells that would go back, the cells still running that finish and are charged) and cancel nothing. Call it first and tell the user the numbers; then call without it.

## Response `200`

`action` success envelope.

- CancelPlaytableRunsResponse
  - `success` true, required
  - `operation` 'action', required
  - `action` string, required: kebab-case verb; matches the route segment.
  - `item` object, nullable, required
    - `sid` string, required
    - `team_sid` string, required
    - `name` string, required
    - `description` string, nullable, required
    - `agent_sid` string, nullable, required: The AI SDR picked for this table (ub_ag_…, block 10 step 10.2): the agent that works every thread of its people, every setting on the agent itself (its Brief, goal, link, scenarios: update_agent). Null = the team's default agent, whichever it is. The table's own setup of before (ai_sdr_setup, 2026-10-12 to 2026-10-30) became an agent of its own in step 10.3.
    - `company_default_view_sid` string, required: pt_vw_… default view of the companies tab; auto-created with the table, read-only.
    - `people_default_view_sid` string, required: pt_vw_… default view of the people tab; auto-created with the table, read-only.
    - `config` object, required
      - `auto_run` boolean, required: When true, action fields fire automatically on rows entering the table (empty→queued). Default false.
    - `created_by` object, required
      - `actor_type` 'user' | 'support' | 'api_key' | 'system' | 'agent', required
      - `actor_sid` string, nullable, required
      - `team_sid` string, required
      - `actor_name` string, nullable: The OAuth client that acted ("Claude", "n8n"); null for a user, an API key or a system job.
      - `oauth_client_sid` string, nullable: The acting OAuth client (id_oc_*); null off the OAuth path.
      - `reason` string, nullable: Why a system actor wrote the row (snapshot_capture_job, ...); null otherwise.
      - `permissions` object, required: Internal audit context: the grant set the actor held at write time. Not a contract.
      - `cluster_id` integer, nullable: Internal audit context: the cluster that served the write.
      - `trace_id` string, nullable: Internal audit context: the trace id of the request that wrote the row.
    - `deleted_by` object, nullable, required
      - `actor_type` 'user' | 'support' | 'api_key' | 'system' | 'agent', required
      - `actor_sid` string, nullable, required
      - `team_sid` string, required
      - `actor_name` string, nullable: The OAuth client that acted ("Claude", "n8n"); null for a user, an API key or a system job.
      - `oauth_client_sid` string, nullable: The acting OAuth client (id_oc_*); null off the OAuth path.
      - `reason` string, nullable: Why a system actor wrote the row (snapshot_capture_job, ...); null otherwise.
      - `permissions` object, required: Internal audit context: the grant set the actor held at write time. Not a contract.
      - `cluster_id` integer, nullable: Internal audit context: the cluster that served the write.
      - `trace_id` string, nullable: Internal audit context: the trace id of the request that wrote the row.
    - `created_at` string, required
    - `updated_at` string, required
    - `deleted_at` string, nullable, required
  - `result` object, required
    - `dry_run` boolean, required: true: the counts below are what a stop WOULD do; nothing was cancelled.
    - `runs` object[], required: The unfinished runs found, in the order they were stopped: the waiting ones first, then the dispatched ones.
      - `sid` string, required: Playtable run sid (pt_rn_…).
      - `waiting` boolean, required: true: the run held no batch yet (it waited behind another run on its field).
      - `reverted_cells_count` integer, required: Its queued cells sent back (on a dry run: the ones that would be).
      - `in_flight_cells_count` integer, required: Its cells a worker holds right now: they finish and are charged either way.
    - `cancelled_count` integer, required: Runs this call cancelled (0 on a dry run; a run that ended on its own meanwhile is not counted).
    - `reverted_cells_count` integer, required: Queued cells sent back, summed over the runs (no prior value → empty, a prior value → done).
    - `in_flight_cells_count` integer, required: Cells still running, summed over the runs: they finish and are charged. Say so to the user before the stop.
    - `spent_credits` number, required: The runs' spend so far, summed; the in-flight cells may still add to it (the ledger is truth).
  - `meta` object, required
    - `trace_id` string, required: UUID v7; same 128-bit value as the X-Trace-Id header.
    - `span_id` string, required: 16 hex chars, root span of this request.
    - `timestamp` string, required: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
    - `duration_ms` integer, required: Server-side wall clock.
    - `team_sid` string, nullable: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends.
    - `actor_type` string, nullable: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends.

## Other responses

- `4XX`: MCP error envelope. `error.code` is one of validation_failed, nothing_to_update, not_found, relation_not_found, invalid_transition, limit_exceeded, payment_required, duplicate_rejected, conflict, delete_blocked, unauthorized, forbidden, rate_limited, not_implemented.
- `5XX`: MCP error envelope with `error.code` internal_error or service_unavailable.

---

[API](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-playtables.md) - [All operations](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-playtables/llms.txt) - [OpenAPI document](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-playtables/revisions/aa394506515d?raw)