Skip to main content
POST
/
v0
/
websets
/
{webset}
/
searches
cURL
curl --request POST \
  --url https://api.exa.ai/websets/v0/websets/{webset}/searches \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "count": 2,
  "query": "<string>",
  "entity": {
    "type": "company"
  },
  "criteria": [
    {
      "description": "<string>"
    }
  ],
  "exclude": [
    {
      "source": "import",
      "id": "<string>"
    }
  ],
  "scope": [
    {
      "source": "import",
      "id": "<string>",
      "relationship": {
        "definition": "<string>",
        "limit": 5.5
      }
    }
  ],
  "recall": true,
  "behavior": "override",
  "metadata": {}
}
'
{
  "id": "<string>",
  "object": "webset_search",
  "status": "created",
  "websetId": "<string>",
  "query": "<string>",
  "entity": {
    "type": "company"
  },
  "criteria": [
    {
      "description": "<string>",
      "successRate": 50
    }
  ],
  "count": 2,
  "exclude": [
    {
      "source": "import",
      "id": "<string>"
    }
  ],
  "scope": [
    {
      "source": "import",
      "id": "<string>",
      "relationship": {
        "definition": "<string>",
        "limit": 5.5
      }
    }
  ],
  "progress": {
    "found": 123,
    "analyzed": 123,
    "completion": 50,
    "timeLeft": 123
  },
  "recall": {
    "expected": {
      "total": 123,
      "confidence": "high",
      "bounds": {
        "min": 123,
        "max": 123
      }
    },
    "reasoning": "<string>"
  },
  "canceledAt": "2023-11-07T05:31:56Z",
  "canceledReason": "webset_deleted",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "behavior": "override",
  "metadata": {}
}

Authorizations

​
x-api-key
string
header
required

Your Exa API key

Path Parameters

​
webset
string
required

The id of the Webset

Body

application/json
​
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.

Required range: x >= 1
​
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.

Required string length: 1 - 5000
​
entity
Company · object

Entity the search will return results for.

It is not required to provide it, we automatically detect the entity from all the information provided in the query. Only use this when you need more fine control.

​
criteria
CreateCriterionParameters · object[]

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.

Required array length: 1 - 5 elements
​
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.

​
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.

​
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
enum<string>
default:override

How this search interacts with existing items in the Webset:

  • override: Replace existing items and evaluate all items against new criteria
  • append: Add new items to existing ones, keeping items that match the new criteria
Available options:
override,
append
​
metadata
object

Set of key-value pairs you want to associate with this object.

Response

200 - application/json

Webset Search created

​
id
string
required

The unique identifier for the search

​
object
string
default:webset_search
required
Allowed value: "webset_search"
​
status
enum<string>
required

The status of the search

Available options:
created,
pending,
running,
completed,
canceled
​
websetId
string
required

The unique identifier for the Webset this search belongs to

​
query
string
required

The query used to create the search.

Required string length: 1 - 5000
​
entity
Company · object
required

The entity the search will return results for.

When no entity is provided during creation, we will automatically select the best entity based on the query.

​
criteria
object[]
required

The criteria the search will use to evaluate the results. If not provided, we will automatically generate them for you.

​
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.

Required range: x >= 1
​
exclude
object[]
required

Sources (existing imports or websets) used to omit certain results to be found during the search.

​
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.

​
progress
object
required

The progress of the search

​
recall
object
required

Recall metrics for the search, null if not yet computed or requested.

​
canceledAt
string<date-time> | null
required

The date and time the search was canceled

​
canceledReason
enum<string> | null
required

The reason the search was canceled

Available options:
webset_deleted,
webset_canceled
​
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

​
behavior
enum<string>
default:override

The behavior of the search when it is added to a Webset.

  • override: the search will replace the existing Items found in the Webset and evaluate them against the new criteria. Any Items that don't match the new criteria will be discarded.
  • append: the search will add the new Items found to the existing Webset. Any Items that don't match the new criteria will be discarded.
Available options:
override,
append
​
metadata
object

Set of key-value pairs you want to associate with this object.