playtable_runs

Create playtable run

The single entry point for every bulk operation on a playtable. Async: the created row is the progress handle: poll get_playtable_run with include progress every ~5s until progress.state is finished or cancelled.

type branches the body. enrich is the only paid type (action columns over the scope; a formula column never runs, it fills through backfill_playtable_field): always estimate_playtable_run first, tell the user the cost range and set max_budget to its cost_max (exhaustion auto-cancels, reason budget_exhausted; a cap at cost_expected cancels a row short); params force_rerun re-queues done cells (re-charge consent), params cells not_run | error narrows to those. export writes the scope to CSV (params format csv, a file_url) or an external tool (write_tool_sid). import batch-promotes a data source (params data_source_sid, no scope). bulk runs tag, field, workflow, move and delete edits (params operation).

scope, required for enrich, export and bulk: one form, object_sids or view_sid/filter; an empty filter is rejected, the scope is snapshotted at create; hand-picked object_sids and exclude_object_sids are capped at 10 000 each (422 scope_too_large). 409 conflict when a field already has an active run (its sid in error.context), 429 at the team concurrency cap; already_exists is always false. When NOT: single-cell fixes (update_playtable_field_value); continuous source syncing (data sources; import here is a one-shot promotion).

Contract:

  • MCP tool create_playtable_run, registry package mcp.playtables/playtable_runs, mount playtables.columns.
  • Operation create, response envelope create.
  • Flags: none.
post/api/playtable-runs

Request

  • Base URL
    https://beta.getsales.io/playtables/v1
  • Auth
    HTTP bearer and API key in header Team-SID

Request body

playtable_sidstring required

Parent playtable sid (pt_tb_…).

object_type'people' | 'company' required

Which tab the run targets: people | company.

type'enrich' | 'export' | 'import' | 'bulk' required

enrich (PAID - estimate first, set max_budget) | export | import | bulk. Branches which fields below are required.

field_sidsstring[]

REQUIRED for type=enrich, forbidden otherwise (422): 1..20 action columns (a widget, a plain column or a formula column is 422; a formula column fills through backfill_playtable_field instead).

max_budgetnumber nullable

Decimal credits - enrich only: hard per-run spend cap; the budget guard cancels the run when exhausted (reason=budget_exhausted). Omit/null = uncapped. Base it on the estimate cost range.

Response

create success envelope.

successtrue required
operation'create' required
already_existsboolean required

Changes

No recorded changes to this operation across all 1 revision of this API.