> For the complete documentation index, see [llms.txt](https://agpt.co/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://agpt.co/docs/integrations/block-integrations/websets_search.md). # Exa Websets Search Blocks for running and managing searches within Exa websets. ## Exa Cancel Webset Search ### What it is Cancel a running webset search ### How it works This block stops a running search operation on a webset. Items already found before cancellation are retained in the webset. Use this when a search is taking too long, returning unexpected results, or is no longer needed. The block returns the number of items found before cancellation. It charges only if Exa's response reports a cost (150 credits per USD). ### Inputs | Input | Description | Type | Required | | ---------- | ----------------------------------- | ---- | -------- | | webset\_id | The ID or external ID of the Webset | str | Yes | | search\_id | The ID of the search to cancel | str | Yes | ### Outputs | Output | Description | Type | | ---------------------------- | ----------------------------------------- | ---- | | error | Error message if the operation failed | str | | search\_id | The ID of the canceled search | str | | status | Status after cancellation | str | | items\_found\_before\_cancel | Number of items found before cancellation | int | | success | Whether the cancellation was successful | str | ### Possible use case **Resource Control**: Stop searches that are taking longer than expected. **Query Refinement**: Cancel searches to adjust query and restart with better parameters. **Partial Results**: Stop searches early when you have enough items for your needs. *** ## Exa Create Webset Search ### What it is Add a new search to an existing webset to find more items ### How it works This block adds a search for up to `count` items (1-1000) to an existing webset. `behavior` decides what happens to existing items: 'append' (default) keeps them and adds the new results, 'override' re-evaluates them against this search's criteria and drops the ones that fail; the legacy 'merge' is sent as 'append'. A search can be limited to imports or websets, leave out the items of others, or become a "hop" search through a scope relationship, which needs a limit of 1-10. Before calling Exa the block rejects more than 5 criteria, a 'custom' entity without a 2-200 character description, and source types other than 'import' or 'webset'. `recall` (on by default) asks Exa to estimate how many matches exist, returned in `expected_results`. With `wait_for_completion` on, the block polls the search (every 5 seconds, backing off to 30) until it is completed, canceled or failed, for up to `polling_timeout` seconds (default 300, max 600); on timeout it returns the status from creation and 0 items instead of failing. It charges only if Exa's response reports a cost (150 credits per USD). ### Inputs | Input | Description | Type | Required | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -------- | | webset\_id | The ID or external ID of the Webset | str | Yes | | query | What to find, in plain language (up to 5,000 characters) | str | Yes | | count | Number of items to find. Exa may find fewer. | int | No | | entity\_type | Kind of result to find; 'auto' lets Exa detect it from the query, 'custom' needs a description | "company" \| "person" \| "article" \| "research\_paper" \| "custom" \| "auto" | No | | entity\_description | What each result is, when the entity type is 'custom' (2-200 characters) | str | No | | criteria | Up to 5 criteria every item must meet. If not provided, auto-detected from query. | List\[str] | No | | behavior | What happens to the webset's existing items: 'override' re-evaluates them against this search's criteria and drops the ones that fail; 'append' keeps them and adds the new results. 'merge' is legacy and is sent as 'append'. | "override" \| "append" \| "merge" | No | | recall | Also estimate how many matching results exist (returned in 'expected\_results') | bool | No | | max\_people\_per\_company | For people searches: try to include at most this many people from the same current employer (soft cap) | int | No | | exclude\_source\_ids | IDs of imports/websets to exclude from results | List\[str] | No | | exclude\_source\_types | Type of each exclude source, in the same order ('import' or 'webset'; defaults to 'import') | List\[str] | No | | scope\_source\_ids | IDs of imports/websets to limit search scope to | List\[str] | No | | scope\_source\_types | Type of each scope source, in the same order ('import' or 'webset'; defaults to 'import') | List\[str] | No | | scope\_relationships | Optional, one per scope source: how results relate to that source's items, for hop searches (e.g. 'CEOs of these companies') | List\[str] | No | | scope\_relationship\_limits | Required for each relationship: related entities to find per source item (1-10) | List\[int] | No | | metadata | Metadata to attach to the search | Dict\[str, Any] | No | | wait\_for\_completion | Wait for the search to complete before returning | bool | No | | polling\_timeout | Maximum time to wait for completion in seconds | int | No | ### Outputs | Output | Description | Type | | ----------------- | --------------------------------------------------------------------- | --------------- | | error | Error message if the operation failed | str | | search\_id | The unique identifier for the created search | str | | webset\_id | The webset this search belongs to | str | | status | Current status of the search | str | | query | The search query | str | | expected\_results | Recall estimation of expected results | Dict\[str, Any] | | items\_found | Number of items found (if wait\_for\_completion was True) | int | | completion\_time | Time taken to complete in seconds (if wait\_for\_completion was True) | float | ### Possible use case **Webset Expansion**: Add more items to existing websets with new or refined queries. **Multi-Criteria Collection**: Run multiple searches with different criteria to build comprehensive datasets. **Iterative Building**: Progressively expand websets based on analysis of initial results. *** ## Exa Find Or Create Search ### What it is Find existing search by query or create new - prevents duplicate searches in workflows ### How it works This block reads the webset and looks for a search whose query matches yours, ignoring case and surrounding spaces. If one exists it returns that search with its items found so far and `was_created` false; otherwise it creates a search with your query, count, entity type and behavior and returns it straight away with 0 items. The default behavior here is 'override', which re-evaluates the webset's existing items against the new search and drops the ones that fail; choose 'append' to keep them. The 'custom' entity type always fails, because this block has no description input and Exa needs one. It charges only if Exa's response reports a cost (150 credits per USD). ### Inputs | Input | Description | Type | Required | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | -------- | | webset\_id | The ID or external ID of the Webset | str | Yes | | query | Search query to find or create | str | Yes | | count | Number of items to find (only used if creating new search) | int | No | | entity\_type | Entity type (only used if creating) | "company" \| "person" \| "article" \| "research\_paper" \| "custom" \| "auto" | No | | behavior | Only used if creating. What happens to the webset's existing items: 'override' re-evaluates them against this search's criteria and drops the ones that fail; 'append' keeps them and adds the new results. 'merge' is legacy and is sent as 'append'. | "override" \| "append" \| "merge" | No | ### Outputs | Output | Description | Type | | ------------ | ---------------------------------------------------------- | ---- | | error | Error message if the operation failed | str | | search\_id | The search ID (existing or new) | str | | webset\_id | The webset ID | str | | status | Current search status | str | | query | The search query | str | | was\_created | True if search was newly created, False if already existed | bool | | items\_found | Number of items found (0 if still running) | int | ### Possible use case **Retry-Safe Workflows**: Safely handle workflow retries without creating duplicate searches. **Deduplication**: Avoid running the same search multiple times when called from different workflow branches. **Efficient Operations**: Skip search creation when results from identical queries already exist. *** ## Exa Get Webset Search ### What it is Get the status and details of a webset search ### How it works This block retrieves one webset search and returns its status, query, entity type, criteria, target count, behavior, scope and exclude sources, progress (found, analyzed, completion, time left) and the recall estimate when one was requested. For a canceled search it also gives the time and reason (webset\_deleted, webset\_canceled or out\_of\_credits). Use this to monitor search progress, verify search configuration, or investigate search behavior when results don't match expectations. It charges only if Exa's response reports a cost (150 credits per USD). ### Inputs | Input | Description | Type | Required | | ---------- | ----------------------------------- | ---- | -------- | | webset\_id | The ID or external ID of the Webset | str | Yes | | search\_id | The ID of the search to retrieve | str | Yes | ### Outputs | Output | Description | Type | | ------------------------- | -------------------------------------------------------------------------- | ---------------------- | | error | Error message if the operation failed | str | | search\_id | The unique identifier for the search | str | | status | Current status: created, pending, running, completed or canceled | str | | query | The search query | str | | entity\_type | Type of entity being searched | str | | criteria | Criteria used for verification | List\[Dict\[str, Any]] | | count | Number of items the search aims to find | int | | behavior | How the search treats existing items: override or append | str | | max\_people\_per\_company | Soft cap on people per employer, if one was requested | int | | exclude | Imports or websets whose items this search leaves out | List\[Dict\[str, Any]] | | scope | Imports or websets the search is limited to (empty for the whole web) | List\[Dict\[str, Any]] | | progress | Search progress information | Dict\[str, Any] | | recall | Recall estimation information | Dict\[str, Any] | | created\_at | When the search was created | str | | updated\_at | When the search was last updated | str | | canceled\_at | When the search was canceled (if applicable) | str | | canceled\_reason | Why it was canceled: webset\_deleted, webset\_canceled or out\_of\_credits | str | | metadata | Metadata attached to the search | Dict\[str, Any] | ### Possible use case **Progress Tracking**: Monitor search completion and items found during long-running operations. **Configuration Review**: Retrieve search details to verify criteria and settings are correct. **Debugging**: Investigate search configuration when results don't match expectations. *** --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://agpt.co/docs/integrations/block-integrations/websets_search.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.