openapi: 3.1.0 info: title: Exa Agent Websets API version: 2.0.0 description: Exa Agent API - subset of the Exa Public API. servers: - url: https://api.exa.ai security: - apiKey: [] - bearer: [] tags: - name: Websets paths: /v0/websets: servers: - url: https://api.exa.ai/websets post: description: '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.' operationId: websets-create parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateWebsetParameters' responses: '201': description: Webset created content: application/json: schema: $ref: '#/components/schemas/Webset' headers: X-Request-Id: schema: type: string description: Unique identifier for the request. example: req_N6SsgoiaOQOPqsYKKiw5 required: true '409': description: Webset with this externalId already exists headers: X-Request-Id: schema: type: string description: Unique identifier for the request. example: req_N6SsgoiaOQOPqsYKKiw5 required: true summary: Create a Webset tags: - Websets security: - apiKey: [] - bearer: [] x-codeSamples: - lang: javascript label: JavaScript source: "// npm install exa-js\nimport Exa from 'exa-js';\nconst exa = new Exa('YOUR_EXA_API_KEY');\n\nconst webset = await exa.websets.create({\n search: {\n query: \"Tech companies in San Francisco\",\n count: 10\n }\n});\n\nconsole.log(`Created webset: ${webset.id}`);" - lang: python label: Python source: "# pip install exa-py\nfrom exa_py import Exa\nexa = Exa(api_key='YOUR_EXA_API_KEY')\n\nwebset = exa.websets.create(params={\n 'search': {\n 'query': 'Tech companies in San Francisco',\n 'count': 10\n }\n})\n\nprint(f'Created webset: {webset.id}')" - lang: javascript label: Filter within CSV Import source: "// Filter a CSV import by criteria (no top-level import needed)\nimport Exa from 'exa-js';\nconst exa = new Exa('YOUR_EXA_API_KEY');\n\nconst webset = await exa.websets.create({\n search: {\n query: \"people who changed jobs\",\n criteria: [\"changed jobs in the last 6 months\"],\n count: 10,\n scope: [{\n source: \"import\",\n id: \"import_abc123\" // Your existing import ID\n }]\n }\n});\n\nconsole.log(`Filtered webset: ${webset.id}`);" - lang: python label: Filter within CSV Import source: "from exa_py import Exa\nexa = Exa(api_key='YOUR_EXA_API_KEY')\n\nwebset = exa.websets.create(params={\n 'search': {\n 'query': 'people who changed jobs',\n 'criteria': ['changed jobs in the last 6 months'],\n 'count': 10,\n 'scope': [{\n 'source': 'import',\n 'id': 'import_abc123' # Your existing import ID\n }]\n }\n})\n\nprint(f'Filtered webset: {webset.id}')" - lang: javascript label: Hop Search (Graph Traversal) source: "// Find related entities (e.g., companies -> investors)\nimport Exa from 'exa-js';\nconst exa = new Exa('YOUR_EXA_API_KEY');\n\nconst webset = await exa.websets.create({\n search: {\n query: \"investors\",\n scope: [{\n source: \"webset\",\n id: \"webset_companies\",\n relationship: {\n definition: \"investors of\",\n limit: 3 // Find up to 3 investors per company\n }\n }]\n }\n});\n\nconsole.log(`Hop search webset: ${webset.id}`);" - lang: python label: Hop Search (Graph Traversal) source: "from exa_py import Exa\nexa = Exa(api_key='YOUR_EXA_API_KEY')\n\nwebset = exa.websets.create(params={\n 'search': {\n 'query': 'investors',\n 'scope': [{\n 'source': 'webset',\n 'id': 'webset_companies',\n 'relationship': {\n 'definition': 'investors of',\n 'limit': 3 # Find up to 3 investors per company\n }\n }]\n }\n})\n\nprint(f'Hop search webset: {webset.id}')" get: description: 'Returns a list of Websets. You can paginate through the results using the `cursor` parameter. You can filter results using the `search` parameter to find Websets by ID, external ID, or title.' operationId: websets-list parameters: - name: cursor required: false in: query description: The cursor to paginate through the results schema: minLength: 1 type: string - name: limit required: false in: query description: The number of Websets to return schema: minimum: 1 maximum: 100 default: 25 type: number - name: search required: false in: query description: Search term to filter Websets by ID, external ID, or title schema: minLength: 2 maxLength: 50 type: string responses: '200': description: List of Websets content: application/json: schema: $ref: '#/components/schemas/ListWebsetsResponse' headers: X-Request-Id: schema: type: string description: Unique identifier for the request. example: req_N6SsgoiaOQOPqsYKKiw5 required: true summary: List all Websets tags: - Websets security: - apiKey: [] - bearer: [] x-codeSamples: - lang: javascript label: JavaScript source: "// npm install exa-js\nimport Exa from \"exa-js\";\nconst exa = new Exa(\"YOUR_EXA_API_KEY\");\n\n// List websets with optional pagination\nconst websets = await exa.websets.list({\n limit: 20, // Optional: max results per page\n});\n\nconsole.log(`Found ${websets.data.length} websets`);\nwebsets.data.forEach((webset) => {\n console.log(`- ${webset.id}: ${webset.status}`);\n});" - lang: python label: Python source: "# pip install exa-py\nfrom exa_py import Exa\n\nexa = Exa(\"YOUR_EXA_API_KEY\")\n\n# List websets with optional pagination\nwebsets_response = exa.websets.list(\n limit=20 # Optional: max results per page\n)\n\nprint(f\"Found {len(websets_response.data)} websets\")\nfor webset in websets_response.data:\n print(f\"- {webset.id}: {webset.status}\")" /v0/websets/{id}: servers: - url: https://api.exa.ai/websets get: operationId: websets-get parameters: - name: id required: true in: path description: The id or externalId of the Webset. schema: type: string - name: expand required: false in: query description: Expand the response with the specified resources schema: type: array items: type: string enum: - items responses: '200': description: Webset content: application/json: schema: $ref: '#/components/schemas/GetWebsetResponse' headers: X-Request-Id: schema: type: string description: Unique identifier for the request. example: req_N6SsgoiaOQOPqsYKKiw5 required: true '404': description: Webset not found headers: X-Request-Id: schema: type: string description: Unique identifier for the request. example: req_N6SsgoiaOQOPqsYKKiw5 required: true summary: Get a Webset tags: - Websets security: - apiKey: [] - bearer: [] x-codeSamples: - lang: javascript label: JavaScript source: '// npm install exa-js import Exa from "exa-js"; const exa = new Exa("YOUR_EXA_API_KEY"); const webset = await exa.websets.get("webset_id"); console.log(`Webset: ${webset.id} - ${webset.status}`);' - lang: python label: Python source: '# pip install exa-py from exa_py import Exa exa = Exa("YOUR_EXA_API_KEY") webset = exa.websets.get("webset_id") print(f"Webset: {webset.id} - {webset.status}")' post: operationId: websets-update parameters: - name: id required: true in: path description: The id or externalId of the Webset schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateWebsetRequest' responses: '200': description: Webset updated content: application/json: schema: $ref: '#/components/schemas/Webset' headers: X-Request-Id: schema: type: string description: Unique identifier for the request. example: req_N6SsgoiaOQOPqsYKKiw5 required: true '404': description: Webset not found headers: X-Request-Id: schema: type: string description: Unique identifier for the request. example: req_N6SsgoiaOQOPqsYKKiw5 required: true summary: Update a Webset tags: - Websets security: - apiKey: [] - bearer: [] x-codeSamples: - lang: javascript label: JavaScript source: "// npm install exa-js\nimport Exa from \"exa-js\";\nconst exa = new Exa(\"YOUR_EXA_API_KEY\");\n\nconst webset = await exa.websets.update(\"webset_id\", {\n name: \"Updated Webset Name\",\n description: \"Updated description\",\n});\n\nconsole.log(`Updated webset: ${webset.id}`);" - lang: python label: Python source: "# pip install exa-py\nfrom exa_py import Exa\n\nexa = Exa(\"YOUR_EXA_API_KEY\")\n\nwebset = exa.websets.update(\n \"webset_id\",\n params={\"name\": \"Updated Webset Name\", \"description\": \"Updated description\"},\n)\n\nprint(f\"Updated webset: {webset.id}\")" delete: description: 'Deletes a Webset. Once deleted, the Webset and all its Items will no longer be available.' operationId: websets-delete parameters: - name: id required: true in: path description: The id or externalId of the Webset schema: type: string responses: '200': description: Webset deleted content: application/json: schema: $ref: '#/components/schemas/Webset' headers: X-Request-Id: schema: type: string description: Unique identifier for the request. example: req_N6SsgoiaOQOPqsYKKiw5 required: true '404': description: Webset not found headers: X-Request-Id: schema: type: string description: Unique identifier for the request. example: req_N6SsgoiaOQOPqsYKKiw5 required: true summary: Delete a Webset tags: - Websets security: - apiKey: [] - bearer: [] x-codeSamples: - lang: javascript label: JavaScript source: '// npm install exa-js import Exa from "exa-js"; const exa = new Exa("YOUR_EXA_API_KEY"); await exa.websets.delete("webset_id"); console.log("Webset deleted successfully");' - lang: python label: Python source: '# pip install exa-py from exa_py import Exa exa = Exa("YOUR_EXA_API_KEY") exa.websets.delete("webset_id") print("Webset deleted successfully")' /v0/websets/{id}/cancel: servers: - url: https://api.exa.ai/websets post: description: 'Cancels all operations being performed on a Webset. Any enrichment or search will be stopped and the Webset will be marked as `idle`.' operationId: websets-cancel parameters: - name: id required: true in: path description: The id or externalId of the Webset schema: type: string responses: '200': description: Webset canceled content: application/json: schema: $ref: '#/components/schemas/Webset' headers: X-Request-Id: schema: type: string description: Unique identifier for the request. example: req_N6SsgoiaOQOPqsYKKiw5 required: true summary: Cancel a running Webset tags: - Websets security: - apiKey: [] - bearer: [] x-codeSamples: - lang: javascript label: JavaScript source: '// npm install exa-js import Exa from "exa-js"; const exa = new Exa("YOUR_EXA_API_KEY"); const webset = await exa.websets.cancel("webset_id"); console.log(`Cancelled webset: ${webset.id}`);' - lang: python label: Python source: '# pip install exa-py from exa_py import Exa exa = Exa("YOUR_EXA_API_KEY") webset = exa.websets.cancel("webset_id") print(f"Cancelled webset: {webset.id}")' components: schemas: WebsetEnrichmentFormat: type: string enum: - text - date - number - options - email - phone - url WebsetItemArticleProperties: type: - object properties: type: type: string const: article default: article url: type: - string format: uri description: The URL of the article description: type: - string description: Short description of the relevance of the article content: type: string description: The text content for the article nullable: true article: type: - object properties: title: type: string description: The title of the article nullable: true author: type: string description: The author(s) of the article nullable: true publishedAt: type: string description: The date and time the article was published nullable: true required: - title - author - publishedAt title: WebsetItemArticlePropertiesFields required: - type - url - description - content - article CustomEntity: type: - object properties: type: type: string const: custom default: custom description: type: - string minLength: 2 maxLength: 200 required: - type - description title: Custom WebsetSearchCanceledReason: type: string enum: - webset_deleted - webset_canceled - out_of_credits Monitor: type: - object properties: id: type: - string description: The unique identifier for the Monitor object: type: - string enum: - monitor description: The type of object status: type: - string enum: - enabled - disabled description: The status of the Monitor websetId: type: - string description: The id of the Webset the Monitor belongs to cadence: type: - object properties: cron: description: Cron expression for monitor cadence (must be a valid Unix cron with 5 fields). The schedule must trigger at most once per day. type: - string timezone: description: IANA timezone (e.g., "America/New_York") default: Etc/UTC type: - string required: - cron description: How often the monitor will run behavior: type: - object properties: type: type: string const: search default: search config: type: - object properties: query: type: - string minLength: 2 maxLength: 10000 description: The query to search for. By default, the query from the last search is used. criteria: type: - array items: type: - object properties: description: type: - string minLength: 2 maxLength: 1000 required: - description maxItems: 5 description: The criteria to search for. By default, the criteria from the last search is used. entity: $ref: '#/components/schemas/Entity' title: Entity description: The entity to search for. By default, the entity from the last search/import is used. count: type: - number exclusiveMinimum: 0 description: The maximum number of results to find behavior: default: append type: - string enum: - override - append description: The behaviour of the Search when it is added to a Webset. required: - count description: '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.' required: - type - config description: Behavior to perform when monitor runs lastRun: type: object $ref: '#/components/schemas/MonitorRun' title: MonitorRun description: The last run of the monitor nullable: true nextRunAt: type: string format: date-time description: Date and time when the next run will occur in nullable: true metadata: description: Set of key-value pairs you want to associate with this object. type: - object additionalProperties: type: - string maxLength: 1000 createdAt: type: - string format: date-time description: When the monitor was created updatedAt: type: - string format: date-time description: When the monitor was last updated required: - id - object - status - websetId - cadence - behavior - lastRun - nextRunAt - metadata - createdAt - updatedAt PersonEntity: type: - object properties: type: type: string const: person default: person required: - type title: Person WebsetSearch: type: - object properties: id: type: - string description: The unique identifier for the search object: type: string const: webset_search default: webset_search status: type: - string enum: - created - pending - running - completed - canceled description: The status of the search title: WebsetSearchStatus websetId: type: - string description: The unique identifier for the Webset this search belongs to query: description: The query used to create the search. type: - string minLength: 1 maxLength: 5000 entity: $ref: '#/components/schemas/Entity' description: '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.' nullable: true criteria: type: - array items: type: - object properties: description: description: The description of the criterion type: - string minLength: 1 maxLength: 1000 successRate: type: - number minimum: 0 maximum: 100 description: Value between 0 and 100 representing the percentage of results that meet the criterion. required: - description - successRate description: The criteria the search will use to evaluate the results. If not provided, we will automatically generate them for you. count: type: - number minimum: 1 description: 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: type: integer minimum: 1 description: The soft cap requested for matching people from the same current employer company, or null when no cap was requested. nullable: true behavior: default: override type: - string $ref: '#/components/schemas/WebsetSearchBehavior' description: '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.' exclude: type: - array items: type: - object properties: source: type: - string enum: - import - webset id: type: - string required: - source - id description: Sources (existing imports or websets) used to omit certain results to be found during the search. scope: type: - array items: type: - object properties: source: type: - string enum: - import - webset id: type: - string relationship: type: - object properties: definition: type: - string description: What the relationship of the entities you hope to find is relative to the entities contained in the provided source. limit: type: - number minimum: 1 maximum: 10 required: - definition - limit required: - source - id description: '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: type: - object properties: found: type: - number description: The number of results found so far analyzed: type: - number description: The number of results analyzed so far completion: type: - number minimum: 0 maximum: 100 description: The completion percentage of the search timeLeft: type: number description: The estimated time remaining in seconds, null if unknown nullable: true required: - found - analyzed - completion - timeLeft description: The progress of the search recall: type: object properties: expected: type: - object properties: total: type: - number description: The estimated total number of potential matches confidence: type: - string enum: - high - medium - low description: The confidence in the estimate bounds: type: - object properties: min: type: - number description: The minimum estimated total number of potential matches max: type: - number description: The maximum estimated total number of potential matches required: - min - max required: - total - confidence - bounds reasoning: type: - string description: The reasoning for the estimate required: - expected - reasoning description: Recall metrics for the search, null if not yet computed or requested. nullable: true metadata: default: {} description: Set of key-value pairs you want to associate with this object. type: - object additionalProperties: type: - string maxLength: 1000 canceledAt: type: string format: date-time description: The date and time the search was canceled nullable: true canceledReason: type: string $ref: '#/components/schemas/WebsetSearchCanceledReason' description: The reason the search was canceled nullable: true createdAt: type: - string format: date-time description: The date and time the search was created updatedAt: type: - string format: date-time description: The date and time the search was updated required: - id - object - websetId - status - query - entity - criteria - count - maxPeoplePerCompany - exclude - scope - progress - recall - canceledAt - canceledReason - createdAt - updatedAt WebsetItemCustomProperties: type: - object properties: type: type: string const: custom default: custom url: type: - string format: uri description: The URL of the Item description: type: - string description: Short description of the Item content: type: string description: The text content of the Item nullable: true custom: type: - object properties: title: type: string description: The title of the website nullable: true author: type: string description: The author(s) of the website nullable: true publishedAt: type: string description: The date and time the website was published nullable: true required: - title - author - publishedAt title: WebsetItemCustomPropertiesFields required: - type - url - description - content - custom Import: type: - object properties: id: type: - string description: The unique identifier for the Import object: type: - string enum: - import description: The type of object status: type: - string enum: - pending - processing - completed - failed - canceled description: The status of the Import format: type: - string enum: - csv - webset description: The format of the import. entity: $ref: '#/components/schemas/Entity' description: The type of entity the import contains. nullable: true title: type: - string description: The title of the import count: type: - number description: The number of entities in the import metadata: description: Set of key-value pairs you want to associate with this object. type: - object additionalProperties: type: - string maxLength: 1000 failedReason: type: string enum: - invalid_format - invalid_file_content - missing_identifier description: The reason the import failed nullable: true failedAt: type: string format: date-time description: When the import failed nullable: true failedMessage: type: string description: A human readable message of the import failure nullable: true createdAt: type: - string format: date-time description: When the import was created updatedAt: type: - string format: date-time description: When the import was last updated required: - id - object - status - format - entity - title - count - metadata - failedReason - failedAt - failedMessage - createdAt - updatedAt CreateEnrichmentParameters: type: - object properties: description: type: - string minLength: 1 maxLength: 5000 description: Provide a description of the enrichment task you want to perform to each Webset Item. format: type: - string enum: - text - date - number - options - email - phone - url description: '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: type: - array items: type: - object properties: label: type: - string description: The label of the option required: - label minItems: 1 maxItems: 150 description: When the format is options, the different options for the enrichment agent to choose from. metadata: description: Set of key-value pairs you want to associate with this object. type: - object additionalProperties: type: - string maxLength: 1000 required: - description Entity: oneOf: - type: - object $ref: '#/components/schemas/CompanyEntity' - type: - object $ref: '#/components/schemas/PersonEntity' - type: - object $ref: '#/components/schemas/ArticleEntity' - type: - object $ref: '#/components/schemas/ResearchPaperEntity' - type: - object $ref: '#/components/schemas/CustomEntity' ArticleEntity: type: - object properties: type: type: string const: article default: article required: - type title: Article CompanyEntity: type: - object properties: type: type: string const: company default: company required: - type title: Company WebsetItemEvaluation: type: - object properties: criterion: type: - string description: The description of the criterion reasoning: type: - string description: The reasoning for the result of the evaluation satisfied: type: - string enum: - 'yes' - 'no' - unclear description: The satisfaction of the criterion references: default: [] type: - array items: type: - object properties: title: type: string description: The title of the reference nullable: true snippet: type: string description: The relevant snippet of the reference content nullable: true url: type: - string format: uri description: The URL of the reference required: - title - snippet - url description: The references used to generate the result. required: - criterion - reasoning - satisfied MonitorRun: type: - object properties: id: type: - string description: The unique identifier for the Monitor Run object: type: - string enum: - monitor_run description: The type of object status: type: - string enum: - created - running - completed - canceled - failed description: The status of the Monitor Run monitorId: type: - string description: The monitor that the run is associated with type: type: - string enum: - search - refresh description: The type of the Monitor Run completedAt: type: string format: date-time description: When the run completed nullable: true failedAt: type: string format: date-time description: When the run failed nullable: true failedReason: type: string description: The reason the run failed nullable: true canceledAt: type: string format: date-time description: When the run was canceled nullable: true createdAt: type: - string format: date-time description: When the run was created updatedAt: type: - string format: date-time description: When the run was last updated required: - id - object - monitorId - status - type - completedAt - failedAt - failedReason - canceledAt - createdAt - updatedAt WebsetItemResearchPaperProperties: type: - object properties: type: type: string const: research_paper default: research_paper url: type: - string format: uri description: The URL of the research paper description: type: - string description: Short description of the relevance of the research paper content: type: string description: The text content of the research paper nullable: true researchPaper: type: - object properties: title: type: string description: The title of the research paper nullable: true author: type: string description: The author(s) of the research paper nullable: true publishedAt: type: string description: The date and time the research paper was published nullable: true required: - title - author - publishedAt title: WebsetItemResearchPaperPropertiesFields required: - type - url - description - content - researchPaper ResearchPaperEntity: type: - object properties: type: type: string const: research_paper default: research_paper required: - type title: Research Paper UpdateWebsetRequest: type: - object properties: metadata: description: Set of key-value pairs you want to associate with this object. type: object additionalProperties: type: - string maxLength: 1000 nullable: true title: type: - string minLength: 1 description: Optional name that appears anywhere the Webset is displayed. examples: - Leading climate tech startups WebsetEnrichment: type: - object properties: id: type: - string description: The unique identifier for the enrichment object: type: string const: webset_enrichment default: webset_enrichment status: type: - string enum: - pending - canceled - completed description: The status of the enrichment title: WebsetEnrichmentStatus websetId: type: - string description: The unique identifier for the Webset this enrichment belongs to. title: type: string description: 'The title of the enrichment. This will be automatically generated based on the description and format.' nullable: true description: type: - string description: The description of the enrichment task provided during the creation of the enrichment. format: type: string $ref: '#/components/schemas/WebsetEnrichmentFormat' description: The format of the enrichment response. nullable: true options: type: array items: type: - object properties: label: type: - string description: The label of the option required: - label description: When the format is options, the different options for the enrichment agent to choose from. title: WebsetEnrichmentOptions nullable: true instructions: type: string description: 'The instructions for the enrichment Agent. This will be automatically generated based on the description and format.' nullable: true metadata: default: {} description: The metadata of the enrichment type: - object additionalProperties: type: - string maxLength: 1000 createdAt: type: - string format: date-time description: The date and time the enrichment was created updatedAt: type: - string format: date-time description: The date and time the enrichment was updated required: - id - object - status - websetId - title - description - format - options - instructions - createdAt - updatedAt Webset: type: - object properties: id: type: - string description: The unique identifier for the webset object: type: string const: webset default: webset status: type: - string enum: - idle - pending - running - paused description: The status of the webset title: WebsetStatus externalId: type: string description: The external identifier for the webset nullable: true title: type: string description: The title of the webset nullable: true searches: type: - array items: type: - object $ref: '#/components/schemas/WebsetSearch' description: The searches that have been performed on the webset. imports: type: - array items: type: - object $ref: '#/components/schemas/Import' description: Imports that have been performed on the webset. enrichments: type: - array items: type: - object $ref: '#/components/schemas/WebsetEnrichment' description: The Enrichments to apply to the Webset Items. monitors: type: - array items: type: - object $ref: '#/components/schemas/Monitor' description: The Monitors for the Webset. excludes: type: - array items: type: - object properties: source: type: - string enum: - import - webset id: type: - string required: - source - id description: 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. metadata: default: {} description: Set of key-value pairs you want to associate with this object. type: - object additionalProperties: type: - string maxLength: 1000 dashboardUrl: type: - string format: uri description: The URL to view the webset in the Exa dashboard createdAt: type: - string format: date-time description: The date and time the webset was created updatedAt: type: - string format: date-time description: The date and time the webset was updated required: - id - object - status - externalId - title - searches - imports - enrichments - monitors - dashboardUrl - createdAt - updatedAt WebsetItemPersonProperties: type: - object properties: type: type: string const: person default: person url: type: - string format: uri description: The URL of the person profile description: type: - string description: Short description of the relevance of the person person: type: - object properties: name: type: - string description: The name of the person location: type: string description: The location of the person nullable: true position: type: string description: The current work position of the person nullable: true company: type: object properties: name: type: - string description: The name of the company location: type: string description: The location the person is working at the company nullable: true required: - name - location title: WebsetItemPersonCompanyPropertiesFields nullable: true pictureUrl: type: string format: uri description: The image URL of the person nullable: true required: - name - location - position - company - pictureUrl title: WebsetItemPersonPropertiesFields required: - type - url - description - person ListWebsetsResponse: type: - object properties: data: type: - array items: type: - object $ref: '#/components/schemas/Webset' description: The list of websets hasMore: type: - boolean description: Whether there are more results to paginate through nextCursor: type: string description: The cursor to paginate through the next set of results nullable: true required: - data - hasMore - nextCursor WebsetItemCompanyProperties: type: - object properties: type: type: string const: company default: company url: type: - string format: uri description: The URL of the company website description: type: - string description: Short description of the relevance of the company content: type: string description: The text content of the company website nullable: true company: type: - object properties: name: type: - string description: The name of the company location: type: string description: The main location of the company nullable: true employees: type: number description: The number of employees of the company nullable: true industry: type: string description: The industry of the company nullable: true about: type: string description: A short description of the company nullable: true logoUrl: type: string format: uri description: The logo URL of the company nullable: true foundedYear: type: number description: The year the company was founded nullable: true headquarters: type: object nullable: true description: The structured headquarters address of the company properties: address: type: string description: The street address of the headquarters nullable: true city: type: string description: The city of the headquarters nullable: true state: type: string description: The state or region of the headquarters nullable: true postalCode: type: string description: The postal code of the headquarters nullable: true country: type: string description: The country of the headquarters nullable: true countryCode: type: string description: The ISO country code of the headquarters nullable: true required: - address - city - state - postalCode - country - countryCode title: WebsetItemCompanyHeadquarters financials: type: object nullable: true description: Financial information about the company properties: revenueAnnual: type: number description: The annual revenue of the company (USD) nullable: true fundingTotal: type: number description: The total funding raised by the company (USD) nullable: true fundingLatestRound: type: object nullable: true description: The latest funding round properties: name: type: string description: The name of the funding round (e.g. Series A) nullable: true date: type: string description: The date of the funding round nullable: true amount: type: number description: The amount raised in the funding round (USD) nullable: true required: - name - date - amount title: WebsetItemCompanyFundingRound required: - revenueAnnual - fundingTotal - fundingLatestRound title: WebsetItemCompanyFinancials webTraffic: type: object nullable: true description: Web traffic metrics for the company properties: visitsMonthly: type: number description: The estimated monthly website visits nullable: true uniqueVisitors: type: number description: The estimated monthly unique visitors nullable: true required: - visitsMonthly - uniqueVisitors title: WebsetItemCompanyWebTraffic required: - name - location - employees - industry - about - logoUrl - foundedYear - headquarters - financials - webTraffic title: WebsetItemCompanyPropertiesFields required: - type - url - description - content - company CreateWebsetParameters: type: - object properties: title: type: string minLength: 1 description: Optional name that appears anywhere the Webset is displayed. Leave empty to have Exa generate one automatically. examples: - Leading climate tech startups nullable: true search: type: - object properties: query: type: - string minLength: 1 maxLength: 5000 description: '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.' examples: - Marketing agencies based in the US, that focus on consumer products. - AI startups in Europe that raised Series A funding in 2024 - SaaS companies with 50-200 employees in the fintech space count: default: 10 type: - number minimum: 1 description: '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: $ref: '#/components/schemas/Entity' description: '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. Only use this when you need more fine control.' criteria: type: - array items: type: - object $ref: '#/components/schemas/CreateCriterionParameters' title: CreateCriterionParameters minItems: 1 maxItems: 5 description: '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.' maxPeoplePerCompany: type: - integer minimum: 1 description: 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: type: - boolean description: '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: type: - array items: type: - object properties: source: type: - string enum: - import - webset id: type: - string minLength: 1 description: The ID of the source to exclude. required: - source - id description: 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: type: - array items: type: - object properties: source: type: - string enum: - import - webset id: type: - string minLength: 1 description: The ID of the source to search. relationship: type: - object properties: definition: type: - string description: What the relationship of the entities you hope to find is relative to the entities contained in the provided source. limit: type: - number minimum: 1 maximum: 10 required: - definition - limit required: - source - id description: 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. required: - query description: Create initial search for the Webset. import: type: - array items: type: - object properties: source: type: - string enum: - import - webset id: type: - string minLength: 1 description: The ID of the source to search. required: - source - id description: Import data from existing Websets and Imports into this Webset. enrichments: type: - array items: type: - object $ref: '#/components/schemas/CreateEnrichmentParameters' title: CreateEnrichmentParameters description: '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.' exclude: type: - array items: type: - object properties: source: type: - string enum: - import - webset id: type: - string minLength: 1 description: The ID of the source to exclude. required: - source - id description: 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. externalId: type: - string maxLength: 300 description: 'The external identifier for the webset. You can use this to reference the Webset by your own internal identifiers.' metadata: description: Set of key-value pairs you want to associate with this object. type: - object additionalProperties: type: - string maxLength: 1000 examples: - search: query: Marketing agencies based in the US, that focus on consumer products. count: 10 GetWebsetResponse: allOf: - type: - object $ref: '#/components/schemas/Webset' - type: - object properties: items: type: - array items: type: - object $ref: '#/components/schemas/WebsetItem' description: When expand query parameter contains `items`, this will contain the items in the webset WebsetItem: type: - object properties: id: type: - string description: The unique identifier for the Webset Item object: type: string const: webset_item default: webset_item source: type: - string enum: - search - import description: The source of the Item sourceId: type: - string description: The unique identifier for the source sourceEntityId: type: - string description: The original identifier used to resolve this item (e.g., email, name, or URL). Only relevant when the source is import. websetId: type: - string description: The unique identifier for the Webset this Item belongs to. properties: oneOf: - type: - object $ref: '#/components/schemas/WebsetItemPersonProperties' title: Person - type: - object $ref: '#/components/schemas/WebsetItemCompanyProperties' title: Company - type: - object $ref: '#/components/schemas/WebsetItemArticleProperties' title: Article - type: - object $ref: '#/components/schemas/WebsetItemResearchPaperProperties' title: Research Paper - type: - object $ref: '#/components/schemas/WebsetItemCustomProperties' title: Custom description: The properties of the Item evaluations: type: - array items: type: - object $ref: '#/components/schemas/WebsetItemEvaluation' description: The criteria evaluations of the item enrichments: type: array items: type: - object $ref: '#/components/schemas/EnrichmentResult' description: The enrichments results of the Webset item nullable: true createdAt: type: - string format: date-time description: The date and time the item was created updatedAt: type: - string format: date-time description: The date and time the item was last updated required: - id - object - source - sourceId - websetId - properties - evaluations - enrichments - createdAt - updatedAt EnrichmentResult: type: - object properties: object: type: string const: enrichment_result default: enrichment_result status: type: - string enum: - pending - completed - canceled description: The status of the enrichment result. format: type: - string $ref: '#/components/schemas/WebsetEnrichmentFormat' result: type: array items: type: - string description: The result of the enrichment. nullable: true reasoning: type: string description: The reasoning for the result when an Agent is used. nullable: true references: type: - array items: type: - object properties: title: type: string description: The title of the reference nullable: true snippet: type: string description: The relevant snippet of the reference content nullable: true url: type: - string format: uri description: The URL of the reference required: - title - snippet - url description: The references used to generate the result. enrichmentId: type: - string description: The id of the Enrichment that generated the result required: - object - status - format - result - reasoning - references - enrichmentId CreateCriterionParameters: type: - object properties: description: type: - string minLength: 1 maxLength: 1000 description: The description of the criterion required: - description WebsetSearchBehavior: type: string enum: - override - append securitySchemes: apiKey: type: apiKey name: x-api-key in: header description: 'Pass your Exa API key in the x-api-key header. You can also authenticate with Authorization: Bearer .' bearer: type: http scheme: bearer description: 'Pass your Exa API key in the x-api-key header. You can also authenticate with Authorization: Bearer .'