> ## Documentation Index > Fetch the complete documentation index at: https://docs.getsales.io/llms.txt > Use this file to discover all available pages before exploring further. # Estimate playtable run cost > Dry-run pricing for an enrich run - THE money-honesty gate (§4.6): call it BEFORE any paid create_playtable_run(type:"enrich") and surface the range to the user. Resolves the scope row count per field (ES run_condition prefilter - approximate by design, the worker re-checks per cell; done cells are skipped unless force_rerun:true = re-charge consent; cells:not_run | error prices only the cells that have not run or only the error ones) and prices each field's materialized waterfall from the cached gtm-api tool registry. Returns rows_matched, cost_min (every row succeeds on the cheapest step), cost_max (full waterfall at max prices), cost_expected (registry expected path), priced_at, and a per-field breakdown with per-step price ranges - pass cost_max as max_budget at create (cost_expected is a midpoint, not a cap). No writes, no charges - free to call; free run types (export|import|bulk) have nothing to estimate. Also the answer to "what would it cost to …" - estimate only, no run. A view/filter scope is priced by count (rows_matched = the ES count; rows_to_run per field subtracts the rows already done unless force_rerun, or counts the error rows by id under cells), so any size prices instantly and rows_matched is never a truncated number. Contract: - MCP tool `estimate_playtable_run`, registry package `mcp.playtables/playtable_runs`, mount `playtables.columns`. - Operation `action`, response envelope `action`. - Flags: read only. ## OpenAPI ````yaml /api-reference/playtables/openapi.yaml post /api/playtable-runs/estimate openapi: 3.0.3 info: title: 'GetSales public contract: gs.service.playtables' description: >- The data platform and the outreach engine: tables of people and companies, their enrichment columns, cells and runs, the data sources that feed them, sender profiles, the stoplist, the activity feed, the credit ledger, and the multichannel workflows with their per-person journeys and tasks. GENERATED. This document is projected from the Zod MCP tool registry in `product/mcp/gs.mcp` (one tool per public endpoint, 1:1). Do not edit it by hand; edit the tool definition and regenerate with `pnpm openapi:public`. Surface: the public `/api` contract of `gs.service.playtables`, 142 operations. This is the only OpenAPI document the platform publishes. Internal (`/internal`) and health endpoints are deliberately absent: they are not part of any contract, they can change without notice, and the service source is their only description. Conventions: - Auth is a bearer JWT, optionally narrowed by the `Team-SID` header. - Every success body is an MCP envelope: `success: true` plus one typed `operation` shape (`search`, `get`, `create`, `update`, `delete`, `metrics`, `group_by`, `action`), and a `meta` block with `trace_id` for support. - Every failure is the same `McpError` envelope with a code from a fixed 16-code taxonomy, so a client maps errors once. - Lists page with `page_size` (0 to 500, default 50) plus an opaque forward `cursor`; `page_size: 0` returns counts only. - On `GET` and `DELETE`, object-valued query parameters (`filter`, `sort`) travel as JSON text and array-valued ones repeat as `name[]=value`. - The MCP-only `_meta` field (usage analytics) never reaches the backend and is not part of this contract. version: '1.0' contact: name: GetSales url: https://getsales.io email: support@getsales.io license: name: Proprietary url: https://getsales.io/terms servers: - url: https://beta.getsales.io/playtables/v1 description: >- Production (the gateway path on the beta ring; the origin is provisioned per DEPLOY_MAP.md) security: - BearerJwt: [] TeamSid: [] tags: - name: activities description: >- Registry package `mcp.playtables/activities`, served on MCP mount `playtables.journeys`. - name: activity_objects description: >- Registry package `mcp.playtables/activity_objects`, served on MCP mount `playtables.people`. - name: companies description: >- Registry package `mcp.playtables/companies`, served on MCP mount `playtables.people`. - name: credit_ledger_entries description: >- Registry package `mcp.playtables/credit_ledger_entries`, served on MCP mount `id.billing`. - name: data_source_items description: >- Registry package `mcp.playtables/data_source_items`, served on MCP mount `playtables.sources`. - name: data_sources description: >- Registry package `mcp.playtables/data_sources`, served on MCP mount `playtables.sources`. - name: notes description: >- Registry package `mcp.playtables/notes`, served on MCP mount `playtables.pipeline`. - name: people description: >- Registry package `mcp.playtables/people`, served on MCP mount `playtables.people`. - name: pipeline_stages description: >- Registry package `mcp.playtables/pipeline_stages`, served on MCP mount `playtables.pipeline`. - name: plays description: >- Registry package `mcp.playtables/plays`, served on MCP mount `playtables.pipeline`. - name: playtable_field_values description: >- Registry package `mcp.playtables/playtable_field_values`, served on MCP mount `playtables.columns`. - name: playtable_fields description: >- Registry package `mcp.playtables/playtable_fields`, served on MCP mount `playtables.columns`. - name: playtable_runs description: >- Registry package `mcp.playtables/playtable_runs`, served on MCP mount `playtables.columns`. - name: playtable_views description: >- Registry package `mcp.playtables/playtable_views`, served on MCP mount `playtables.tables`. - name: playtables description: >- Registry package `mcp.playtables/playtables`, served on MCP mount `playtables.tables`. - name: result_pages description: >- Registry package `mcp.playtables/result_pages`, served on MCP mount `playtables.tables`. - name: sender_profiles description: >- Registry package `mcp.playtables/sender_profiles`, served on MCP mount `playtables.sources`. - name: stoplist_entries description: >- Registry package `mcp.playtables/stoplist_entries`, served on MCP mount `playtables.stoplist`. - name: tags description: >- Registry package `mcp.playtables/tags`, served on MCP mount `playtables.pipeline`. - name: workflow_attachments description: >- Registry package `mcp.playtables/workflow_attachments`, served on MCP mount `playtables.workflows`. - name: workflow_records description: >- Registry package `mcp.playtables/workflow_records`, served on MCP mount `playtables.journeys`. - name: workflow_sources description: >- Registry package `mcp.playtables/workflow_sources`, served on MCP mount `playtables.workflows`. - name: workflow_tasks description: >- Registry package `mcp.playtables/workflow_tasks`, served on MCP mount `playtables.journeys`. - name: workflow_versions description: >- Registry package `mcp.playtables/workflow_versions`, served on MCP mount `playtables.workflows`. - name: workflows description: >- Registry package `mcp.playtables/workflows`, served on MCP mount `playtables.workflows`. paths: /api/playtable-runs/estimate: post: tags: - playtable_runs summary: Estimate playtable run cost description: >- Dry-run pricing for an enrich run - THE money-honesty gate (§4.6): call it BEFORE any paid create_playtable_run(type:"enrich") and surface the range to the user. Resolves the scope row count per field (ES run_condition prefilter - approximate by design, the worker re-checks per cell; done cells are skipped unless force_rerun:true = re-charge consent; cells:not_run | error prices only the cells that have not run or only the error ones) and prices each field's materialized waterfall from the cached gtm-api tool registry. Returns rows_matched, cost_min (every row succeeds on the cheapest step), cost_max (full waterfall at max prices), cost_expected (registry expected path), priced_at, and a per-field breakdown with per-step price ranges - pass cost_max as max_budget at create (cost_expected is a midpoint, not a cap). No writes, no charges - free to call; free run types (export|import|bulk) have nothing to estimate. Also the answer to "what would it cost to …" - estimate only, no run. A view/filter scope is priced by count (rows_matched = the ES count; rows_to_run per field subtracts the rows already done unless force_rerun, or counts the error rows by id under cells), so any size prices instantly and rows_matched is never a truncated number. Contract: - MCP tool `estimate_playtable_run`, registry package `mcp.playtables/playtable_runs`, mount `playtables.columns`. - Operation `action`, response envelope `action`. - Flags: read only. operationId: estimate_playtable_run requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EstimatePlaytableRunRequest' responses: '200': description: '`action` success envelope.' content: application/json: schema: $ref: '#/components/schemas/EstimatePlaytableRunResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' components: schemas: EstimatePlaytableRunRequest: type: object description: Request body of `estimate_playtable_run`. properties: playtable_sid: type: string minLength: 18 maxLength: 18 pattern: ^pt_tb_ description: Parent playtable sid (pt_tb_…). object_type: type: string enum: - people - company description: 'Which tab the run would target: people | company.' type: type: string enum: - enrich description: >- The type of the run this prices: enrich, the one paid type, the same word create_playtable_run takes (export, import and bulk have nothing to estimate). Optional; any other word is a 422 here, before the create. field_sids: type: array items: type: string minLength: 18 maxLength: 18 pattern: ^pt_fd_ minItems: 1 maxItems: 20 description: The fields that would run (pt_fd_…, 1..20; action columns only). scope: type: object properties: object_sids: type: array nullable: true items: type: string minLength: 18 maxLength: 18 minItems: 1 description: >- Explicit targets (cr_pp_… / cr_co_… of the run object_type), min 1, max 10 000 (a wider selection is a view/filter, optionally with exclude_object_sids). Exactly one scope form: XOR with view_sid/filter - both or neither → 422. view_sid: type: string nullable: true minLength: 18 maxLength: 18 pattern: ^pt_vw_ description: >- Saved view (pt_vw_…) - its filter AST is snapshotted into the run at create; later view edits do not retarget. Combinable with filter; XOR with object_sids. exclude_object_sids: type: array nullable: true items: type: string minLength: 18 maxLength: 18 maxItems: 10000 description: >- Rows of the view/filter form to leave out (select all minus the unticked rows), at most 10 000; never with object_sids. filter: anyOf: - type: object properties: and: type: array items: type: object additionalProperties: {} description: >- Recursive node: the same object shape repeats here. A static OpenAPI document cannot express the cycle, so this level is documented as an open object. minItems: 1 maxItems: 20 required: - and additionalProperties: false - type: object properties: or: type: array items: type: object additionalProperties: {} description: >- Recursive node: the same object shape repeats here. A static OpenAPI document cannot express the cycle, so this level is documented as an open object. minItems: 1 maxItems: 20 required: - or additionalProperties: false - type: object properties: not: type: object additionalProperties: {} description: >- Recursive node: the same object shape repeats here. A static OpenAPI document cannot express the cycle, so this level is documented as an open object. required: - not additionalProperties: false - type: object properties: any: type: object properties: path: type: string minLength: 1 description: >- Array-valued path - the only way to reach inside an array. where: type: object additionalProperties: {} description: >- Recursive node: the same object shape repeats here. A static OpenAPI document cannot express the cycle, so this level is documented as an open object. required: - path - where additionalProperties: false required: - any additionalProperties: false - type: object properties: field: type: string minLength: 1 description: >- Namespaced path: record. or a built-in object attribute; element-relative inside any.where. op: type: object properties: eq: anyOf: - type: string - type: number - type: boolean ne: anyOf: - type: string - type: number - type: boolean in: type: array items: anyOf: - type: string - type: number - type: boolean minItems: 1 maxItems: 100 nin: type: array items: anyOf: - type: string - type: number - type: boolean minItems: 1 maxItems: 100 gt: anyOf: - type: number - type: string gte: anyOf: - type: number - type: string lt: anyOf: - type: number - type: string lte: anyOf: - type: number - type: string is_null: type: boolean contains: type: string minLength: 1 not_contains: type: string minLength: 1 contains_any: type: array items: type: string minLength: 1 minItems: 1 maxItems: 50 not_contains_any: type: array items: type: string minLength: 1 minItems: 1 maxItems: 50 starts_with: type: string minLength: 1 additionalProperties: false required: - field - op additionalProperties: false - {} description: >- Ad-hoc filter AST over the tab (§4.18 atoms, depth <= 5); stored resolved. Combinable with view_sid; XOR with object_sids. An empty/match-all filter form is rejected. additionalProperties: false description: 'Same XOR rule as create: object_sids XOR view_sid/filter.' force_rerun: type: boolean description: >- Default false - count done cells as re-runnable (they would be re-charged). cells: type: string enum: - not_run - error description: >- Price only the cells that have not run (not_run) or only the error cells (error); the same selection as params.cells on create. required: - playtable_sid - object_type - field_sids - scope EstimatePlaytableRunResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - action action: type: string description: kebab-case verb; matches the route segment. item: {} result: type: object properties: rows_matched: type: number description: >- Scope size (ES count; approximate by design - the worker re-checks per cell). cost_min: type: number description: Credits if every row succeeds on the cheapest step. cost_max: type: number description: Credits if every row walks the full waterfall at max prices. cost_expected: type: number description: Registry expected-price path × rows_to_run. currency: type: string enum: - credits priced_at: type: string description: ISO 8601 UTC - registry price snapshot time. fields: type: array items: type: object properties: playtable_field_sid: type: string rows_to_run: type: number description: >- Rows the run would actually enqueue (run_condition prefilter; skips done unless force_rerun, narrowed by cells). cost_min: type: number cost_max: type: number cost_expected: type: number steps: type: array items: type: object properties: tool_sid: type: string description: gtm-api tool at this waterfall step (external sid). price_min: type: number description: Registry min price per row, credits. price_max: type: number description: Registry max price per row, credits. required: - tool_sid - price_min - price_max description: >- Materialized waterfall with the registry price range per step. required: - playtable_field_sid - rows_to_run - cost_min - cost_max - cost_expected - steps description: Per-field, per-step breakdown. required: - rows_matched - cost_min - cost_max - cost_expected - currency - priced_at - fields meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: string nullable: true description: >- 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: type: string nullable: true description: >- user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - operation - action - item - result - meta McpError: type: object properties: success: type: boolean enum: - false error: type: object properties: code: type: string enum: - 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 - internal_error - service_unavailable - not_implemented message: type: string recoverable: type: boolean suggestion: type: string field_errors: type: object additionalProperties: type: array items: type: object properties: rule: type: string message: type: string required: - rule - message blockers: type: array items: type: object properties: type: type: string description: >- Machine-readable blocker type (active_flow, pending_tasks, …). severity: type: string enum: - hard - soft description: >- hard = external action required; soft = acknowledge is enough. description: type: string entity_sid: type: string nullable: true count: type: integer resolution: type: string description: 'Hard: tool name to call. Soft: code for acknowledge[].' resolution_hint: type: string required: - type - severity - description - entity_sid - resolution - resolution_hint context: type: object additionalProperties: {} required: - code - message - recoverable meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: string nullable: true description: >- 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: type: string nullable: true description: >- user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - error responses: McpClientError: description: >- 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. content: application/json: schema: $ref: '#/components/schemas/McpError' McpServerError: description: >- MCP error envelope with `error.code` internal_error or service_unavailable. content: application/json: schema: $ref: '#/components/schemas/McpError' securitySchemes: BearerJwt: type: http scheme: bearer bearerFormat: JWT description: >- Access token issued by gs.service.id. Its `access_identity` claim carries `team_sid`, `actor_sid` and `actor_type`, and that team scope is authoritative. TeamSid: type: apiKey in: header name: Team-SID description: >- Team scope for tokens that do not carry one. Ignored when the token already names a team. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.