Preview company-catalog coverage

This page documents the canonical HTTP contract for this endpoint.

This read-only endpoint previews only the current company-catalog snapshot; it does not create a durable list-build job. It requires an authenticated user with organization context. Developer API keys need search:run.

The response distinguishes an exact count from a capped lower bound with count_relation (exact or at_least), identifies count_scope: "catalog_snapshot", and returns the interpreted filters, sample, and projection metadata. A snapshot count does not claim exhaustive real-world market coverage.

Body parameters

filtersrequired
object
Company-catalog filters; use canonical values from GET /api/list-builds/inputs.
count_cap · optional
integer
Count ceiling; default 250, range 1–1000. Counts above the cap are reported as at_least.
sample_size · optional
integer
Sample rows to include; default 5, range 0–5.

Name	Type	Description
filtersrequired	object	Company-catalog filters; use canonical values from GET /api/list-builds/inputs.
count_cap	integer	Count ceiling; default 250, range 1–1000. Counts above the cap are reported as at_least.
sample_size	integer	Sample rows to include; default 5, range 0–5.

Errors

Status	Meaning
400	Invalid company-catalog filter or count request.
401	Authentication required.
403	Developer API key lacks search:run.
422	count_cap must be 1–1000 and sample_size 0–5.
503	Company-catalog preview is temporarily unavailable.

Example

bash

curl -X POST "https://app.autotouch.ai/api/list-builds/preview" -H "Authorization: Bearer $AUTOTOUCH_API_KEY" -H "Content-Type: application/json" -d '{"filters":{"specialization_ids":["accountant"]},"count_cap":250,"sample_size":5}'

Request body

json

{
  "filters": {"specialization_ids": ["accountant"]},
  "count_cap": 250,
  "sample_size": 5
}

Response example

json

{
  "count": 250,
  "count_relation": "at_least",
  "count_scope": "catalog_snapshot",
  "has_more": true,
  "coverage_note": "Count is scoped to the current company-catalog snapshot and does not claim exhaustive real-world market coverage.",
  "count_cap": 250,
  "sample": [{"id": "company:example", "name": "Example Accountants"}],
  "sample_size": 1,
  "interpreted_filters": {"specialization_ids": ["accountant"]},
  "projection": {},
  "timing": {}
}