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 (daily quota; see detail — pass detail "thin" to guarantee $0); thin rows carry no domain — use enrich_company on the ones you keep. detail "full" is billable, about $0.0067 per returned row (0 rows costs $0) (Tier 0 list price; your account may pay a different rate — call get_balance for your real prices, and read cost.amount_charged in every response for what was actually spent). Realtime is billed per row too. Run count_companies first. Note that 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
TableJSON 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
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fix | No | ||
| cost | No | ||
| mode | No | ||
| note | No | ||
| leads | No | ||
| status | No | ||
| returned | No | ||
| companies | No | ||
| test_mode | No | ||
| spend_guard | No | ||
| results_count | No | ||
| next_page_args | No | ||
| requested_rows | No | ||
| escalation_note | No | ||
| test_mode_notice | No | ||
| vocabulary_warnings | No | ||
| blocked_by_vocabulary | No | ||
| deprecated_params_ignored | No | ||
| escalated_to_realtime_because | No | ||
| api_returned_more_than_requested | No |