gtm.devdocs
find companies

Company list builder API

build_list

2.5 credits / company returned

Describe the list you want in plain language and get the executed company list back in ONE call — we extract the criteria, choose between taxonomy filters and semantic search, canonicalize every value against the graph's real vocabularies, run the search, and return the rows plus the exact plan applied (in the same shapes search_companies / concept_search accept, so you can iterate deterministically). Supports excludes ("...but not staffing agencies"). Funding graph language ("raised a Series B", "backed by Sequoia", "over $10M raised") and detected-tech-stack language ("using Salesforce", "not on HubSpot") are extracted as exact filters, not vibes — they apply alongside EITHER taxonomy filters or semantic search. When the description names people (titles/roles), the response includes a ready-made find_people follow-up. A best-effort `total` (full matching-universe count, filter mode only) rides along when it resolves within a short bound. Companies only — chain find_people for the humans.

Get an API key 1,000 free live credits · no card

Parameters

paramtypedescription
description requiredstringWhat you want, in plain language, e.g. "US payroll and HR software companies, 200+ employees, not staffing agencies" or "companies that feel like Stripe but for logistics".
limitintegerRows to return (default 10, max 50 in semantic mode / 100 in filter mode). COST: each company returned costs 2.5 credits (plus a 0.1 base fee per call), so this limit sets the price of the call — ask for what you need.
offsetintegerRows to skip for pagination. Mode-specific caps apply (semantic ~200 deep, filter 5000).

Call it from your agent (MCP)

Connect once and build_list appears in your agent’s toolbox next to every other gtm.dev tool. Claude Code:

claude mcp add --transport http gtm https://mcp.gtm.dev \
  --header "Authorization: Bearer YOUR_API_KEY"

Under the hood, the client sends:

curl -X POST https://mcp.gtm.dev \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"build_list","arguments":{"description":"US payroll and HR software companies, 200+ employees, not staffing agencies","limit":25}}}'

other clients (cursor, claude desktop, openai agents sdk, langchain): mcp setup

Call it over REST

curl -X POST https://api.gtm.dev/v1/tools/build_list \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"US payroll and HR software companies, 200+ employees, not staffing agencies","limit":25}'

Errors (401, 402, 429, 400) are listed in the REST reference. Calls that error are not billed — see pricing.

Related tools