---
title: "Plan data source filters"
method: POST
path: "/api/data-sources/ai-plan"
tags: ["data_sources"]
---

# Plan data source filters

`POST /api/data-sources/ai-plan`

## Request

- Base URL: `https://beta.getsales.io/playtables/v1`
- URL: `https://beta.getsales.io/playtables/v1/api/data-sources/ai-plan`
- Auth: HTTP bearer and API key in header `Team-SID`

Turn a description of who to find into a wire-ready filter set without creating anything: the step before create_data_source when the user should see or edit what will be searched. Paid: the AI parse costs one credit per call. It reads the words into facets (location, industry, current and past company, school, seniority, job function, company headcount, titles as free text) and the platform pool resolves every id-bearing term; a term with no id lands in result.unresolved, never faked. Facets are ANDed and the values inside one facet ORed; there are no exclusion filters, so describe who to find, never who to leave out. A facet keeps at most 10 values: the first ten stay, the dropped terms are named in result.warnings.

Hand the answer to create_data_source as is: type and object_type from the result, name = suggested_name, payload = {filters, prompt: <the description>} (find_people adds payload.company_sids). create_data_source with payload.prompt alone plans the same way at its first collect step, so call this only when the plan must be seen first.

Refusals: 422 on prompt when nothing usable was read (ai_parse_failed or ai_empty_filter: rephrase with roles, places or industries); a busy pool answers 503 service_unavailable (context.reason infrastructure_unavailable or search_in_flight) or 429 rate_limited (pool_rate_limited), each with context.retry_after: wait until then, or create the source with the prompt alone and let its collector plan at the pool's pace.

Contract:
- MCP tool `plan_data_source_filters`, registry package `mcp.playtables/data_sources`, mount `playtables.sources`.
- Operation `action`, response envelope `action`.
- Flags: none.

## Request body

- PlanDataSourceFiltersRequest: Request body of `plan_data_source_filters`.
  - `prompt` string, required: Who to find, in the user's words ("CMOs at fintech companies in DACH", "heads of growth").
  - `vertical` 'people' | 'company': people (default) | company - what the search brings back.
  - `company_scoped` boolean: Default false. true = a find_people plan: who to find inside companies selected in a grid; current companies are left out of the filter, the selection supplies them.

## Response `200`

`action` success envelope.

- PlanDataSourceFiltersResponse
  - `success` true, required
  - `operation` 'action', required
  - `action` string, required: kebab-case verb; matches the route segment.
  - `item` unknown, required
  - `result` object, required
    - `engine` string, required: Always "sales_nav": the wire engine the filters are written for; the collector runs them only under it.
    - `type` 'ai_search' | 'sender_search' | 'post_engagement' | 'find_people' | 'csv' | 'webhook', required: The kind to create with this plan: ai_search for an open search, find_people for a company_scoped one.
    - `object_type` 'people' | 'company', required: What the plan finds (the vertical): people | company. Pass it to create_data_source.
    - `filters` union, required: The wire-ready filter set: pass it verbatim as payload.filters. Different facets are ANDed and the values inside one facet ORed. Id facets ride as [{id}] (locations, industries, current_companies, past_companies, schools), the fixed lists as flat ids (seniority_levels, functions, company_headcounts), titles as [{text}] (current_titles).
      - object
      - unknown[]
        - unknown
    - `chips` object[], required: The human reading of the same filter, one chip per term (what the product shows under "View details"). Relay these to the user before you create anything.
      - `key` string, required: The semantic key the term fills: titles, seniorities, functions, company_sizes, locations, industries, current_companies, past_companies, schools, keywords, network, company_types.
      - `term` string, required: The human term as the description put it.
      - `id` string: The facet id it resolved to; absent on a free-text facet (a title rides as text).
      - `label` string: The label the search resolved for that id.
    - `unresolved` object[], required: Terms no facet id was found for: DROPPED from filters, never faked. Resolve one with suggest_data_source_filter_values and add the chosen id under the matching wire key, or tell the user the search is narrower than asked.
      - `key` string, required
      - `term` string, required
    - `warnings` string[], required: Sentences worth relaying to the user.
    - `suggested_name` string, required: A source name derived from the description (max 255): pass it as name.
  - `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)