---
title: "Estimate semantic index cost"
method: POST
path: "/api/playtable-fields/{sid}/estimate-semantic-index"
tags: ["playtable_fields"]
---

# Estimate semantic index cost

`POST /api/playtable-fields/{sid}/estimate-semantic-index`

## Request

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

What switching Semantic search on (or to another embed model) would cost ONE existing column, in credits, before the save: the backfill now (cost_expected over cells_to_embed of cells_filled; text already embedded with the same model is free) and one new or edited value later, as a range (cost_per_value_min to cost_per_value_max: a later value is its own call and its length is unknown until it lands). A dry run of the embed job's own sweep priced by the catalog rule, at the platform key every call runs on. No writes, no charges. Surface the numbers to the user before update_playtable_field sets payload.semantic_index.

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

## Path parameters

- `sid` string, required: The column (pt_fd_…): a scalar_text column, or an action_ai_research column with output: text; any other type is 422 validation_failed.

## Request body

- EstimateSemanticIndexRequest: Request body of `estimate_semantic_index`.
  - `provider` string, required: The embed provider the knob would carry, e.g. "openai". A pairing the platform catalog does not list is 422 relation_not_found, as on update.
  - `model` string, required: The embed model, e.g. "text-embedding-3-small". An unreachable catalog is 503 service_unavailable: without the rate there is no honest number.

## Response `200`

`action` success envelope.

- EstimateSemanticIndexResponse
  - `success` true, required
  - `operation` 'action', required
  - `action` string, required: kebab-case verb; matches the route segment.
  - `item` unknown, required
  - `result` object, required
    - `cells_filled` integer, required: Cells holding text the index embeds (valid, non-empty after trim).
    - `cells_to_embed` integer, required: Of them, the ones a backfill with THIS model pays for now; text already embedded with the same model is free (content hash).
    - `cost_expected` number, required: Credits the backfill costs now.
    - `cost_per_value_min` number, required: Credits one new or edited value costs later, at least: its own call, one unit, which covers any value up to about 1000 tokens.
    - `cost_per_value_max` number, required: Credits one later value costs at most: a value at the index's 8,000-character cap, written in this column's script.
    - `currency` 'credits', required
    - `sampled` boolean, required: true when the column held more than 5,000 cells: counted and priced on the first 5,000, extrapolated to the rest.
    - `priced_at` string, required: ISO 8601 UTC instant of the pricing.
  - `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)