Search companies (free thin rows, full rows billed)
search_companiesReturn companies matching an ICP. Free by default while the account has free thin rows left today (a daily quota; detail "thin" guarantees $0). Thin rows carry no domain; enrich_company adds it for the ones you keep. detail "full" is billable: about $0.02 per returned row (0 rows costs $0) at the Tier 0 list price. Accounts can pay a different rate: get_balance returns this account's prices, and every response reports what was actually spent in cost.amount_charged_usd. Realtime is billed per row too. count_companies sizes the result for free first. headcount_range is a snapshot taken when the record was indexed and can lag the company's current size; the filter itself is applied at query time.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "search_companies"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Data mode. "database" = Generect's own index: sub-second, free counts, free thin rows (see detail) or cheaper full rows; it accepts a subset of the filters today and names any it rejects. "realtime" = live LinkedIn lookup, 5–60s, billed per row, accepts every realtime filter. "auto" (default) tries database first and escalates to realtime only if a filter you passed is rejected there (the escalation is reported, and is refused above the per-call spend ceiling). Pick "database" explicitly when freshness is not critical and cost matters more than freshness. | |
| limit | No | Alias for limit_by. | |
| detail | No | Row detail for the database search. Thin rows are FREE (id, name, industry, headcount_range, HQ country/city, company_type, founded_year; no LinkedIn URL, domain, contacts or history) up to a daily per-account row quota that resets at 00:00 UTC. Omitted (default): thin while the free tier is available; once it is not (quota spent, a custom-contract account, a server without the tier) the search continues as before: full rows billed per row, marked thin_unavailable in the result, under the spend ceiling. "thin": free rows only, never billed, never escalated to realtime; a spent quota is a 429 and a realtime-only filter is an error. "full": the whole record, billed per row. Browse thin, then spend only on the rows you keep: generate_email takes the lead id directly, enrich_* gives the full record. | |
| offset | No | Alias for offset_by. | |
| compact | No | Default true: return a small per-company summary (including the Generect `id`, which every later step accepts). Set false for the full raw record (~80 fields), only worth it when you specifically need skills, education or other deep fields. | |
| keywords | No | Free-text keywords across name/description/specialties. Realtime only: using it forces the pricier live mode. | |
| limit_by | No | Rows to return this call (1–100, default 25). You are billed per returned row, so this number IS the price of the call. | |
| locations | No | HQ locations: cities, states or countries. | |
| offset_by | No | Rows to skip (pagination). | |
| headcounts | No | Size buckets. Allowed ONLY: "1-10","11-50","51-200","201-500","501-1000","1001-5000","5001-10000","10 000+". | |
| industries | No | Company industries. Must match Generect industry names exactly (e.g. "Software Development"); unknown names are rejected with HTTP 400. | |
| timeout_ms | No | Request timeout in milliseconds. | |
| exclude_ids | No | Exclude companies by LinkedIn id/URN. | |
| technologies | No | Technologies the company uses. Realtime only: using it forces the pricier live mode. | |
| company_names | No | Restrict to specific company names. Realtime only: using it forces the pricier live mode. | |
| company_types | No | Company types: "Public Company","Privately Held","Non Profit","Government Agency","Educational", … | |
| revenues_range | No | Annual revenue range, single object {min,max}. Realtime only: using it forces the pricier live mode. | |
| sub_industries | No | Expand each selected industry to its sub-industries as well (broadens the match). | |
| exclude_domains | No | Exclude companies by domain (e.g. existing customers). | |
| linkedins_links | No | Specific LinkedIn company URLs. Realtime only: using it forces the pricier live mode. | |
| headcount_growth | No | Headcount growth in percent. Realtime only: using it forces the pricier live mode. | |
| num_of_followers | No | LinkedIn follower buckets: "1-50","51-100","101-1000","1001-5000","5001+". Realtime only: using it forces the pricier live mode. | |
| confirm_spend_usd | No | Explicit approval for an unusually large charge. Calls whose worst case exceeds $5 are refused unless this is set to at least the amount the tool reports. Only set it after the user has agreed to that number. | |
| exclude_locations | No | HQ locations to exclude. | |
| get_max_companies | No | DEPRECATED: accepted but ignored. Always on now: search responses include results_count without asking. | |
| exclude_industries | No | Industries to exclude. | |
| hiring_on_linkedin | No | Only companies actively hiring. Realtime only: using it forces the pricier live mode. | |
| fallback_from_leads | No | DEPRECATED: accepted but ignored. Removed. It fabricated lead-derived name aggregates and cost an extra billable query. | |
| department_headcount | No | Department size, e.g. {"name":"engineering","min":10,"max":100}. Realtime only: using it forces the pricier live mode. | |
| allow_unlisted_values | No | Escape hatch for the local vocabulary check; see the lead-side field of the same name. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fix | No | ||
| cost | No | ||
| mode | No | ||
| note | No | ||
| leads | No | ||
| detail | No | ||
| status | No | ||
| returned | No | ||
| companies | No | ||
| free_tier | No | ||
| test_mode | No | ||
| thin_note | No | ||
| spend_guard | No | ||
| results_count | No | ||
| next_page_args | No | ||
| requested_rows | No | ||
| escalation_note | No | ||
| test_mode_notice | No | ||
| thin_unavailable | No | ||
| vocabulary_warnings | No | ||
| blocked_by_vocabulary | No | ||
| deprecated_params_ignored | No | ||
| escalated_to_realtime_because | No | ||
| api_returned_more_than_requested | No |