Exa Events API

openapi: 3.1.0
info:
  title: Exa Agent Events 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: Events
paths:
  /v0/events:
    servers:
    - url: https://api.exa.ai/websets
    get:
      description: 'List all events that have occurred in the system.


        You can paginate through the results using the `cursor` parameter.'
      operationId: events-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 results to return
        schema:
          minimum: 1
          maximum: 200
          default: 25
          type: number
      - name: types
        required: false
        in: query
        description: The types of events to filter by
        schema:
          type: array
          items:
            type: string
            enum:
            - webset.created
            - webset.deleted
            - webset.paused
            - webset.idle
            - webset.search.created
            - webset.search.canceled
            - webset.search.completed
            - webset.search.updated
            - import.created
            - import.completed
            - webset.item.created
            - webset.item.enriched
            - monitor.created
            - monitor.updated
            - monitor.deleted
            - monitor.run.created
            - monitor.run.completed
            - webset.export.created
            - webset.export.completed
      - name: createdBefore
        required: false
        in: query
        description: Filter events created before or at this timestamp (inclusive). Must be a valid ISO 8601 datetime string. All times are in UTC.
        schema:
          format: date-time
          type: string
      - name: createdAfter
        required: false
        in: query
        description: Filter events created after or at this timestamp (inclusive). Must be a valid ISO 8601 datetime string. All times are in UTC.
        schema:
          format: date-time
          type: string
      responses:
        '200':
          description: List of events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEventsResponse'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Unique identifier for the request.
              example: req_N6SsgoiaOQOPqsYKKiw5
              required: true
      summary: List all Events
      tags:
      - Events
      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 events = await exa.websets.events.list({\n  limit: 20,\n});\n\nconsole.log(`Found ${events.data.length} events`);\nevents.data.forEach((event) => {\n  console.log(`- ${event.id}: ${event.type} at ${event.createdAt}`);\n});"
      - lang: python
        label: Python
        source: "# pip install exa-py\nfrom exa_py import Exa\n\nexa = Exa(\"YOUR_EXA_API_KEY\")\n\nevents = exa.websets.events.list(limit=20)\n\nprint(f\"Found {len(events.data)} events\")\nfor event in events.data:\n    print(f\"- {event.id}: {event.type}\")"
  /v0/events/{id}:
    servers:
    - url: https://api.exa.ai/websets
    get:
      description: 'Get a single Event by id.


        You can subscribe to Events by creating a Webhook.'
      operationId: events-get
      parameters:
      - name: id
        required: true
        in: path
        description: The id of the event
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Unique identifier for the request.
              example: req_N6SsgoiaOQOPqsYKKiw5
              required: true
        '404':
          description: Event not found
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Unique identifier for the request.
              example: req_N6SsgoiaOQOPqsYKKiw5
              required: true
      summary: Get an Event
      tags:
      - Events
      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 event = await exa.websets.events.get("event_id");


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

          from exa_py import Exa


          exa = Exa("YOUR_EXA_API_KEY")


          event = exa.websets.events.get("event_id")


          print(f"Event: {event.id} - {event.type}")'
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
    WebsetSearchCanceledReason:
      type: string
      enum:
      - webset_deleted
      - webset_canceled
      - out_of_credits
    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
    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
    ListEventsResponse:
      type:
      - object
      properties:
        data:
          type:
          - array
          items:
            discriminator:
              propertyName: type
            $ref: '#/components/schemas/Event'
          description: The list of events
        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
    Event:
      discriminator:
        propertyName: type
      oneOf:
      - type:
        - object
        properties:
          id:
            description: The unique identifier for the event
            type:
            - string
          object:
            type: string
            const: event
            default: event
          type:
            type: string
            const: webset.created
            default: webset.created
          data:
            type:
            - object
            $ref: '#/components/schemas/Webset'
          createdAt:
            type:
            - string
            format: date-time
            description: The date and time the event was created
        required:
        - id
        - object
        - type
        - data
        - createdAt
        title: WebsetCreatedEvent
      - type:
        - object
        properties:
          id:
            description: The unique identifier for the event
            type:
            - string
          object:
            type: string
            const: event
            default: event
          type:
            type: string
            const: webset.deleted
            default: webset.deleted
          data:
            type:
            - object
            $ref: '#/components/schemas/Webset'
          createdAt:
            type:
            - string
            format: date-time
            description: The date and time the event was created
        required:
        - id
        - object
        - type
        - data
        - createdAt
        title: WebsetDeletedEvent
      - type:
        - object
        properties:
          id:
            description: The unique identifier for the event
            type:
            - string
          object:
            type: string
            const: event
            default: event
          type:
            type: string
            const: webset.idle
            default: webset.idle
          data:
            type:
            - object
            $ref: '#/components/schemas/Webset'
          createdAt:
            type:
            - string
            format: date-time
            description: The date and time the event was created
        required:
        - id
        - object
        - type
        - data
        - createdAt
        title: WebsetIdleEvent
      - type:
        - object
        properties:
          id:
            description: The unique identifier for the event
            type:
            - string
          object:
            type: string
            const: event
            default: event
          type:
            type: string
            const: webset.paused
            default: webset.paused
          data:
            type:
            - object
            $ref: '#/components/schemas/Webset'
          createdAt:
            type:
            - string
            format: date-time
            description: The date and time the event was created
        required:
        - id
        - object
        - type
        - data
        - createdAt
        title: WebsetPausedEvent
      - type:
        - object
        properties:
          id:
            description: The unique identifier for the event
            type:
            - string
          object:
            type: string
            const: event
            default: event
          type:
            type: string
            const: webset.item.created
            default: webset.item.created
          data:
            type:
            - object
            $ref: '#/components/schemas/WebsetItem'
          createdAt:
            type:
            - string
            format: date-time
            description: The date and time the event was created
        required:
        - id
        - object
        - type
        - data
        - createdAt
        title: WebsetItemCreatedEvent
      - type:
        - object
        properties:
          id:
            description: The unique identifier for the event
            type:
            - string
          object:
            type: string
            const: event
            default: event
          type:
            type: string
            const: webset.item.enriched
            default: webset.item.enriched
          data:
            type:
            - object
            $ref: '#/components/schemas/WebsetItem'
          createdAt:
            type:
            - string
            format: date-time
            description: The date and time the event was created
        required:
        - id
        - object
        - type
        - data
        - createdAt
        title: WebsetItemEnrichedEvent
      - type:
        - object
        properties:
          id:
            description: The unique identifier for the event
            type:
            - string
          object:
            type: string
            const: event
            default: event
          type:
            type: string
            const: webset.search.created
            default: webset.search.created
          data:
            type:
            - object
            $ref: '#/components/schemas/WebsetSearch'
          createdAt:
            type:
            - string
            format: date-time
            description: The date and time the event was created
        required:
        - id
        - object
        - type
        - data
        - createdAt
        title: WebsetSearchCreatedEvent
      - type:
        - object
        properties:
          id:
            description: The unique identifier for the event
            type:
            - string
          object:
            type: string
            const: event
            default: event
          type:
            type: string
            const: webset.search.updated
            default: webset.search.updated
          data:
            type:
            - object
            $ref: '#/components/schemas/WebsetSearch'
          createdAt:
            type:
            - string
            format: date-time
            description: The date and time the event was created
        required:
        - id
        - object
        - type
        - data
        - createdAt
        title: WebsetSearchUpdatedEvent
      - type:
        - object
        properties:
          id:
            description: The unique identifier for the event
            type:
            - string
          object:
            type: string
            const: event
            default: event
          type:
            type: string
            const: webset.search.canceled
            default: webset.search.canceled
          data:
            type:
            - object
            $ref: '#/components/schemas/WebsetSearch'
          createdAt:
            type:
            - string
            format: date-time
            description: The date and time the event was created
        required:
        - id
        - object
        - type
        - data
        - createdAt
        title: WebsetSearchCanceledEvent
      - type:
        - object
        properties:
          id:
            description: The unique identifier for the event
            type:
            - string
          object:
            type: string
            const: event
            default: event
          type:
            type: string
            const: webset.search.completed
            default: webset.search.completed
          data:
            type:
            - object
            $ref: '#/components/schemas/WebsetSearch'
          createdAt:
            type:
            - string
            format: date-time
            description: The date and time the event was created
        required:
        - id
        - object
        - type
        - data
        - createdAt
        title: WebsetSearchCompletedEvent
      - type:
        - object
        properties:
          id:
            description: The unique identifier for the event
            type:
            - string
          object:
            type: string
            const: event
            default: event
          type:
            type: string
            const: import.created
            default: import.created
          data:
            type:
            - object
            $ref: '#/components/schemas/Import'
          createdAt:
            type:
            - string
            format: date-time
            description: The date and time the event was created
        required:
        - id
        - object
        - type
        - data
        - createdAt
        title: ImportCreatedEvent
      - type:
        - object
        properties:
          id:
            description: The unique identifier for the event
            type:
     

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