Skip to main content

​
Endpoint essentials

Use this when you want to explore a market, build a target account list, or find companies by what they do. You can search with structured filters, natural-language relevance, or both. The Company Search API lets you find companies by domain, country, industry, revenue, funding, headcount, product focus, business model, and more. This page walks you through structured and ranked search, the response shape, and worked examples you can adapt. For the operator list, field catalog, and validation rules, see Search reference. Every request goes to the same endpoint:
Replace YOUR_API_KEY in each example with your actual API key. All requests require the x-api-version: 2025-11-01 header.

​
Request body

​
search fields

​
Find companies by what they do

Use ranked search when your criteria describe a product, capability, or business model that does not map cleanly to a filter field. This request combines a natural-language query with a hard country filter.
Request
The filter remains exact. The API ranks only companies that satisfy it. Use hybrid for most discovery queries. Use lexical when literal wording matters, or semantic when conceptual similarity matters more than shared keywords.

​
Match literal keywords

Use lexical mode when the exact words in the query matter. This mode uses keyword retrieval without semantic vector matching.
Request

​
Find conceptually similar companies

Use semantic mode when companies may describe the same capability with different terminology. This mode uses embedding similarity without keyword retrieval.
Request
Looking for the list of fields you can filter on? See Searchable fields in the search reference for the full table of filters.field values (with sortable flags). Use Autocomplete to discover valid values for fields like basic_info.industries, taxonomy.professional_network_industry, or locations.country.

​
Response body

​
Ranked pagination

Ranked search supports pagination in hybrid, lexical, and semantic modes. Set limit to the number of results you want per page, from 1 to 100. Pass next_cursor back as cursor to continue beyond the first 100 results. A ranked search exposes at most 1,000 candidate positions, not an exhaustive list of every matching company. The first 100 candidates are reranked. Later results use retrieval ranking without another reranking pass. Keep the same search, filters, and x-api-version on subsequent requests. You can change limit and authorized fields. Cursors expire 20 minutes after the initial search; paging does not extend that time. If a cursor expires or becomes invalid, restart without cursor. Continue until next_cursor is null, even if a page is short or empty. Company records can change between pages. See the pagination reference for details.

​
Rate limits and credits

Pricing: 0.03 credits per result, plus a per-result charge for each premium group you filter on or receive: taxonomy 0.1; followers, headcount, funding, hiring, software reviews and maps 0.2; technographics 1 on the filter side only. Filtering and receiving bill separately, and sorting is free. Premium groups are returned when you name them in fields, or when your plan includes them at no charge, so a plain request costs the base price. A request with no results does not consume credits. The full table is under Premium fields in search. For your own prices, open the Pricing tab in the dashboard or call /account/endpoints.
  • Rate limit: 30 requests per minute.
Search results are intentionally lightweight so you can explore and segment companies at a low credit cost. When you need the full company profile, use Company Enrich.

Examples

or/nested logic, well-funded-by-country, recently founded.

Pagination & sorting

Cursor-based pagination and sort rules for stable ordering.

Reference

Operators, searchable fields, response fields, validation, errors.

​
Your first search: find a company by domain

The simplest search finds a company by its exact primary domain. You pass a single filter with the = operator.

​
Understanding the response

Every search response has three fields:
  • companies: an array of matching company records. Each record contains crustdata_company_id and the fields you requested in fields.
  • next_cursor — a pagination token. Pass it in the next request to get the next page. null means there are no more pages.
  • total_count is always null for ranked search. For filter-only search, it reports the matching count when available.

​
How to interpret results

  • next_cursor is null: You have reached the last page. No more results.
  • total_count is null: Ranked searches do not report a total. Filter-only totals can also be unavailable. Use next_cursor to decide whether to continue.
  • Empty companies array: On a ranked continuation, records may have changed or no longer match. Continue if next_cursor is present. If it is null, the search has ended.

​
Controlling which fields come back

The fields parameter lets you pick exactly which fields to include. This keeps your responses small and focused. If you omit fields, the API returns all available fields for each company. Each company always includes crustdata_company_id, even when you do not request it. Every field you request is in the response. If a company has no data for a field, its value is null. If a requested group has no data, the whole group is null, even when you asked for one of its sub-fields. For example, a company with no maps data returns {"crustdata_company_id": 1128887, "maps": null} for "fields": ["maps"].

​
Combine filters with and

Real searches need more than one criterion. Wrap multiple conditions inside an op: "and" group to require all of them. This search finds software development companies headquartered in the USA, sorted by headcount (largest first).
Response trimmed for clarity.
The key difference from the first example: instead of a single filters object, you now have a group with op: "and" and a conditions array. Every condition must match for a company to be included. For or and nested logic, or for finding well-funded or recently founded companies, see the Examples below. To walk through large result sets, see Pagination and sorting.

​
Examples

Worked recipes you can copy, paste, and adapt. Each example is a full working request. For the core walkthrough (first search, combining filters with and), see the sections above. For the operator list, field catalog, and validation rules, see Search reference.
This example uses two results per page to keep the responses short. You can request up to 100 per page. Start without a cursor:
For the next page, copy the actual next_cursor into cursor. The cursor strings below are placeholders; company IDs are from the live validation.
Repeat with each returned cursor until next_cursor is null. Keep the query, mode, filters, and API version unchanged. Replaying the same cursor preserves candidate order while the search session remains valid.
Use hybrid mode for broad discovery across keywords and concepts. Add a structured filter when part of your criteria must match exactly.This request finds AI infrastructure companies focused on model deployment and monitoring, then restricts the candidates to companies in the USA.
The country filter is a hard constraint. The API ranks the matching companies against the natural-language query.
Use lexical mode when the words in your query matter more than conceptual similarity. This request looks for company descriptions that match a set of MLOps terms.
Use semantic mode when relevant companies may describe the same capability with different words. This request finds platforms that help engineering teams observe and troubleshoot distributed systems.
Use op: "or" when a company should match any condition. You can also nest and/or groups for complex queries.This search finds companies that are either in the software development industry or have over $5M in total investment, AND are headquartered in the USA.
The outer and requires both conditions: the inner or matches either software development companies or well-funded companies, and the outer condition restricts to US-headquartered companies.
This is a common pattern for sales and investor research: find companies in a specific market with significant funding. This search finds US-based companies with over $10M in total investment, sorted by funding (highest first).
Response trimmed for clarity.
Combine estimated revenue bounds with the latest funding round type, date, and amount. You can also require an investor to appear in the company’s funding history.This search finds companies whose estimated revenue range is entirely between 1Mand1M and 50M, whose latest round was Series A or Series B on or after 2025-01-01, whose latest round raised at least $5M, and that list Sequoia Capital as an investor.
funding.investors contains known investors across the company’s funding history. Combining it with funding.last_* filters means the company has that investor and its latest round matches the other conditions. It does not mean that investor participated in the latest round.
Use comparison operators like > and < on numeric or date fields. This search finds companies founded after 2020, sorted by headcount.
Response trimmed for clarity.
Filter on roles.distribution.<function> to find companies by the number of employees in a specific function — for example, companies with a large engineering team. Combine it with an industry or location filter to narrow the result.
Response trimmed for clarity.
roles.distribution.<function> is filter-only — you can filter on it, but it is not returned in the search response (requesting it in fields returns 400). Select headcount.total or other returnable fields instead. The valid function names are listed in the searchable fields reference.
Filter on the dotted period path headcount.growth_percent.6m to find companies whose 6-month headcount growth exceeds a threshold. The same shape applies to .1m, .3m, .12m and to headcount.growth_absolute.* for absolute employee deltas.
The dotted period paths (headcount.growth_percent.6m, etc.) are filterable but not sortable — passing one as a sorts.field returns 400 "Unsupported columns". Sort on headcount.total (or another sortable field) and use the growth filter to narrow the population.
/company/search returns the growth map under period keys 1m, 3m, 6m, 12m. The same underlying data is also returned by /company/enrich, but with different keys (mom, qoq, six_months, yoy, two_years).
Pass a known company’s crustdata_company_id to competitors.company_ids (or its domains to competitors.websites) to pull the companies Crustdata tracks as its competitors. Here, competitors of OpenAI (631466).
Response trimmed for clarity.
competitors.company_ids and competitors.websites are filter-only — you can filter on them, but they are not returned in the response (passing one in fields returns 400 "Invalid fields"). Select returnable fields like headcount.total instead.
Filter on funding.investors to find every company an investor has backed. This search finds Sequoia Capital portfolio companies, sorted by total funding.
Response trimmed for clarity. Request funding.investors in fields to see the company’s all-time investor list. This field does not identify participants in a specific funding round.
Combine basic_info.company_type with an industry and a country filter — a common first step in alumni or talent-flow workflows. This search finds UK universities, ranked by headcount.
Response trimmed for clarity.
Filter on locations.country with a full country name, such as Canada, or an ISO 3166-1 alpha-3 code, such as CAN. Both forms return the same companies. This search finds companies with headquarters in Canada and more than 100 employees.
Response trimmed for clarity. The response returns the full country name, such as "Canada", for either filter form. See Normalized location facets.
The geo_distance filter finds companies whose headquarters is within a specific distance of a point. Apply it to the locations.headquarters field.This search finds companies with more than 100 employees headquartered within 50 km of Palo Alto.
The value is an object whose centre is given as either a location string (geocoded server-side) or an explicit lat_lng pair (which skips geocoding). If both are supplied, lat_lng wins. distance is required and must be positive; unit is optional and defaults to km (also accepts mi, miles, m, meters, ft, feet). See the geo_distance reference for the full value-object table.

​
Search by explicit coordinates

Use lat_lng when you already have coordinates (for example, from a map picker) or you want to skip the geocoding step. The example below finds companies headquartered within 25 miles of latitude 37.4419, longitude -122.143 (Palo Alto).
The geo_exclude filter is the inverse of geo_distance — it removes companies headquartered inside the radius and keeps everyone else. Use it to carve out a metro you already cover, or to target companies outside a region.This search finds companies that are not headquartered within 100 km of London.
geo_exclude accepts the same value object as geo_distance (location or lat_lng, a required distance, and an optional unit), so you can also exclude a radius around explicit coordinates.
The geo_polygon filter finds companies whose headquarters falls inside a polygon you describe with coordinates. Reach for it when a circle is the wrong shape for the area you care about, such as a sales territory or a metro boundary traced on a map. Apply it to the locations.headquarters field.This search finds companies with more than 100 employees headquartered inside a triangle covering the San Francisco peninsula.
The value is an object with a single points key: a list of [lat, lng] pairs, at least 3 distinct points and at most 1,000. The polygon closes itself, so you do not need to repeat the first point. Coordinates are used as given and are not geocoded. See the geo_polygon reference for the value-object table and the 400 cases.
Filter on followers.count and followers.six_months_growth_percent to find companies with a large, fast-growing audience.
Response trimmed for clarity. followers.count is sortable; the follower-growth fields are filterable but not sortable.
Pass one or more exact primary domains to basic_info.primary_domain with the in operator to resolve known domains in a single call.
A widely shared domain (for example, a platform domain that many small profiles reuse) can return several low-headcount records alongside the primary company. To resolve a single best-match company from a domain, use Company Identify or Company Enrich with exact_match: true.
When you already have crustdata_company_id values (from a previous search or Identify call), fetch those exact records with the in operator. This is the most deterministic way to pull specific companies.
Use revenue.public_markets.ipo_date to find companies that went public in a date window, or revenue.acquisition_status to find acquired companies.Companies that IPO’d in 2020–2021 (1,000+ employees):
Acquired software companies:
Responses trimmed for clarity. revenue.acquisition_status matches the lowercase value "acquired".
Combine funding.last_round_type with funding.last_fundraise_date to find companies that recently raised a specific round. This search finds companies whose latest round was Series A/B/C and closed on or after 2024-01-01.
Response trimmed for clarity. Round-type values are lowercase with underscores (series_a, series_b). Use => / =< for date ranges — >= and <= are not supported.
Filter on taxonomy.categories and basic_info.markets for fine-grained segmentation. This search finds AI companies in the software-development industry, ranked by headcount.
Case does not matter for category and market values under in, but the wording does. Use Autocomplete to find the stored value. For example, the AI category is stored as "Artificial Intelligence (AI)". For public-market tags like "NASDAQ", filter on basic_info.markets.
Filter on taxonomy.primary_naics_detail.naics_code to find companies in one NAICS industry. Name taxonomy.primary_naics_detail and taxonomy.sic_detail_list in fields to get the classification back with each result. This search finds the largest US companies under NAICS 541511, Custom Computer Programming Services.
The taxonomy group also returns both objects, and they have no price of their own. To match on a SIC code instead, filter on taxonomy.sic_detail_list.sic_code. Two sic_code conditions under and match a company whose list holds both codes, even in different entries. Most companies carry no NAICS or SIC classification and return null for both. See the NAICS and SIC note in the search reference.
Use the (.) fuzzy operator on basic_info.name to match name variants and tolerate typos, combined with a basic_info.company_type filter. This search finds privately held companies with “robotics” in the name.
Response trimmed for clarity. (.) is fuzzy (tolerates typos, ignores word order); use [.] for exact token matching.

​
What to do next

  • Paginate and sort — see Pagination and sorting to walk through all matching companies.
  • Look up operators and fields — see Search reference for operators, searchable fields, response fields, validation, and errors.
  • Enrich a company — use Company Enrich to get a detailed profile for a known company.
  • Discover filter values — use Company Autocomplete to find valid values for industries, categories, and countries before building search filters.