Exa Websets API

openapi: 3.2.0
info:
  title: Exa Websets API
  version: 2.0.0
  description: Exa Websets 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:
    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
    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
    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
    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
    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
    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
    CustomEntity:
      type:
      - object
      properties:
        type:
          type: string
          const: custom
          default: custom
        description:
          type:
          - string
          minLength: 2
          maxLength: 200
      required:
      - type
      - description
      title: Custom
    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
    CreateCriterionParameters:
      type:
      - object
      properties:
        description:
          type:
          - string
          minLength: 1
          maxLength: 1000
          description: The description of the criterion
      required:
      - description
    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
                - li

# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/exa-ai/refs/heads/main/openapi/exa-ai-websets-api-openapi.yml