---
title: "Create a Webset"
method: POST
path: "/v0/websets"
tags: ["Websets"]
---

# Create a Webset

`POST /v0/websets`

Creates a new Webset with optional search, import, and enrichment configurations. The Webset will automatically begin processing once created.

You can specify an `externalId` to reference the Webset with your own identifiers for easier integration.

## Request body

- CreateWebsetParameters
  - `title` string, nullable — Optional name that appears anywhere the Webset is displayed. Leave empty to have Exa generate one automatically.
  - `search` object — Create initial search for the Webset.
    - `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.
    - `count` number — Number of Items the Webset will attempt to find. The actual number of Items found may be less than this number depending on the search complexity.
    - `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.
    - `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.
    - `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 or websets). 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
  - `import` object[] — Import data from existing Websets and Imports into this Webset.
    - `source` 'import' | 'webset', required
    - `id` string, required — The ID of the source to import.
    - `evaluate` boolean — When true, items from this import will be evaluated against the search criteria. Requires a search to be provided.
  - `enrichments` CreateEnrichmentParameters[] — Add enrichments to extract additional data from found items. Enrichments automatically search for and extract specific information (like contact details, funding data, employee counts, etc.) from each item added to your Webset.
    - `description` string, required — Provide a description of the enrichment task you want to perform to each Webset Item.
    - `format` 'text' | 'date' | 'number' | 'options' | 'email' | 'phone' | 'url' — Format of the enrichment response. We automatically select the best format based on the description. If you want to explicitly specify the format, you can do so here.
    - `options` object[] — When the format is options, the different options for the enrichment agent to choose from.
      - `label` string, required — The label of the option
    - `metadata` object — Set of key-value pairs you want to associate with this object.
  - `exclude` object[] — Global exclusion sources (existing imports or websets) that apply to all operations within this Webset. Any results found within these sources will be omitted across all search and import operations.
    - `source` 'import' | 'webset', required
    - `id` string, required — The ID of the source to exclude.
  - `externalId` string — The external identifier for the webset. You can use this to reference the Webset by your own internal identifiers.
  - `metadata` object — Set of key-value pairs you want to associate with this object.

## Response `201`

Webset created

- Webset
  - `id` string, required — The unique identifier for the webset
  - `object` 'webset', required
  - `status` 'idle' | 'pending' | 'running' | 'paused', required — The status of the webset
  - `externalId` string, nullable, required — The external identifier for the webset
  - `title` string, nullable, required — The title of the webset
  - `searches` WebsetSearch[], required — The searches that have been performed on the webset.
    - `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
  - `imports` Import[], required — Imports that have been performed on the webset.
    - `id` string, required — The unique identifier for the Import
    - `object` 'import', required — The type of object
    - `status` 'pending' | 'processing' | 'completed' | 'failed' | 'canceled', required — The status of the Import
    - `format` 'csv' | 'webset', required — The format of the import.
    - `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
    - `title` string, required — The title of the import
    - `count` number, required — The number of entities in the import
    - `metadata` object, required — Set of key-value pairs you want to associate with this object.
    - `failedReason` 'invalid_format' | 'invalid_file_content' | 'missing_identifier', nullable, required — The reason the import failed
    - `failedAt` string, date-time, nullable, required — When the import failed
    - `failedMessage` string, nullable, required — A human readable message of the import failure
    - `createdAt` string, date-time, required — When the import was created
    - `updatedAt` string, date-time, required — When the import was last updated
  - `enrichments` WebsetEnrichment[], required — The Enrichments to apply to the Webset Items.
    - `id` string, required — The unique identifier for the enrichment
    - `object` 'webset_enrichment', required
    - `status` 'pending' | 'canceled' | 'completed', required — The status of the enrichment
    - `websetId` string, required — The unique identifier for the Webset this enrichment belongs to.
    - `title` string, nullable, required — The title of the enrichment. This will be automatically generated based on the description and format.
    - `description` string, required — The description of the enrichment task provided during the creation of the enrichment.
    - `format` 'text' | 'date' | 'number' | 'options' | 'email' | 'phone' | 'url', required
    - `options` object[], nullable, required — When the format is options, the different options for the enrichment agent to choose from.
      - `label` string, required — The label of the option
    - `instructions` string, nullable, required — The instructions for the enrichment Agent. This will be automatically generated based on the description and format.
    - `metadata` object — The metadata of the enrichment
    - `createdAt` string, date-time, required — The date and time the enrichment was created
    - `updatedAt` string, date-time, required — The date and time the enrichment was updated
  - `monitors` Monitor[], required — The Monitors for the Webset.
    - `id` string, required — The unique identifier for the Monitor
    - `object` 'monitor', required — The type of object
    - `status` 'enabled' | 'disabled', required — The status of the Monitor
    - `websetId` string, required — The id of the Webset the Monitor belongs to
    - `cadence` object, required — How often the monitor will run
      - `cron` string, required — Cron expression for monitor cadence (must be a valid Unix cron with 5 fields). The schedule must trigger at most once per day.
      - `timezone` string — IANA timezone (e.g., "America/New_York")
    - `behavior` object, required — Behavior to perform when monitor runs
      - `type` 'search', required
      - `config` object, required — Specify the search parameters for the Monitor. By default, the search parameters (query, entity and criteria) from the last search are used when no parameters are provided.
        - `query` string — The query to search for. By default, the query from the last search is used.
        - `criteria` object[] — The criteria to search for. By default, the criteria from the last search is used.
          - `description` string, required
        - `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
        - `count` number, required — The maximum number of results to find
        - `behavior` 'override' | 'append' — The behaviour of the Search when it is added to a Webset.
    - `lastRun` MonitorRun, required
      - `id` string, required — The unique identifier for the Monitor Run
      - `object` 'monitor_run', required — The type of object
      - `status` 'created' | 'running' | 'completed' | 'canceled' | 'failed', required — The status of the Monitor Run
      - `monitorId` string, required — The monitor that the run is associated with
      - `type` 'search' | 'refresh', required — The type of the Monitor Run
      - `completedAt` string, date-time, nullable, required — When the run completed
      - `failedAt` string, date-time, nullable, required — When the run failed
      - `failedReason` string, nullable, required — The reason the run failed
      - `canceledAt` string, date-time, nullable, required — When the run was canceled
      - `createdAt` string, date-time, required — When the run was created
      - `updatedAt` string, date-time, required — When the run was last updated
    - `nextRunAt` string, date-time, nullable, required — Date and time when the next run will occur in
    - `metadata` object, required — Set of key-value pairs you want to associate with this object.
    - `createdAt` string, date-time, required — When the monitor was created
    - `updatedAt` string, date-time, required — When the monitor was last updated
  - `excludes` object[] — The Excludes sources (existing imports or websets) that apply to all operations within this Webset. Any results found within these sources will be omitted across all search and import operations.
    - `source` 'import' | 'webset', required
    - `id` string, required
  - `metadata` object — Set of key-value pairs you want to associate with this object.
  - `dashboardUrl` string, uri, required — The URL to view the webset in the Exa dashboard
  - `createdAt` string, date-time, required — The date and time the webset was created
  - `updatedAt` string, date-time, required — The date and time the webset was updated

## Other responses

- `409` — Webset with this externalId already exists

---

[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)