Search companies (free thin rows, full rows billed)
search_companiesFind companies matching your ideal customer profile by industry, size, location, and type. Count results free first, then browse free thin rows before paying to enrich only the ones you keep.
Instructions
Return 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.
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 |