---
title: "Search playtable field values"
method: POST
path: "/api/playtable-field-values/search"
tags: ["playtable_field_values"]
---

# Search playtable field values

`POST /api/playtable-field-values/search`

## Request

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

Cell-level execution records - per-cell status, cost cache, error and pin state, with a counts block (status / playtable_field_sid breakdowns). Use for: which cells errored for a field, why enrichment failed across rows, error-by-field health (page_size:0 + counts.groups). Requires a scope filter: playtable_sid.eq OR object_sid OR sid.in (422 otherwise). NOT for bulk value reads (people/companies search, include:["field_values"]) or money aggregates (credit-ledger-entries tools).

Contract:
- MCP tool `search_playtable_field_values`, registry package `mcp.playtables/playtable_field_values`, mount `playtables.columns`.
- Operation `search`, response envelope `search`.
- Flags: read only.

## Request body

- SearchPlaytableFieldValuesRequest: Request body of `search_playtable_field_values`.
  - `filter` object: Field filters, ANDed: {field: {eq | ne | in | nin | gte | lte | gt | lt | is_null}}; q inside it is free text. Omit for every row.
    - `sid` object
      - `eq` string: Cell (playtable field value) sid (pt_vl_…).
      - `in` string[]
    - `playtable_sid` object: Scope anchor (pt_tb_…).
      - `eq` string
    - `object_sid` object: cr_pp_… / cr_co_… (mixed prefixes, not prefix-pinned); cell-level debugging scope for one row.
      - `eq` string
      - `in` string[]
    - `object_type` object: Residual inside scope: people | company.
      - `eq` 'people' | 'company'
    - `playtable_field_sid` object: Per-field drill-down (pt_fd_…).
      - `eq` string
      - `in` string[]
    - `status` object: Error/progress drill-down; failed cells = in:["error","run_condition_not_met"].
      - `eq` 'empty' | 'queued' | 'running' | 'done' | 'error' | 'run_condition_not_met'
      - `ne` 'empty' | 'queued' | 'running' | 'done' | 'error' | 'run_condition_not_met'
      - `in` string[]
      - `nin` string[]
    - `is_value_from_formula` object: Pinned-vs-formula audit: false on formula fields = manually pinned or tool-written.
      - `eq` boolean
    - `finished_at` object: Last terminal write; is_null:true = never finalized.
      - `gte` string
      - `lte` string
      - `gt` string
      - `lt` string
      - `is_null` boolean
    - `created_at` object
      - `gte` string
      - `lte` string
      - `gt` string
      - `lt` string
  - `include` string[]: Relations to attach to every item; omit for the bare rows.
  - `sort` object: One column and its direction; omit for the default order.
    - `field` 'updated_at' | 'finished_at' | 'created_at', required: The column to order by.
    - `direction` 'asc' | 'desc': asc or desc; default desc.
  - `page_size` integer: 0..500, default 50; 0 = counts only, 1 = the first row.
  - `cursor` string, nullable: pagination.next_cursor of the previous page.

## Response `200`

`search` success envelope.

- SearchPlaytableFieldValuesResponse
  - `success` true, required
  - `operation` 'search', required
  - `items` object[], required
    - `item` object, required
      - `sid` string, required
      - `team_sid` string, required
      - `playtable_sid` string, required
      - `object_type` 'people' | 'company', required
      - `object_sid` string, required
      - `playtable_field_sid` string, required
      - `value` string, nullable, required
      - `is_value_from_formula` boolean, required
      - `original_value` string, nullable, required: The system-produced value the FIRST manual overwrite snapshotted, what reset restores; null unless is_overwritten. The list surface nulls it like meta: read it on get, update, write and reset.
      - `is_overwritten` boolean, required: The current value is a manual write over a system-produced one: the edited marker, and the one state reset accepts.
      - `is_not_valid` boolean, required: A manually written value that could not be converted to the column's type (text in a number column), stored raw and flagged; system writers coerce or null instead.
      - `status` 'empty' | 'queued' | 'running' | 'done' | 'error' | 'run_condition_not_met', required
      - `cost` number, nullable, required
      - `provider_sid` string, nullable, required
      - `meta` object, nullable, required
        - `run_sid` string, nullable, required
        - `steps` object[], required
          - `step_index` number, required
          - `tool_sid` string, required
          - `status` 'success' | 'failed' | 'skipped', required
          - `cost` number, required
          - `error` string, nullable, required
          - `finished_at` string, nullable, required
          - `verdict` string, nullable
          - `email` string, nullable
      - `error_msg` string, nullable, required
      - `finished_at` string, nullable, required
      - `created_at` string, required
      - `updated_at` string, required
    - `included` object, required
      - `field` object: 1:1 owning field (include[]=field): name, slug, category, type; config carries run_condition / nl_condition / preset.
        - `sid` string, required
        - `name` string, required
        - `slug` string, required
        - `category` string, required
        - `type` string, required
  - `pagination` object, required
    - `next_cursor` string, nullable, required
    - `has_more` boolean, required
    - `total_count` integer, nullable, required
  - `applied_filters` object, required
  - `includes` string[], required
  - `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.
  - `counts` object
    - `total_count` number, required
    - `groups` object, required
      - `status` union, required
        - object
        - unknown[]
          - unknown
      - `playtable_field_sid` union, required
        - object
        - unknown[]
          - unknown

## 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)