> ## Documentation Index > Fetch the complete documentation index at: https://docs.api.tamtam.ai/llms.txt > Use this file to discover all available pages before exploring further. # Preview a contact search > How many people a contact search would match, before you start it. Takes the same companies and queries as [Start a contact search](/api-reference/contact-searches/create-contact-search). **Read it as a ceiling, not a forecast.** It sums one count per query, so anyone matching two queries is counted twice; and it cannot apply seniority bands, which are read from a job title only after a profile has been fetched — `seniority_bands_ignored` names the ones it had to skip. The one direction it comes out too small is `queries_counted` below `queries_requested`, which caps what a single preview may spend: the queries left out contribute nobody to the total. Costs no credits, but it is not instant: each query is a live provider count, a few seconds. Size an uncertain search with it — but do not preview what you are not about to run. It is refused with 402 when the account has no credits at all, since the search it sizes could not be started either. ## OpenAPI ````yaml /reference/openapi.yaml post /v2/contact-searches/preview-count openapi: 3.1.0 info: title: Tamtam Public API version: 2.0.0 servers: - url: https://api.tamtam.ai/api security: [] paths: /v2/contact-searches/preview-count: post: tags: - Contact Searches summary: Preview a contact search description: >- How many people a contact search would match, before you start it. Takes the same companies and queries as [Start a contact search](/api-reference/contact-searches/create-contact-search). **Read it as a ceiling, not a forecast.** It sums one count per query, so anyone matching two queries is counted twice; and it cannot apply seniority bands, which are read from a job title only after a profile has been fetched — `seniority_bands_ignored` names the ones it had to skip. The one direction it comes out too small is `queries_counted` below `queries_requested`, which caps what a single preview may spend: the queries left out contribute nobody to the total. Costs no credits, but it is not instant: each query is a live provider count, a few seconds. Size an uncertain search with it — but do not preview what you are not about to run. It is refused with 402 when the account has no credits at all, since the search it sizes could not be started either. operationId: preview-contact-search-count requestBody: content: application/json: schema: $ref: '#/components/schemas/PreviewContactSearchCountInputBody' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/PreviewContactSearchCountOutputBody' description: OK default: content: application/problem+json: schema: $ref: '#/components/schemas/ErrorModel' description: Error security: - apikeyAuth: [] - bearerAuth: [] components: schemas: PreviewContactSearchCountInputBody: additionalProperties: false properties: company_linkedin_ids: description: The companies the search would run at. examples: - - '104924588' items: type: string minItems: 1 type: - array - 'null' queries: description: >- The queries the search would run. Send the same ones you will submit: a count run without a filter you intend to search with sizes a different search. items: $ref: '#/components/schemas/ContactSearchQueryInputDto' minItems: 1 type: - array - 'null' required: - company_linkedin_ids - queries type: object PreviewContactSearchCountOutputBody: additionalProperties: false properties: queries_counted: description: >- How many of the queries the count actually ran. Below queries_requested means total covers only the first N and is a FLOOR for the whole search rather than an estimate of it. format: int64 type: integer queries_requested: description: How many queries were sent. format: int64 type: integer seniority_bands_ignored: description: >- Seniority bands the count could not apply, because seniority is read from a job title after a profile is fetched and never reaches a provider. Non-empty means total is an upper bound: the search will keep fewer people than this. items: type: string type: - array - 'null' total: description: >- How many people the queries match across the companies, summed over queries. An upper bound on what the search would extract, never a forecast: it double-counts anyone matching two queries, and it cannot apply seniority bands (see seniority_bands_ignored). examples: - 412 format: int64 type: integer required: - total - queries_counted - queries_requested - seniority_bands_ignored type: object ErrorModel: additionalProperties: false properties: detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string type: object ContactSearchQueryInputDto: additionalProperties: false properties: canonical_job_titles_excludes_ids: description: Canonical job title IDs to exclude. items: type: string type: - array - 'null' canonical_job_titles_includes_ids: description: >- Canonical job title IDs to match. Prefer these over free text where a canonical title exists: they carry the title's translations. items: type: string type: - array - 'null' countries: description: >- Alpha-2 country codes for the PERSON's location. There is no sub-country filter here. examples: - - FR items: type: string type: - array - 'null' country_excludes: description: Alpha-2 country codes to exclude. examples: - - BE items: type: string type: - array - 'null' include_past_job_titles: description: >- Top up a query that comes back short by also searching people who PREVIOUSLY held one of its titles at the company. Off unless set: it matches people on a role they no longer hold, while the list shows the role they do, and it is the dominant source of off-target results. examples: - false type: boolean job_titles_excludes: description: >- Free-text job titles to exclude. These do exclude, unlike a NOT inside keywords. examples: - - Intern items: type: string type: - array - 'null' job_titles_includes: description: Free-text job titles to match. examples: - - Head of Sales - VP Sales items: type: string type: - array - 'null' keywords: description: >- Free-text search over the whole profile: headline, About, every role's title and description, skills, education. A boolean expression — uppercase AND / OR, double quotes around phrases, parentheses for grouping, implicit AND between bare words. It restricts which provider may run this query, since a provider with no profile-text filter would return people matching the titles and ignoring the words. A query whose keywords no provider can honour fails the whole request rather than running unfiltered. examples: - '"supply chain" AND SAP' type: string label: description: >- Short name for this query, shown beside the search in the app and frozen at submit time. Defaults to the persona's name, or to 'Query N' for an inline query. examples: - Revenue leadership type: string persona_id: description: >- One of your saved personas, supplying this query's job titles, countries and seniority bands. List them via [Get personas](/api-reference/personas/get-personas). The persona is read at submit time and frozen into the search, so editing it later does not change a search already running. Whether the search is widened by Tamtam's AI extension of the persona follows the persona's own setting, as it does in the app. Any field you also set below overrides the persona's value for it — and overriding the job titles also switches the AI extension off for this query, because a caller who narrowed a persona by hand must not have it widened again with titles they cannot see. examples: - b3c6f5e2-1234-4abc-9def-0123456789ab type: string seniority_excludes: description: >- Seniority bands to drop, same classification and same application point as seniority_includes. items: type: string type: - array - 'null' seniority_includes: description: >- Seniority bands to keep, read from each person's job title by Tamtam's own classifier and applied to the profiles the search fetches — never sent to a provider. A person whose title carries no seniority signal is kept rather than dropped. Allowed values: 'Owner / Partner', 'CXO', 'Vice President', 'Director', 'Experienced Manager', 'Senior', 'Entry Level', 'In Training'. Because the bands apply after fetching, they narrow what lands in the list without narrowing what the search pays for — see the note on [Preview a contact search](/api-reference/contact-searches/preview-contact-search-count). examples: - - Director - CXO items: type: string type: - array - 'null' type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object securitySchemes: apikeyAuth: description: Account API key passed in the Authorization header in: header name: Authorization type: apiKey bearerAuth: description: Bearer JWT obtained via the OAuth 2.1 authorization flow scheme: bearer type: http ````