POST
/
v0
/
websets
/
{webset}
/
searches
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": "Marketing agencies based in the US, that focus on consumer products. Get brands worked with and city",
  "entity": {
    "type": "company"
  },
  "criteria": [
    {
      "description": "<string>"
    }
  ],
  "behaviour": "override",
  "metadata": {}
}'
{
  "id": "<string>",
  "object": "webset_search",
  "status": "created",
  "query": "<string>",
  "entity": {
    "type": "company"
  },
  "criteria": [
    {
      "description": "<string>",
      "successRate": 50
    }
  ],
  "count": 2,
  "progress": {
    "found": 123,
    "completion": 50
  },
  "metadata": {},
  "canceledAt": "2023-11-07T05:31:56Z",
  "canceledReason": "webset_deleted",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

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

Query describing what you are looking for.

Any URL provided will be crawled and used as context for the search.

Required string length: 1 - 5000
Example:

"Marketing agencies based in the US, that focus on consumer products. Get brands worked with and city"

​
entity
object

Entity the Webset will return results for.

It is not required to provide it, we automatically detect the entity from all the information provided in the query.

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

​
behaviour
enum<string>
default:override

The behaviour of the Search when it is added to a Webset.

  • override: the search will reuse 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.
Available options:
override
​
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,
running,
completed,
canceled
​
query
string
required

The query used to create the search.

Required string length: 1 - 5000
​
entity
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
​
progress
object
required

The progress of the search

​
canceledAt
string | 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
required

The date and time the search was created

​
updatedAt
string
required

The date and time the search was updated

​
metadata
object

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