openapi: 3.1.0
info:
  title: Exa Agent Searches 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: Searches
paths:
  /v0/websets/{webset}/searches:
    servers:
    - url: https://api.exa.ai/websets
    post:
      description: 'Creates a new Search for the Webset.


        The default behavior is to reuse the previous Search results and evaluate them against the new criteria.'
      operationId: websets-searches-create
      parameters:
      - name: webset
        required: true
        in: path
        description: The id of the Webset
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebsetSearchParameters'
      responses:
        '200':
          description: Webset Search created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebsetSearch'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Unique identifier for the request.
              example: req_N6SsgoiaOQOPqsYKKiw5
              required: true
      summary: Create a Search
      tags:
      - Searches
      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 search = await exa.websets.searches.create(\"webset_id\", {\n  query: \"additional companies to add\",\n  count: 5,\n});\n\nconsole.log(`Created search: ${search.id}`);"
      - lang: python
        label: Python
        source: "# pip install exa-py\nfrom exa_py import Exa\n\nexa = Exa(\"YOUR_EXA_API_KEY\")\n\nsearch = exa.websets.searches.create(\n    \"webset_id\", params={\"query\": \"additional companies to add\", \"count\": 5}\n)\n\nprint(f\"Created search: {search.id}\")"
  /v0/websets/{webset}/searches/{id}:
    servers:
    - url: https://api.exa.ai/websets
    get:
      description: Gets a Search by id
      operationId: websets-searches-get
      parameters:
      - name: webset
        required: true
        in: path
        description: The id of the Webset
        schema:
          type: string
      - name: id
        required: true
        in: path
        description: The id of the Search
        schema:
          type: string
      responses:
        '200':
          description: Search retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebsetSearch'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Unique identifier for the request.
              example: req_N6SsgoiaOQOPqsYKKiw5
              required: true
      summary: Get a Search
      tags:
      - Searches
      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 search = await exa.websets.searches.get("webset_id", "search_id");


          console.log(`Search: ${search.id} - ${search.status}`);'
      - lang: python
        label: Python
        source: '# pip install exa-py

          from exa_py import Exa


          exa = Exa("YOUR_EXA_API_KEY")


          search = exa.websets.searches.get("webset_id", "search_id")


          print(f"Search: {search.id} - {search.status}")'
  /v0/websets/{webset}/searches/{id}/cancel:
    servers:
    - url: https://api.exa.ai/websets
    post:
      description: 'Cancels a currently running Search.


        You can cancel all searches at once by using the `websets/:webset/cancel` endpoint.'
      operationId: websets-searches-cancel
      parameters:
      - name: webset
        required: true
        in: path
        description: The id of the Webset
        schema:
          type: string
      - name: id
        required: true
        in: path
        description: The id of the Search
        schema:
          type: string
      responses:
        '200':
          description: Search canceled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebsetSearch'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Unique identifier for the request.
              example: req_N6SsgoiaOQOPqsYKKiw5
              required: true
      summary: Cancel a running Search
      tags:
      - Searches
      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 search = await exa.websets.searches.cancel("webset_id", "search_id");


          console.log(`Cancelled search: ${search.id}`);'
      - lang: python
        label: Python
        source: '# pip install exa-py

          from exa_py import Exa


          exa = Exa("YOUR_EXA_API_KEY")


          search = exa.websets.searches.cancel("webset_id", "search_id")


          print(f"Cancelled search: {search.id}")'
components:
  schemas:
    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'
    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
    PersonEntity:
      type:
      - object
      properties:
        type:
          type: string
          const: person
          default: person
      required:
      - type
      title: Person
    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
    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
    CreateWebsetSearchParameters:
      type:
      - object
      properties:
        count:
          type:
          - number
          minimum: 1
          description: 'Number of Items the Search will attempt to find.


            The actual number of Items found may be less than this number depending on the query complexity.'
        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. Get brands worked with and city
          - AI startups in Europe that raised Series A funding in 2024
          - SaaS companies with 50-200 employees in the fintech space
        entity:
          $ref: '#/components/schemas/Entity'
          description: 'Entity the search 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.
        exclude:
          type:
          - array
          items:
            type:
            - object
            properties:
              source:
                type:
                - string
                enum:
                - import
                - webset
              id:
                description: The ID of the source to exclude.
                type:
                - string
                minLength: 1
            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). Any results found within these sources matching the search criteria will be included in the Webset.
        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.'
        behavior:
          default: override
          type:
          - string
          description: 'How this search interacts with existing items in the Webset:


            - **override**: Replace existing items and evaluate all items against new criteria

            - **append**: Add new items to existing ones, keeping items that match the new criteria'
          $ref: '#/components/schemas/WebsetSearchBehavior'
        metadata:
          description: Set of key-value pairs you want to associate with this object.
          type:
          - object
          additionalProperties:
            type:
            - string
            maxLength: 1000
      required:
      - count
      - query
    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
    ResearchPaperEntity:
      type:
      - object
      properties:
        type:
          type: string
          const: research_paper
          default: research_paper
      required:
      - type
      title: Research Paper
  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 <key>.'
    bearer:
      type: http
      scheme: bearer
      description: 'Pass your Exa API key in the x-api-key header. You can also authenticate with Authorization: Bearer <key>.'