---
title: "Create a Search"
method: POST
path: "/v0/websets/{webset}/searches"
tags: ["Searches"]
---

# Create a Search

`POST /v0/websets/{webset}/searches`

Creates a new Search for the Webset.

The default behavior is to reuse the previous Search results and evaluate them against the new criteria.

## Path parameters

- `webset` string, required

## Request body

- CreateWebsetSearchParameters
  - `count` number, required — Number of Items the Search will attempt to find. The actual number of Items found may be less than this number depending on the query complexity.
  - `query` string, required — Natural language search query describing what you are looking for. Be specific and descriptive about your requirements, characteristics, and any constraints that help narrow down the results. Any URLs provided will be crawled and used as additional context for the search.
  - `entity` union
    - CompanyEntity
      - `type` 'company', required
    - PersonEntity
      - `type` 'person', required
    - ArticleEntity
      - `type` 'article', required
    - ResearchPaperEntity
      - `type` 'research_paper', required
    - CustomEntity
      - `type` 'custom', required
      - `description` string, required
  - `criteria` CreateCriterionParameters[] — Criteria every item is evaluated against. It's not required to provide your own criteria, we automatically detect the criteria from all the information provided in the query. Only use this when you need more fine control.
    - `description` string, required — The description of the criterion
  - `maxPeoplePerCompany` integer — Optional soft cap for people searches. When set, the search will try to include at most this many matching people from the same current employer company.
  - `exclude` object[] — Sources (existing imports or websets) to exclude from search results. Any results found within these sources will be omitted to prevent finding them during search.
    - `source` 'import' | 'webset', required
    - `id` string, required — The ID of the source to exclude.
  - `scope` object[] — Limit the search to specific sources (existing imports). Any results found within these sources matching the search criteria will be included in the Webset.
    - `source` 'import' | 'webset', required
    - `id` string, required — The ID of the source to search.
    - `relationship` object
      - `definition` string, required — What the relationship of the entities you hope to find is relative to the entities contained in the provided source.
      - `limit` number, required
  - `recall` boolean — Whether to provide an estimate of how many total relevant results could exist for this search. Result of the analysis will be available in the `recall` field within the search request.
  - `behavior` 'override' | 'append'
  - `metadata` object — Set of key-value pairs you want to associate with this object.

## Response `200`

Webset Search created

- WebsetSearch
  - `id` string, required — The unique identifier for the search
  - `object` 'webset_search', required
  - `status` 'created' | 'pending' | 'running' | 'completed' | 'canceled', required — The status of the search
  - `websetId` string, required — The unique identifier for the Webset this search belongs to
  - `query` string, required — The query used to create the search.
  - `entity` union, required
    - CompanyEntity
      - `type` 'company', required
    - PersonEntity
      - `type` 'person', required
    - ArticleEntity
      - `type` 'article', required
    - ResearchPaperEntity
      - `type` 'research_paper', required
    - CustomEntity
      - `type` 'custom', required
      - `description` string, required
  - `criteria` object[], required — The criteria the search will use to evaluate the results. If not provided, we will automatically generate them for you.
    - `description` string, required — The description of the criterion
    - `successRate` number, required — Value between 0 and 100 representing the percentage of results that meet the criterion.
  - `count` number, required — The number of results the search will attempt to find. The actual number of results may be less than this number depending on the search complexity.
  - `maxPeoplePerCompany` integer, nullable, required — The soft cap requested for matching people from the same current employer company, or null when no cap was requested.
  - `behavior` 'override' | 'append'
  - `exclude` object[], required — Sources (existing imports or websets) used to omit certain results to be found during the search.
    - `source` 'import' | 'webset', required
    - `id` string, required
  - `scope` object[], required — The scope of the search. By default, there is no scope - thus searching the web. If provided during creation, the search will only be performed on the sources provided.
    - `source` 'import' | 'webset', required
    - `id` string, required
    - `relationship` object
      - `definition` string, required — What the relationship of the entities you hope to find is relative to the entities contained in the provided source.
      - `limit` number, required
  - `progress` object, required — The progress of the search
    - `found` number, required — The number of results found so far
    - `analyzed` number, required — The number of results analyzed so far
    - `completion` number, required — The completion percentage of the search
    - `timeLeft` number, nullable, required — The estimated time remaining in seconds, null if unknown
  - `recall` object, nullable, required — Recall metrics for the search, null if not yet computed or requested.
    - `expected` object, required
      - `total` number, required — The estimated total number of potential matches
      - `confidence` 'high' | 'medium' | 'low', required — The confidence in the estimate
      - `bounds` object, required
        - `min` number, required — The minimum estimated total number of potential matches
        - `max` number, required — The maximum estimated total number of potential matches
    - `reasoning` string, required — The reasoning for the estimate
  - `metadata` object — Set of key-value pairs you want to associate with this object.
  - `canceledAt` string, date-time, nullable, required — The date and time the search was canceled
  - `canceledReason` 'webset_deleted' | 'webset_canceled' | 'out_of_credits', required
  - `createdAt` string, date-time, required — The date and time the search was created
  - `updatedAt` string, date-time, required — The date and time the search was updated

---

[API](https://skmtc.net/exa/apis/exa-public-api.md) · [All operations](https://skmtc.net/exa/apis/exa-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/exa/exa-public-api/revisions/5c7114e0ef43/schema)