How It Works

The Websets API operates as an asynchronous search system. When you create a Webset, it automatically starts searching and verifying results based on your criteria. Let’s dive into each part of the process.

​

Creating Your First Search

The process starts when you create a Webset. Here’s how it flows:

​

1. Initial Request

Start by providing a search configuration:

{
  "search": {
    "query": "AI companies in Europe that raised Series A funding",
    "count": 50
  }
}

You can optionally specify:

• An entity.type to define what you’re looking for
• Custom criteria for verification
• enrichments to extract specific data points
• metadata for your own tracking

​

2. Webset Creation

When your request is received:

1. A new Webset is created with status running
2. A webset.created event is emitted
3. The search process begins automatically

​

3. Search Process

The search flows through several stages:

1. Initialization

   • A new WebsetSearch is created
   • Status is set to running
   • webset.search.created event is emitted

2. Discovery & Verification

   • The system starts retrieving results leveraging Exa Search and verifies each one
   • Items that pass verification and match your search criteria are automatically added to your Webset
   • Each new item triggers a webset.item.created event
   • Items are immediately available through the list endpoint

3. Enrichment (if configured)

   • Each item is processed through specified enrichments
   • webset.item.enriched events are emitted as results come in
   • Enrichment results are added to the item’s data

4. Completion

   • When the search finds all items, its status changes to completed
   • A webset.search.completed event is emitted
   • If no other operations are running, you’ll receive a webset.idle event

​

Accessing Results

You can access your data throughout the process:

1. Real-time Access

   • Use the list endpoint to paginate through items
   • Listen for item events (webset.item.created and webset.item.enriched) to process results as they arrive

2. Bulk Export

   • Available once the Webset becomes idle
   • Includes all items with their content, verifications and enrichments
   • Useful for processing the complete dataset

​

Running Additional Searches

You can create additional searches on the same Webset at any time. Each new search:

• Follows the same event flow as the initial search
• Can run in parallel with other enrichment operations (not other searches for now)
• Maintains its own progress tracking
• Contributes to the overall Webset state

​

Control Operations

Manage your searches with:

• Cancel specific searches
• Cancel all operations