Exa Websets API

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 

# --- 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