Sourcing a Growth-Stage TAM by Headcount and Growth Rate with TypeScript

POST /source-growth-tam (companySize, minGrowthRatio, growthWindow, maxResults)
    ↓
POST /search/query-mode              (create: company_size + employee_growth_Nmo)
    ↓
POST /search/query-mode/{id}/run     (page results)
    ↓
companies[]

Implement a TypeScript/Express service that sources a growth-stage TAM by
headcount and employee-growth momentum using Clay's query-mode Search API.

Requirements:
- Base URL: https://api.clay.com/public/v0, auth header "clay-api-key".
- Employee-growth momentum does NOT exist in filters-mode at all (the
  30 real fields there include none growth-related). It only exists in query-mode
  as employee_growth_3mo / _6mo / _12mo / _24mo -- a number ratio where
  1.1 means +10% growth and 0.9 means -10% decline.
- The headcount-band field in query-mode is "company_size" -- NOT "size".
  Using "size" produces a real 400: {"message":"Unknown
  field 'size' for entity 'companies'"}.
- Build the query as a string: 'select from companies where company_size =
  "<band>" and employee_growth_<window> > <ratio>'.
- POST /search/query-mode with {"source_type":"companies","query":"..."}
  returns {"search_id":"..."}. POST /search/query-mode/{search_id}/run
  with {"limit":N} returns {"data":[...company rows...]}.
- Run the verification step below before finishing.

mkdir tam-growth-source && cd tam-growth-source
npm init -y
npm install express
npm install -D typescript @types/express @types/node
npx tsc --init

curl -s "https://api.clay.com/public/v0/search/query-mode/reference" \
  -H "clay-api-key: $CLAY_API_KEY"

CLAY_API_KEY=

import express, { Request, Response as ExpressResponse } from "express";

const CLAY_API_BASE = "https://api.clay.com/public/v0";
const CLAY_API_KEY = process.env.CLAY_API_KEY;

if (!CLAY_API_KEY) throw new Error("CLAY_API_KEY env var is required");

interface CompanyRow {
  name: string;
  domain: string;
  size: string;
  industry: string;
}

async function clayFetch(path: string, init: RequestInit = {}): Promise<globalThis.Response> {
  return fetch(`${CLAY_API_BASE}${path}`, {
    ...init,
    headers: {
      "clay-api-key": CLAY_API_KEY as string,
      "Content-Type": "application/json",
      ...(init.headers || {}),
    },
  });
}

type GrowthWindow = "3mo" | "6mo" | "12mo" | "24mo";

// Employee-growth momentum only exists as a native field in query-mode
// (employee_growth_3mo/6mo/12mo/24mo, a ratio: 1.1 = +10% growth) -- absent
// from filters-mode entirely. The headcount-band field here is
// "company_size" -- NOT "size", which produces a real 400 error.
async function sourceGrowthTam(
  companySize: string,
  minGrowthRatio: number,
  growthWindow: GrowthWindow,
  limit: number,
): Promise<CompanyRow[]> {
  const query = `select from companies where company_size = "${companySize}" and employee_growth_${growthWindow} > ${minGrowthRatio}`;

  const createRes = await clayFetch("/search/query-mode", {
    method: "POST",
    body: JSON.stringify({ source_type: "companies", query }),
  });
  if (!createRes.ok) {
    throw new Error(`query create failed: ${createRes.status} ${await createRes.text()}`);
  }
  const { search_id } = (await createRes.json()) as { search_id: string };

  const runRes = await clayFetch(`/search/query-mode/${search_id}/run`, {
    method: "POST",
    body: JSON.stringify({ limit }),
  });
  if (!runRes.ok) {
    throw new Error(`query run failed: ${runRes.status} ${await runRes.text()}`);
  }
  const { data } = (await runRes.json()) as { data: CompanyRow[] };
  return data;
}

const app = express();
app.use(express.json());

app.post("/source-growth-tam", async (req: Request, res: ExpressResponse) => {
  const { companySize, minGrowthRatio, growthWindow = "6mo", maxResults = 20 } = req.body ?? {};
  if (!companySize || !minGrowthRatio) {
    return res.status(400).json({ error: "companySize and minGrowthRatio are required" });
  }

  try {
    const companies = await sourceGrowthTam(companySize, minGrowthRatio, growthWindow, maxResults);
    res.json({ count: companies.length, companies });
  } catch (err) {
    res.status(502).json({ error: (err as Error).message });
  }
});

const port = Number(process.env.PORT) || 3000;
app.listen(port, () => console.log(`listening on ${port}`));

npx tsc
node --env-file=.env dist/index.js

curl -X POST http://localhost:3000/source-growth-tam \
  -H "Content-Type: application/json" \
  -d '{"companySize":"51-200","minGrowthRatio":1.1,"growthWindow":"6mo","maxResults":3}'

{
  "count": 3,
  "companies": [
    {"name": "Vagas.com", "domain": "vagas.com.br", "size": "51-200", "industry": "Software Development"},
    {"name": "GenAI Works", "domain": "genai.works", "size": "51-200", "industry": "Technology, Information and Media"},
    {"name": "Crossing Hurdles", "domain": "crossinghurdles.com", "size": "51-200", "industry": "Staffing and Recruiting"}
  ]
}

verification:
  status: verified
  tested_at: "2026-09-02"
  product_version: "public/v0"
  command: "npx tsc && node --env-file=.env dist/index.js && curl -X POST http://localhost:3000/source-growth-tam -d '{\"companySize\":\"51-200\",\"minGrowthRatio\":1.1,\"growthWindow\":\"6mo\",\"maxResults\":3}'"
  expected_result: "Three real companies in the 51-200 headcount band with 6-month employee growth above 1.1x are returned, using the field 'company_size' (not 'size') and a query-mode search, not filters-mode, which has no growth field."