---
title: "Estimate playtable field backfill"
method: POST
path: "/api/playtable-fields/estimate-backfill"
tags: ["playtable_fields"]
---

# Estimate playtable field backfill

`POST /api/playtable-fields/estimate-backfill`

## Request

- Base URL: `https://beta.getsales.io/playtables/v1`
- URL: `https://beta.getsales.io/playtables/v1/api/playtable-fields/estimate-backfill`
- Auth: HTTP bearer and API key in header `Team-SID`

How long a formula column's fill over this grid takes before the save, in seconds: the rows the pass walks, the measured rate one worker sustains and whether the drawer should ask the person first (needs_confirm, above five minutes by default). Two counts, no writes; the fill itself is never gated by it, so a plan builds the column and reads the number.

Contract:
- MCP tool `estimate_playtable_field_backfill`, registry package `mcp.playtables/playtable_fields`, mount `playtables.columns`.
- Operation `action`, response envelope `action`.
- Flags: read only.

## Request body

- EstimatePlaytableFieldBackfillRequest: Request body of `estimate_playtable_field_backfill`.
  - `playtable_sid` string, required: The table (pt_tb_…); 404 not_found outside the caller's team.
  - `object_type` 'people' | 'company', required: The grid the column sits on: people or company.
  - `columns` integer: Columns the save queues at once (a pass computes them in one walk, so the seconds add up). Default 1.

## Response `200`

`action` success envelope.

- EstimatePlaytableFieldBackfillResponse
  - `success` true, required
  - `operation` 'action', required
  - `action` string, required: kebab-case verb; matches the route segment.
  - `item` unknown, required
  - `result` object, required
    - `rows` integer, required: The rows of the grid the pass walks.
    - `columns` integer, required: As asked.
    - `seconds_expected` integer, required: ceil(rows x columns / cells_a_second): one worker's wall time.
    - `cells_a_second` integer, required: The rate used (playtables.runs.estimate_cells_per_second).
    - `confirm_above_seconds` integer, required: The drawer asks the person first above this many seconds; 0 means never.
    - `needs_confirm` boolean, required: seconds_expected > confirm_above_seconds.
  - `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)