cURL

curl --request POST \
  --url https://api.exa.ai/websets/v0/monitors \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "websetId": "<string>",
  "cadence": {
    "cron": "<string>",
    "timezone": "Etc/UTC"
  },
  "behavior": {
    "type": "search",
    "config": {
      "count": 123,
      "query": "<string>",
      "criteria": [
        {
          "description": "<string>"
        }
      ],
      "entity": {
        "type": "company"
      },
      "behavior": "append"
    }
  },
  "metadata": {}
}
'

{
  "id": "<string>",
  "object": "monitor",
  "status": "enabled",
  "websetId": "<string>",
  "cadence": {
    "cron": "<string>",
    "timezone": "Etc/UTC"
  },
  "behavior": {
    "type": "search",
    "config": {
      "count": 123,
      "query": "<string>",
      "criteria": [
        {
          "description": "<string>"
        }
      ],
      "entity": {
        "type": "company"
      },
      "behavior": "append"
    }
  },
  "lastRun": {
    "id": "<string>",
    "object": "monitor_run",
    "status": "created",
    "monitorId": "<string>",
    "type": "search",
    "completedAt": "2023-11-07T05:31:56Z",
    "failedAt": "2023-11-07T05:31:56Z",
    "failedReason": "<string>",
    "canceledAt": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "nextRunAt": "2023-11-07T05:31:56Z",
  "metadata": {},
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

Monitors

Create a Monitor

Creates a new Monitor to continuously keep your Websets updated with fresh data.

Monitors automatically run on your defined schedule to ensure your Websets stay current without manual intervention:

Find new content: Execute search operations to discover fresh items matching your criteria
Update existing content: Run refresh operations to update items contents and enrichments
Automated scheduling: Configure cron expressions and timezone for precise scheduling control

POST

monitors

cURL

curl --request POST \
  --url https://api.exa.ai/websets/v0/monitors \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "websetId": "<string>",
  "cadence": {
    "cron": "<string>",
    "timezone": "Etc/UTC"
  },
  "behavior": {
    "type": "search",
    "config": {
      "count": 123,
      "query": "<string>",
      "criteria": [
        {
          "description": "<string>"
        }
      ],
      "entity": {
        "type": "company"
      },
      "behavior": "append"
    }
  },
  "metadata": {}
}
'

{
  "id": "<string>",
  "object": "monitor",
  "status": "enabled",
  "websetId": "<string>",
  "cadence": {
    "cron": "<string>",
    "timezone": "Etc/UTC"
  },
  "behavior": {
    "type": "search",
    "config": {
      "count": 123,
      "query": "<string>",
      "criteria": [
        {
          "description": "<string>"
        }
      ],
      "entity": {
        "type": "company"
      },
      "behavior": "append"
    }
  },
  "lastRun": {
    "id": "<string>",
    "object": "monitor_run",
    "status": "created",
    "monitorId": "<string>",
    "type": "search",
    "completedAt": "2023-11-07T05:31:56Z",
    "failedAt": "2023-11-07T05:31:56Z",
    "failedReason": "<string>",
    "canceledAt": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "nextRunAt": "2023-11-07T05:31:56Z",
  "metadata": {},
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

Authorizations

x-api-key

string

header

required

Your Exa API key

Body

application/json

websetId

string

required

The id of the Webset

cadence

object

required

How often the monitor will run

Show child attributes

cadence.cron

string

required

Cron expression for monitor cadence (must be a valid Unix cron with 5 fields). The schedule must trigger at most once per day.

cadence.timezone

string

default:Etc/UTC

IANA timezone (e.g., "America/New_York")

behavior

object

required

Behavior to perform when monitor runs

Show child attributes

behavior.type

string

default:search

required

Allowed value: "search"

behavior.config

object

required

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.

Show child attributes

behavior.config.count

number

required

The maximum number of results to find

behavior.config.query

string

The query to search for. By default, the query from the last search is used.

Required string length: 2 - 10000

behavior.config.criteria

object[]

The criteria to search for. By default, the criteria from the last search is used.

Maximum array length: 5

Show child attributes

behavior.config.criteria.description

string

required

Required string length: 2 - 1000

behavior.config.entity

Company · object

The entity to search for. By default, the entity from the last search/import is used.

Company
Person
Article
Research Paper
Custom

Show child attributes

behavior.config.entity.type

string

default:company

required

Allowed value: "company"

behavior.config.behavior

enum<string>

default:append

The behaviour of the Search when it is added to a Webset.

Available options:

override,

append

metadata

object

Show child attributes

metadata.{key}

string

Response

201 - application/json

Monitor created successfully

string

required

The unique identifier for the Monitor

object

enum<string>

required

The type of object

Available options:

monitor

status

enum<string>

required

The status of the Monitor

Available options:

enabled,

disabled

websetId

string

required

The id of the Webset the Monitor belongs to

cadence

object

required

How often the monitor will run

Show child attributes

cadence.cron

string

required

Cron expression for monitor cadence (must be a valid Unix cron with 5 fields). The schedule must trigger at most once per day.

cadence.timezone

string

default:Etc/UTC

IANA timezone (e.g., "America/New_York")

behavior

object

required

Behavior to perform when monitor runs

Show child attributes

behavior.type

string

default:search

required

Allowed value: "search"

behavior.config

object

required

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.

Show child attributes

behavior.config.count

number

required

The maximum number of results to find

behavior.config.query

string

The query to search for. By default, the query from the last search is used.

Required string length: 2 - 10000

behavior.config.criteria

object[]

The criteria to search for. By default, the criteria from the last search is used.

Maximum array length: 5

Show child attributes

behavior.config.criteria.description

string

required

Required string length: 2 - 1000

behavior.config.entity

Company · object

The entity to search for. By default, the entity from the last search/import is used.

Company
Person
Article
Research Paper
Custom

Show child attributes

behavior.config.entity.type

string

default:company

required

Allowed value: "company"

behavior.config.behavior

enum<string>

default:append

The behaviour of the Search when it is added to a Webset.

Available options:

override,

append

lastRun

MonitorRun · object

required

The last run of the monitor

Show child attributes

lastRun.id

string

required

The unique identifier for the Monitor Run

lastRun.object

enum<string>

required

The type of object

Available options:

monitor_run

lastRun.status

enum<string>

required

The status of the Monitor Run

Available options:

created,

running,

completed,

canceled,

failed

lastRun.monitorId

string

required

The monitor that the run is associated with

lastRun.type

enum<string>

required

The type of the Monitor Run

Available options:

search,

refresh

lastRun.completedAt

string<date-time> | null

required

When the run completed

lastRun.failedAt

string<date-time> | null

required

When the run failed

lastRun.failedReason

string | null

required

The reason the run failed

lastRun.canceledAt

string<date-time> | null

required

When the run was canceled

lastRun.createdAt

string<date-time>

required

When the run was created

lastRun.updatedAt

string<date-time>

required

When the run was last updated

nextRunAt

string<date-time> | null

required

Date and time when the next run will occur in

metadata

object

required

Set of key-value pairs you want to associate with this object.

Show child attributes

metadata.{key}

string

Maximum string length: 1000

createdAt

string<date-time>

required

When the monitor was created

updatedAt

string<date-time>

required

When the monitor was last updated

List Imports Get Monitor

⌘I

Getting Started

Dashboard

API

Create a Monitor

Authorizations

Body

Response