---
updatedAt: 2026-11-02T22:43:56.000Z
agentTools:
  projectIndex: https://data.crunchbase.com/llms.txt
---

# Search API basics

Understand fields, filters, sorting, and search results.

Use the Search API to find entities that match criteria. This page explains how to adapt a query; for a complete first search, follow [Find companies with the Search API](https://data.crunchbase.com/docs/find-companies-with-the-search-api).

## Request structure

Send a `POST` request to `https://api.crunchbase.com/v4/data/searches/{collection}`, replacing `{collection}` with a supported collection such as `organizations`. Collections, fields, and operators depend on your licensed package; use its <a href="https://data.crunchbase.com/reference" target="_blank" rel="noopener noreferrer">API Reference</a>.

Authenticate with your provisioned key in the `X-cb-user-key` header. Send JSON with `Content-Type: application/json` and request JSON with `Accept: application/json`. See <a href="https://data.crunchbase.com/docs/api-essentials#authentication" target="_blank" rel="noopener noreferrer">authentication setup</a>.

| Body property | Purpose                                                                                                                                                    |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `field_ids`   | Required array of fields to return for each matching entity.                                                                                               |
| `query`       | Required array of filter predicates. Separate predicates are combined with AND.                                                                            |
| `order`       | Optional array of sort instructions, each specifying `field_id` and `sort` (`asc` or `desc`).                                                              |
| `limit`       | Number of results to return per page. Set it explicitly; the documented range is 1–1000, with a default of 100. Check your endpoint for applicable limits. |
| `after_id`    | UUID of the last result on the preceding page, for forward pagination.                                                                                     |
| `before_id`   | UUID of the first result on the preceding page, for backward pagination. Do not combine it with `after_id`.                                                |

This example body searches organizations classified as SaaS, returns their identifiers and descriptions, and sorts by organization rank:

```json
{
  "field_ids": ["identifier", "short_description"],
  "query": [
    {
      "type": "predicate",
      "field_id": "categories",
      "operator_id": "includes",
      "values": ["5c4e6926-5ff7-b188-0892-c8eb036c5ace"]
    }
  ],
  "order": [{"field_id": "rank_org", "sort": "asc"}],
  "limit": 3
}
```

The UUID identifies the SaaS category. The <a href="https://data.crunchbase.com/docs/find-companies-with-the-search-api#1-choose-the-industry-and-location" target="_blank" rel="noopener noreferrer">walkthrough’s filter-selection step</a> shows how to discover and verify it with Autocomplete. This is a request body for `POST /v4/data/searches/organizations`, not a complete terminal command.

## Select fields separately from filters

`field_ids` controls the data returned. `query` controls which entities match. Adding `website_url` to `field_ids` requests that field; it does not restrict the results to organizations with a website.

Use the selected endpoint’s request schema to find supported field IDs, filter fields, and operators. Use its response schema to understand each returned value’s shape. A field available for output is not automatically supported for filtering or sorting.

Request only the fields you need. Treat optional values as optional: an omitted field is not equivalent to zero, false, or an empty relationship. HTTP 200 alone does not confirm that every requested field was returned.

## Build a predicate

Each predicate identifies a field, an operator, and its input values:

| Property            | Meaning                                                    |
| ------------------- | ---------------------------------------------------------- |
| `type: "predicate"` | Identifies a filter predicate.                             |
| `field_id`          | The field to evaluate, such as `categories`.               |
| `operator_id`       | A supported comparison for that field, such as `includes`. |
| `values`            | Inputs in the format required by that field and operator.  |

Use <a href="/docs/search-fields-and-operators" target="_blank" rel="noopener noreferrer">Search fields and operators</a> to choose valid `field_id` and `operator_id` combinations for your collection. Do not assume the same operator or value format works across all fields. Identifier filters may require UUIDs, while dates, numbers, and monetary values have their own formats. Check the endpoint schema before substituting values.

For category and location criteria, use <a href="https://data.crunchbase.com/docs/autocomplete" target="_blank" rel="noopener noreferrer">Autocomplete</a> and inspect the suggested entity’s type, name, permalink, and description. Resolve ambiguous matches before using an identifier.

## Combining filters: AND and OR

Separate predicates in `query` are combined with **AND**: every predicate must match. A SaaS category predicate plus a San Francisco headquarters predicate means SaaS **and** headquartered in that location.

Within a predicate, the operator determines how multiple values are matched:

* `includes`, where supported, matches any listed value. Two category UUIDs mean either category.
* `includes_all`, where supported, requires all listed values.

Do not assume every operator treats its values as alternatives. For example, the values for a range operator describe a range rather than independent alternatives.

For **OR across separate predicates**, make separate searches, paginate each as needed, combine the results, and remove duplicates by entity UUID. Do not add an unsupported OR wrapper to the query array.

## Sort and size the results

Each `order` entry specifies a supported `field_id` and `sort: "asc"` or `sort: "desc"`. The example uses ascending `rank_org`, so lower organization-rank values come first. The sort schema also supports `nulls: "first"` or `nulls: "last"` for positioning missing values.

Set an explicit order when your workflow depends on it; do not interpret an unspecified order as a recommendation or a stable ranking. Sorting does not freeze the dataset.

`limit` sets a page size, not the total number of matching entities. A page of three results is not a complete market list. Request additional pages when needed.

## Read the response

Search returns an `entities` array. For each result:

| Path                                      | Meaning                                             |
| ----------------------------------------- | --------------------------------------------------- |
| `entities[i].uuid`                        | The result’s entity UUID.                           |
| `entities[i].properties`                  | The requested fields returned for that entity.      |
| `entities[i].properties.identifier`       | The identifier object, when requested and returned. |
| `entities[i].properties.identifier.value` | The display name.                                   |

Here, `i` is the array index. Check that the array contains an item before reading it. Unlike Autocomplete, Search places the requested fields inside `properties`.

An empty `entities` array means this request returned no results. A missing or malformed array is a response problem to investigate, not an empty result set.

To enrich a match, pass its UUID to the appropriate <a href="https://data.crunchbase.com/docs/entity-lookup" target="_blank" rel="noopener noreferrer">Entity Lookup endpoint</a>. Request cards there; `card_ids` is not part of this Search request body. The <a href="https://data.crunchbase.com/docs/find-companies-with-the-search-api#4-retrieve-details-for-one-result" target="_blank" rel="noopener noreferrer">walkthrough</a> demonstrates the handoff and checks that the returned UUID matches.

## Paginate through results

For forward pagination, use the last returned entity’s `uuid` as `after_id` in the next request body. Keep the query, fields, order, and limit unchanged. Do not send `before_id` and `after_id` together.

Follow <a href="https://data.crunchbase.com/docs/paginate-search-results" target="_blank" rel="noopener noreferrer">Paginate search results</a> for the complete loop, stopping conditions, duplicate handling, and repeated-cursor checks.

Pagination does not provide a transactional snapshot across requests. Records can change during traversal; follow the pagination guide’s reconciliation guidance.

## Diagnose a query

* **Invalid filter or request:** inspect the response message and verify the field, operator, value type, and JSON syntax against your package’s endpoint schema.
* **No matches:** confirm the identifiers and test predicates individually to isolate the restriction. Restore the intended criteria before reporting results.
* **Missing fields:** check exact field names and package availability. Preserve unknown values rather than inferring business facts.
* **Authentication, access, throttling, or transient errors:** follow <a href="https://data.crunchbase.com/docs/api-essentials" target="_blank" rel="noopener noreferrer">authentication, limits, and retry guidance</a>. Repeating an invalid query unchanged will not repair it.

## Related guides

* [Find companies with the Search API](https://data.crunchbase.com/docs/find-companies-with-the-search-api) — a complete search-to-lookup walkthrough.
* [Search API examples](https://data.crunchbase.com/docs/search-api-examples) — additional query examples.
* [Paginate search results](https://data.crunchbase.com/docs/paginate-search-results) — retrieve further pages reliably.