Exa Events API

openapi: 3.2.0
info:
  title: Exa Websets Events 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: 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:
    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
    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
    CustomEntity:
      type:
      - object
      properties:
        type:
          type: string
          const: custom
          default: custom
        description:
          type:
          - string
          minLength: 2
          maxLength: 200
      required:
      - type
      - description
      title: Custom
    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
    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
    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
    WebsetSearchCanceledReason:
      type: string
      enum:
      - webset_deleted
      - webset_canceled
      - out_of_credits
    WebsetItemResearchPaperProperties:
      type:
      - object
      properties:
        type:
          type: string
          const: research_paper
          default: research_paper
        url:
          type:
          - string
          format: uri
          description: The URL of the research paper
        description:
          type:
          - string
          description: Short description of the relevance of the research paper
        content:
          type: string
          description: The text content of the research paper
          nullable: true
        researchPaper:
          type:
          - object
          properties:
            title:
              type: string
              description: The title of the research paper
              nullable: true
            author:
              type: string
              description: The author(s) of the research paper
              nullable: true
            publishedAt:
              type: string
              description: The date and time the research paper was published
              nullable: true
          required:
          - title
          - author
          - publishedAt
          title: WebsetItemResearchPaperPropertiesFields
      required:
      - type
      - url
      - description
      - content
      - researchPaper
    WebsetSearchBehavior:
      type: string
      enum:
      - override
      - append
    EnrichmentResult:
      type:
      - object
      properties:
        object:
          type: string
          const: enrichment_result
          default: enrichment_result
        status:
          type:
          - string
          enum:
          - pending
          - completed
          - canceled
          description: The status of the enrichment result.
        format:
          type:
          - string
          $ref: '#/components/schemas/WebsetEnrichmentFormat'
        result:
          type: array
          items:
            type:
            - string
          description: The result of the enrichment.
          nullable: true
        reasoning:
          type: string
          description: The reasoning for the result when an Agent is used.
          nullable: true
        references:
          type:
          - array
          items:
            type:
            - object
            properties:
              title:
                type: string
                description: The title of the reference
                nullable: true
              snippet:
                type: string
                description: The relevant snippet of the reference content
                nullable: true
              url:
                type:
                - string
                format: uri
                description: The URL of the reference
            required:
            - title
            - snippet
            - url
          description: The references used to generate the result.
        enrichmentId:
          type:
          - string
          description: The id of the Enrichment that generated the result
      required:
      - object
      - status
      - format
      - result
      - reasoning
      - references
      - enrichmentId
    CompanyEntity:
      type:
      - object
      properties:
        type:
          type: string
          const: company
          default: company
      required:
      - type
      title: Company
    ArticleEntity:
      type:
      - object
      properties:
        type:
          type: string
          const: article
          default: article
      required:
      - type
      title: Article
    ResearchPaperEntity:
      type:
      - object
      properties:
        type:
          type: string
          const: research_paper
          default: research_paper
      required:
      - type
      title: Research Paper
    WebsetEnrichmentFormat:
      type: string
      enum:
      - text
      - date
      - number
      - options
      - email
      - phone
      - url
    PersonEntity:
      type:
      - object
      properties:
        type:
          type: string
          const: person
          default: person
      required:
      - type
      title: Person
    WebsetItemPersonProperties:
      type:
      - object
      properties:
        type:
          type: string
          const: person
          default: person
        url:
          type:
          - string
          format: uri
          description: The URL of the person profile
        description:
          type:
          - string
          description: Short description of the relevance of the person
        person:
          type:
          - object
          properties:
            name:
              type:
              - string
              description: The name of the person
            location:
              type: string
              description: The location of the person
              nullable: true
            position:
              type: string
              description: The current work position of the person
              nullable: true
            company:
              type: object
              properties:
                name:
                  type:
                  - string
                  description: The name of the company
                location:
                  type: string
                  description: The location the person is working at the company
                  nullable: true
              requir

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