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

> What anything that spends credits would cost BEFORE it spends them, in one answer: the money-honesty gate (call it, tell the user the range, then act). actions[] carries 1..20 of: column (a saved action column run over the rows: field_sid, force_rerun, cells not_run | error; the columns of one table are priced as ONE run: the registry's per-step ranges, an email lane by outcome, a Use AI column on a sample); column_draft (a Use AI column before it exists: field_type action_ai_research and the draft payload, on the grid playtable_sid + object_type name; one action per model compares models); unit (one call of one tool times the rows: tool_sid, a column catalog read such as get_person_posts, or in:{provider}.{operation}); semantic_index (a column's Semantic search switched on or to another embed model: field_sid, provider, model; the backfill now, a later value as a range in per_row); play (one run of a play now: play_sid; matched, acted, skipped, the ceiling and the month in detail). rows is a count (0..1000000) or the run's scope (object_sids XOR view_sid / filter); omitted, a column prices the whole table, a unit one call. Answers min, expected and max in credits (pass max as max_budget to create_playtable_run, never expected), the basis and each action's numbers, rows, per_row and detail. No writes, no charges. What was spent is the credit ledger.

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



## OpenAPI

````yaml /api-reference/playtables/openapi.yaml post /api/playtable-fields/estimate-credits
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`, 121
    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://api2.getsales.io/playtables/v1
    description: Production
security:
  - BearerJwt: []
    TeamSid: []
tags:
  - name: activities
    description: >-
      Registry package `mcp.playtables/activities`, served on MCP mount
      `playtables.rows`.
  - name: activity_objects
    description: >-
      Registry package `mcp.playtables/activity_objects`, served on MCP mount
      `playtables.rows`.
  - name: companies
    description: >-
      Registry package `mcp.playtables/companies`, served on MCP mount
      `playtables.rows`.
  - name: credit_ledger_entries
    description: >-
      Registry package `mcp.playtables/credit_ledger_entries`, served on MCP
      mount `workspace.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.crm`.
  - name: people
    description: >-
      Registry package `mcp.playtables/people`, served on MCP mount
      `playtables.rows`.
  - name: pipeline_stages
    description: >-
      Registry package `mcp.playtables/pipeline_stages`, served on MCP mount
      `playtables.crm`.
  - name: plays
    description: Registry package `mcp.playtables/plays`, served on MCP mount `signals`.
  - 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: sender_profiles
    description: >-
      Registry package `mcp.playtables/sender_profiles`, served on MCP mount
      `sender-profiles`.
  - name: stoplist_entries
    description: >-
      Registry package `mcp.playtables/stoplist_entries`, served on MCP mount
      `playtables.crm`.
  - name: tags
    description: >-
      Registry package `mcp.playtables/tags`, served on MCP mount
      `playtables.crm`.
  - 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.workflow-records`.
  - 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.workflow-records`.
  - 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-fields/estimate-credits:
    post:
      tags:
        - playtable_fields
      summary: Estimate credits
      description: >-
        What anything that spends credits would cost BEFORE it spends them, in
        one answer: the money-honesty gate (call it, tell the user the range,
        then act). actions[] carries 1..20 of: column (a saved action column run
        over the rows: field_sid, force_rerun, cells not_run | error; the
        columns of one table are priced as ONE run: the registry's per-step
        ranges, an email lane by outcome, a Use AI column on a sample);
        column_draft (a Use AI column before it exists: field_type
        action_ai_research and the draft payload, on the grid playtable_sid +
        object_type name; one action per model compares models); unit (one call
        of one tool times the rows: tool_sid, a column catalog read such as
        get_person_posts, or in:{provider}.{operation}); semantic_index (a
        column's Semantic search switched on or to another embed model:
        field_sid, provider, model; the backfill now, a later value as a range
        in per_row); play (one run of a play now: play_sid; matched, acted,
        skipped, the ceiling and the month in detail). rows is a count
        (0..1000000) or the run's scope (object_sids XOR view_sid / filter);
        omitted, a column prices the whole table, a unit one call. Answers min,
        expected and max in credits (pass max as max_budget to
        create_playtable_run, never expected), the basis and each action's
        numbers, rows, per_row and detail. No writes, no charges. What was spent
        is the credit ledger.


        Contract:

        - MCP tool `estimate_credits`, registry package
        `mcp.playtables/playtable_fields`, mount `playtables.columns`.

        - Operation `action`, response envelope `action`.

        - Flags: read only.
      operationId: estimate_credits
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EstimateCreditsRequest'
      responses:
        '200':
          description: '`action` success envelope.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EstimateCreditsResponse'
        4XX:
          $ref: '#/components/responses/McpClientError'
        5XX:
          $ref: '#/components/responses/McpServerError'
components:
  schemas:
    EstimateCreditsRequest:
      type: object
      description: Request body of `estimate_credits`.
      properties:
        playtable_sid:
          type: string
          nullable: true
          minLength: 18
          maxLength: 18
          pattern: ^pt_tb_
          description: >-
            The table (pt_tb_): required by a column_draft action (the grid its
            prompt is read on), optional otherwise.
        object_type:
          type: string
          nullable: true
          enum:
            - people
            - company
          description: 'people | company, the grid: required by a column_draft action.'
        rows:
          anyOf:
            - type: integer
              minimum: 0
              maximum: 1000000
            - type: object
              properties:
                object_sids:
                  type: array
                  nullable: true
                  items:
                    type: string
                    minLength: 18
                    maxLength: 18
                  minItems: 1
                  maxItems: 10000
                  description: >-
                    Hand-picked rows (cr_pp_ or cr_co_), 1..10000; XOR with
                    view_sid / filter.
                exclude_object_sids:
                  type: array
                  nullable: true
                  items:
                    type: string
                    minLength: 18
                    maxLength: 18
                  maxItems: 10000
                  description: Rows taken out of a view or filter scope, up to 10000.
                view_sid:
                  type: string
                  nullable: true
                  minLength: 18
                  maxLength: 18
                  pattern: ^pt_vw_
                  description: 'A saved view (pt_vw_): its rows now.'
                filter:
                  type: object
                  nullable: true
                  additionalProperties: {}
                  description: >-
                    An inline filter AST over the tab, the run's scope form; an
                    empty filter is refused.
            - {}
          description: >-
            What the price covers: a count of rows (0..1000000), or the run's
            scope (object_sids XOR view_sid / filter, counted on ES). Omitted: a
            column action prices the whole table, a column_draft the grid's
            first rows, a unit one call.
        actions:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - column
                  - column_draft
                  - unit
                  - semantic_index
                  - play
                description: >-
                  column: a saved column over the rows (field_sid, force_rerun,
                  cells). column_draft: a Use AI draft (field_type, payload,
                  playtable_sid, object_type). unit: a tool call times the rows
                  (tool_sid). semantic_index: field_sid, provider, model. play:
                  play_sid.
              field_sid:
                type: string
                nullable: true
                minLength: 18
                maxLength: 18
                pattern: ^pt_fd_
                description: 'column and semantic_index: the column (pt_fd_).'
              force_rerun:
                type: boolean
                nullable: true
                description: >-
                  column: count done cells as re-runnable (they would be charged
                  again). Default false.
              cells:
                type: string
                nullable: true
                enum:
                  - not_run
                  - error
                description: >-
                  column: price only the cells that have not run (not_run) or
                  only the error cells (error), the same selection as the run's
                  params.cells.
              field_type:
                type: string
                nullable: true
                enum:
                  - action_ai_research
                description: >-
                  column_draft: what the draft is; action_ai_research alone
                  today.
              payload:
                type: object
                nullable: true
                additionalProperties: {}
                description: >-
                  column_draft: the draft (prompt, model, output, options,
                  web_search as it will be saved), validated like
                  create_playtable_field's; model "auto" is the catalog's
                  default, an unknown one 422. A column not built or filled yet
                  reads empty: a floor.
              tool_sid:
                type: string
                nullable: true
                maxLength: 255
                description: >-
                  unit: a column catalog read times the rows: get_lite_profile
                  (1 credit), get_full_profile (3), get_profile_experience,
                  get_profile_education, get_profile_skills, get_person_posts (2
                  each), get_company_lite_profile (1), get_company_profile (2),
                  enrich_location (free); or in:{provider}.{operation}
                  (list_provider_catalog). Unknown: 404 not_found or 422
                  relation_not_found.
              provider:
                type: string
                nullable: true
                maxLength: 64
                description: 'semantic_index: the embed provider, e.g. openai.'
              model:
                type: string
                nullable: true
                maxLength: 128
                description: >-
                  semantic_index: the embed model, e.g. text-embedding-3-small;
                  a pairing the catalog does not list is 422 relation_not_found.
              play_sid:
                type: string
                nullable: true
                minLength: 18
                maxLength: 18
                pattern: ^pt_pl_
                description: >-
                  play: the play (pt_pl_); a people play with no workflow yet is
                  422.
            required:
              - type
          minItems: 1
          maxItems: 20
          description: >-
            1..20 actions, each of one kind, priced in the order given and
            summed.
      required:
        - actions
    EstimateCreditsResponse:
      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:
            min:
              type: number
              description: >-
                Credits, the sum over the actions: every row ends on the
                cheapest step.
            expected:
              type: number
              description: >-
                Credits, the sum over the actions: what the rows are expected to
                cost.
            max:
              type: number
              description: >-
                Credits, the sum over the actions: the dearest path; pass it as
                max_budget to create_playtable_run.
            currency:
              type: string
              enum:
                - credits
            priced_at:
              type: string
              description: 'ISO 8601 UTC: the price snapshot time.'
            basis:
              type: object
              properties:
                rows:
                  type: object
                  properties:
                    form:
                      type: string
                      description: 'What the rows setting was: count, scope or table.'
                    requested:
                      type: integer
                      nullable: true
                      description: The count asked for; null for a scope or the table.
                    matched:
                      type: integer
                      nullable: true
                      description: >-
                        The ES count of the scope or the table (approximate by
                        design); null for a count.
                  required:
                    - form
                    - requested
                    - matched
                rows_sampled:
                  type: integer
                  minimum: 0
                  description: Rows a prompt was rendered on (column_draft).
                sampled:
                  type: boolean
                  description: true when any action priced a sample and extrapolated.
              required:
                - rows
                - rows_sampled
                - sampled
            actions:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - column
                      - column_draft
                      - unit
                      - semantic_index
                      - play
                  min:
                    type: number
                    description: 'Credits: every row ends on the cheapest step.'
                  expected:
                    type: number
                    description: 'Credits: what the rows are expected to cost.'
                  max:
                    type: number
                    description: >-
                      Credits: the dearest path with the model's whole output
                      cap; what a run's max_budget is set from.
                  rows:
                    type: integer
                    minimum: 0
                    description: >-
                      The rows the numbers cover: a column's rows_to_run, a
                      draft's rows_total, a unit's count, the cells a semantic
                      index embeds now, the rows a play would act on.
                  per_row:
                    type: object
                    nullable: true
                    properties:
                      min:
                        type: number
                      expected:
                        type: number
                        nullable: true
                      max:
                        type: number
                    required:
                      - min
                      - expected
                      - max
                    description: >-
                      The price of one row where a row has one (a semantic
                      index: one later value as a range, expected null); null
                      for a play.
                  detail:
                    type: object
                    additionalProperties: {}
                    description: >-
                      The engine's own breakdown. column: field_sid,
                      rows_matched, rows_to_run, steps[] {tool_sid, price_min,
                      price_max}. column_draft: provider, model, web_search,
                      rows_sampled, rows_skipped, rows_total, tokens_in {min,
                      avg, max}, tokens_out_expected, price (the model's
                      price_min / price_expected / price_max / price_cap, each
                      with web search or null). unit: tool_sid. semantic_index:
                      field_sid, provider, model, cells_filled, cells_to_embed,
                      cost_per_value_min, cost_per_value_max, sampled. play:
                      play_sid, matched, acted, skipped, credits,
                      ceiling_applies, credits_month, credits_month_parts[].
                required:
                  - type
                  - min
                  - expected
                  - max
                  - rows
                  - per_row
                  - detail
              description: In the order asked.
          required:
            - min
            - expected
            - max
            - currency
            - priced_at
            - basis
            - actions
        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.