openapi: 3.1.0 info: title: Exa Monitors API version: 2.0.0 description: Exa Monitors API - subset of the Exa Public API. servers: - url: https://api.exa.ai security: - apiKey: [] - bearer: [] paths: /monitors: post: operationId: createMonitor summary: Create a Monitor description: 'Creates a new Monitor to run recurring Exa searches on a schedule. Monitors automatically execute your search query on a recurring schedule and deliver results to your webhook endpoint with automatic deduplication: - **Date-based filtering** only fetches content since the last run - **Semantic deduplication** tracks previous outputs to surface only new developments The response includes a `webhookSecret` that is only returned once at creation time. Store it securely for webhook signature verification.' tags: - Monitors requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSearchMonitorParameters' responses: '201': description: The created monitor with webhook secret content: application/json: schema: $ref: '#/components/schemas/CreateSearchMonitorResponse' get: operationId: listMonitors summary: List Monitors description: Lists all monitors for the authenticated team. Supports filtering by status and cursor-based pagination. tags: - Monitors parameters: - in: query name: status schema: type: string enum: - active - paused - disabled description: Filter monitors by status - in: query name: cursor schema: type: string description: Pagination cursor from a previous response - in: query name: limit schema: type: integer minimum: 1 maximum: 100 description: Number of results per page default: 50 - in: query name: name schema: type: string maxLength: 250 description: Filter monitors by name (case-insensitive substring match) - in: query name: metadata schema: description: 'Filter monitors by metadata key-value pairs (exact match, AND semantics). Use bracket notation: `metadata[key]=value`.' type: object propertyNames: type: string additionalProperties: type: string style: deepObject explode: true description: 'Filter monitors by metadata key-value pairs (exact match, AND semantics). Use bracket notation: `metadata[key]=value`.' responses: '200': description: A paginated list of monitors content: application/json: schema: $ref: '#/components/schemas/ListSearchMonitorsResponse' /monitors/batch: post: operationId: batchMonitors summary: Batch Action on Monitors description: 'Perform a batch action on monitors matching the provided filters. Supported actions: - **delete**: Permanently remove matching monitors - **pause**: Pause matching monitors - **unpause**: Unpause matching monitors Use `dry_run: true` (the default) to preview which monitors would be affected before performing the action. Results are paginated via the `limit` parameter; loop until `has_more` is `false` to process all matching monitors.' tags: - Monitors requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BatchMonitorsRequest' responses: '200': description: Batch action result content: application/json: schema: $ref: '#/components/schemas/BatchMonitorsResponse' /monitors/{id}: get: operationId: getMonitor summary: Get a Monitor description: Retrieves a single monitor by its ID. tags: - Monitors parameters: - in: path name: id schema: type: string description: The monitor ID required: true description: The monitor ID responses: '200': description: The monitor content: application/json: schema: $ref: '#/components/schemas/SearchMonitor' patch: operationId: updateMonitor summary: Update a Monitor description: Updates an existing monitor. All fields are optional. For `search`, you can send a partial object containing only the fields you want to change. Set `trigger` to `null` to remove the schedule. tags: - Monitors parameters: - in: path name: id schema: type: string description: The monitor ID required: true description: The monitor ID requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateSearchMonitorParameters' responses: '200': description: The updated monitor content: application/json: schema: $ref: '#/components/schemas/SearchMonitor' delete: operationId: deleteMonitor summary: Delete a Monitor description: Deletes a monitor. This cannot be undone. tags: - Monitors parameters: - in: path name: id schema: type: string description: The monitor ID required: true description: The monitor ID responses: '200': description: The deleted monitor content: application/json: schema: $ref: '#/components/schemas/SearchMonitor' /monitors/{id}/trigger: post: operationId: triggerMonitor summary: Trigger a Monitor description: Triggers a run immediately, regardless of the schedule. Works for monitors with status `active` or `paused`. tags: - Monitors parameters: - in: path name: id schema: type: string description: The monitor ID required: true description: The monitor ID responses: '200': description: Whether the monitor was triggered content: application/json: schema: $ref: '#/components/schemas/TriggerSearchMonitorResponse' /monitors/{id}/runs: get: operationId: listRuns summary: List Runs description: Lists all runs for a monitor with cursor-based pagination. Runs are returned in reverse chronological order. tags: - Runs parameters: - in: path name: id schema: type: string description: The monitor ID required: true description: The monitor ID - in: query name: cursor schema: type: string description: Pagination cursor from a previous response - in: query name: limit schema: type: integer minimum: 1 maximum: 100 description: Number of results per page default: 50 responses: '200': description: A paginated list of runs content: application/json: schema: $ref: '#/components/schemas/ListSearchMonitorRunsResponse' /monitors/{id}/runs/{runId}: get: operationId: getRun summary: Get a Run description: Retrieves a single run by its ID, including the full output if the run is completed. tags: - Runs parameters: - in: path name: id schema: type: string description: The monitor ID required: true description: The monitor ID - in: path name: runId schema: type: string description: The run ID required: true description: The run ID responses: '200': description: The run content: application/json: schema: $ref: '#/components/schemas/SearchMonitorRun' /v0/monitors: servers: - url: https://api.exa.ai/websets post: description: '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' operationId: monitors-create parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateMonitorParameters' responses: '201': description: Monitor created successfully content: application/json: schema: $ref: '#/components/schemas/Monitor' headers: X-Request-Id: schema: type: string description: Unique identifier for the request. example: req_N6SsgoiaOQOPqsYKKiw5 required: true summary: Create a Monitor tags: - Monitors 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 monitor\ \ = await exa.websets.monitors.create({\n websetId: \"webset_id\",\n cadence: {\n cron: \"0 9 * * 1\", // Every\ \ Monday at 9 AM\n timezone: \"America/New_York\",\n },\n behavior: {\n type: \"search\",\n config: {\n\ \ behavior: \"append\",\n query: \"new companies to monitor\",\n count: 10,\n },\n },\n});\n\n\ console.log(`Created monitor: ${monitor.id}`);" - lang: python label: Python source: "# pip install exa-py\nfrom exa_py import Exa\n\nexa = Exa(\"YOUR_EXA_API_KEY\")\n\nmonitor = exa.websets.monitors.create(\n\ \ params={\n \"websetId\": \"webset_id\",\n \"cadence\": {\n \"cron\": \"0 9 * * 1\"\ , # Every Monday at 9 AM\n \"timezone\": \"America/New_York\",\n },\n \"behavior\": {\n\ \ \"type\": \"search\",\n \"config\": {\n \"behavior\": \"append\",\n \ \ \"query\": \"new companies to monitor\",\n \"count\": 10,\n },\n },\n\ \ }\n)\n\nprint(f\"Created monitor: {monitor.id}\")" get: description: Lists all monitors for the Webset. operationId: monitors-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: websetId required: false in: query description: The id of the Webset to list monitors for schema: type: string responses: '200': description: List of monitors content: application/json: schema: $ref: '#/components/schemas/ListMonitorsResponse' headers: X-Request-Id: schema: type: string description: Unique identifier for the request. example: req_N6SsgoiaOQOPqsYKKiw5 required: true summary: List Monitors tags: - Monitors 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 monitors\ \ = await exa.websets.monitors.list({\n webset_id: \"webset_id\",\n});\n\nconsole.log(`Found ${monitors.data.length}\ \ monitors`);\nmonitors.data.forEach((monitor) => {\n console.log(`- ${monitor.id}: ${monitor.status}`);\n});" - lang: python label: Python source: "# pip install exa-py\nfrom exa_py import Exa\n\nexa = Exa(\"YOUR_EXA_API_KEY\")\n\nmonitors = exa.websets.monitors.list(webset_id=\"\ webset_id\")\n\nprint(f\"Found {len(monitors.data)} monitors\")\nfor monitor in monitors.data:\n print(f\"- {monitor.id}:\ \ {monitor.status}\")" /v0/monitors/{id}: servers: - url: https://api.exa.ai/websets get: description: Gets a specific monitor. operationId: monitors-get parameters: - name: id required: true in: path description: The id of the Monitor schema: type: string responses: '200': description: Monitor details content: application/json: schema: $ref: '#/components/schemas/Monitor' headers: X-Request-Id: schema: type: string description: Unique identifier for the request. example: req_N6SsgoiaOQOPqsYKKiw5 required: true summary: Get Monitor tags: - Monitors 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 monitor = await exa.websets.monitors.get("monitor_id"); console.log(`Monitor: ${monitor.id} - ${monitor.status}`);' - lang: python label: Python source: '# pip install exa-py from exa_py import Exa exa = Exa("YOUR_EXA_API_KEY") monitor = exa.websets.monitors.get("monitor_id") print(f"Monitor: {monitor.id} - {monitor.status}")' patch: description: Updates a monitor configuration. operationId: monitors-update parameters: - name: id required: true in: path description: The id of the Monitor schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateMonitor' responses: '200': description: Monitor updated successfully content: application/json: schema: $ref: '#/components/schemas/Monitor' headers: X-Request-Id: schema: type: string description: Unique identifier for the request. example: req_N6SsgoiaOQOPqsYKKiw5 required: true summary: Update Monitor tags: - Monitors 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 monitor\ \ = await exa.websets.monitors.update(\"monitor_id\", {\n cadence: {\n cron: \"0 14 * * *\", // Every day at\ \ 2 PM\n timezone: \"America/New_York\",\n },\n});\n\nconsole.log(`Updated monitor: ${monitor.id}`);" - lang: python label: Python source: "# pip install exa-py\nfrom exa_py import Exa\n\nexa = Exa(\"YOUR_EXA_API_KEY\")\n\nmonitor = exa.websets.monitors.update(\n\ \ \"monitor_id\",\n params={\n \"cadence\": {\n \"cron\": \"0 14 * * *\", # Every day at\ \ 2 PM\n \"timezone\": \"America/New_York\",\n }\n },\n)\n\nprint(f\"Updated monitor: {monitor.id}\"\ )" delete: description: Deletes a monitor. operationId: monitors-delete parameters: - name: id required: true in: path description: The id of the Monitor schema: type: string responses: '200': description: Monitor deleted successfully content: application/json: schema: $ref: '#/components/schemas/Monitor' headers: X-Request-Id: schema: type: string description: Unique identifier for the request. example: req_N6SsgoiaOQOPqsYKKiw5 required: true summary: Delete Monitor tags: - Monitors security: - apiKey: [] - bearer: [] x-codeSamples: - lang: javascript label: JavaScript source: '// npm install exa-js import Exa from "exa-js"; const exa = new Exa("YOUR_EXA_API_KEY"); await exa.websets.monitors.delete("monitor_id"); console.log("Monitor deleted successfully");' - lang: python label: Python source: '# pip install exa-py from exa_py import Exa exa = Exa("YOUR_EXA_API_KEY") exa.websets.monitors.delete("monitor_id") print("Monitor deleted successfully")' /v0/monitors/{monitor}/runs: servers: - url: https://api.exa.ai/websets get: description: Lists all runs for the Monitor. operationId: monitors-runs-list parameters: - name: monitor required: true in: path description: The id of the Monitor to list runs for schema: type: string responses: '200': description: List of monitor runs content: application/json: schema: $ref: '#/components/schemas/ListMonitorRunsResponse' headers: X-Request-Id: schema: type: string description: Unique identifier for the request. example: req_N6SsgoiaOQOPqsYKKiw5 required: true summary: List Monitor Runs tags: - Monitors Runs 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 runs\ \ = await exa.websets.monitors.runs.list(\"monitor_id\");\n\nconsole.log(`Found ${runs.data.length} monitor runs`);\n\ runs.data.forEach((run) => {\n console.log(`- ${run.id}: ${run.status}`);\n});" - lang: python label: Python source: "# pip install exa-py\nfrom exa_py import Exa\n\nexa = Exa(\"YOUR_EXA_API_KEY\")\n\nruns = exa.websets.monitors.runs.list(\"\ monitor_id\")\n\nprint(f\"Found {len(runs.data)} monitor runs\")\nfor run in runs.data:\n print(f\"- {run.id}:\ \ {run.status}\")" /v0/monitors/{monitor}/runs/{id}: servers: - url: https://api.exa.ai/websets get: description: Gets a specific monitor run. operationId: monitors-runs-get parameters: - name: monitor required: true in: path description: The id of the Monitor to get the run for schema: type: string - name: id required: true in: path schema: type: string responses: '200': description: Monitor run details content: application/json: schema: $ref: '#/components/schemas/MonitorRun' headers: X-Request-Id: schema: type: string description: Unique identifier for the request. example: req_N6SsgoiaOQOPqsYKKiw5 required: true summary: Get Monitor Run tags: - Monitors Runs 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 run = await exa.websets.monitors.runs.get("monitor_id", "run_id"); console.log(`Monitor run: ${run.id} - ${run.status}`);' - lang: python label: Python source: '# pip install exa-py from exa_py import Exa exa = Exa("YOUR_EXA_API_KEY") run = exa.websets.monitors.runs.get("monitor_id", "run_id") print(f"Monitor run: {run.id} - {run.status}")' components: schemas: ArticleEntity: type: - object properties: type: type: string const: article default: article required: - type title: Article BatchMonitorsRequest: type: object properties: action: type: string enum: - delete - pause - unpause description: The action to perform on matching monitors. `delete` permanently removes them, `pause` sets their status to paused, and `unpause` sets their status to active. filter: type: object properties: name: type: string maxLength: 250 description: Filter by name (case-insensitive substring match) status: type: string enum: - active - paused - disabled description: Filter by monitor status metadata: type: object propertyNames: type: string additionalProperties: type: string maxLength: 1000 description: Filter by metadata key-value pairs (exact match, AND semantics) description: At least one filter field must be provided to prevent accidental bulk operations. dry_run: type: boolean description: When `true`, returns the monitors that would be affected without performing the action. Defaults to `true`. default: true limit: type: integer minimum: 1 maximum: 500 description: Maximum number of monitors to process in a single request. Defaults to 50, maximum 500. default: 50 required: - action - filter BatchMonitorsResponse: type: object properties: action: type: string enum: - delete - pause - unpause description: The action that was performed affected: type: integer description: The number of monitors affected by the action ids: type: array items: type: string description: The IDs of the monitors that were affected dry_run: type: boolean description: Whether this was a dry run has_more: type: boolean description: Whether there are more monitors matching the filter. If `true`, repeat the request to process the next batch. required: - action - affected - ids - dry_run - has_more additionalProperties: false CompanyEntity: type: - object properties: type: type: string const: company default: company required: - type title: Company CreateMonitorParameters: type: - object properties: websetId: type: - string description: The id of the Webset 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 metadata: type: - object additionalProperties: type: - string required: - websetId - cadence - behavior CreateSearchMonitorParameters: type: object properties: name: type: string description: An optional name for the monitor search: $ref: '#/components/schemas/SearchMonitorSearch' trigger: $ref: '#/components/schemas/SearchMonitorTrigger' outputSchema: $ref: '#/components/schemas/SearchMonitorOutputSchema' metadata: type: object propertyNames: type: string additionalProperties: type: string description: Optional key-value metadata. Echoed back in webhook deliveries so you can route updates to systems like Slack. example: slack_channel_id: C123ABC slack_thread_id: '1745444400.123456' user_id: U123ABC webhook: $ref: '#/components/schemas/SearchMonitorWebhook' required: - search - webhook CreateSearchMonitorResponse: type: object properties: id: type: string description: The unique identifier for the monitor name: anyOf: - type: string - type: 'null' description: An optional display name status: type: string enum: - active - paused - disabled description: The status of the monitor. `active` monitors run on schedule and can be triggered manually. `paused` monitors can only be triggered manually. `disabled` monitors are auto-disabled after 10 consecutive authentication failures. search: $ref: '#/components/schemas/SearchMonitorSearchOutput' trigger: anyOf: - $ref: '#/components/schemas/SearchMonitorTriggerOutput' - type: 'null' description: The interval-based schedule for automatic runs. Null if no schedule is set. outputSchema: $ref: '#/components/schemas/SearchMonitorOutputSchemaOutput' metadata: anyOf: - type: object propertyNames: type: string additionalProperties: type: string description: Caller-provided key-value metadata for your own tracking. example: slack_channel_id: C123ABC slack_thread_id: '1745444400.123456' user_id: U123ABC - type: 'null' description: Optional key-value metadata for your own tracking. Echoed back in webhook deliveries so you can route updates to systems like Slack. example: slack_channel_id: C123ABC slack_thread_id: '1745444400.123456' user_id: U123ABC webhook: $ref: '#/components/schemas/SearchMonitorWebhookOutput' nextRunAt: anyOf: - type: string format: date-time - type: 'null' description: When the next scheduled run will occur. Null if no trigger is set. format: date-time 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 webhookSecret: type: string description: The secret used to verify webhook signatures. This is only returned once at creation time. Store it securely. required: - id - name - status - search - trigger - outputSchema - metadata - webhook - nextRunAt - createdAt - updatedAt - webhookSecret additionalProperties: false CustomEntity: type: - object properties: type: type: string const: custom default: custom description: type: - string minLength: 2 maxLength: 200 required: - type - description title: Custom 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' JsonValue: description: Any JSON value. oneOf: - type: 'null' - type: boolean - type: number - type: string - type: array items: $ref: '#/components/schemas/JsonValue' - type: object propertyNames: type: string additionalProperties: $ref: '#/components/schemas/JsonValue' ListMonitorRunsResponse: type: - object properties: data: type: - array items: type: - object $ref: '#/components/schemas/MonitorRun' description: The list of monitor runs 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 ListMonitorsResponse: type: - object properties: data: type: - array items: type: - object $ref: '#/components/schemas/Monitor' description: The list of monitors 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 ListSearchMonitorRunsResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/SearchMonitorRun' description: The list of runs hasMore: type: boolean description: Whether there are more results nextCursor: anyOf: - type: string - type: 'null' description: Cursor for the next page required: - data - hasMore additionalProperties: false ListSearchMonitorsResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/SearchMonitor' description: The list of monitors hasMore: type: boolean description: Whether there are more results nextCursor: anyOf: - type: string - type: 'null' description: Cursor for the next page required: - data - hasMore additionalProperties: false 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 MonitorBehavior: 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 MonitorCadence: 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 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 PersonEntity: type: - object properties: type: type: string const: person default: person required: - type title: Person ResearchPaperEntity: type: - object properties: type: type: string const: research_paper default: research_paper required: - type title: Research Paper SearchMonitor: type: object properties: id: type: string description: The unique identifier for the monitor name: anyOf: - type: string - type: 'null' description: An optional display name status: type: string enum: - active - paused - disabled description: The status of the monitor. `active` monitors run on schedule and can be triggered manually. `paused` monitors can only be triggered manually. `disabled` monitors are auto-disabled after 10 consecutive authentication failures. search: $ref: '#/components/schemas/SearchMonitorSearchOutput' trigger: anyOf: - $ref: '#/components/schemas/SearchMonitorTriggerOutput' - type: 'null' description: The interval-based schedule for automatic runs. Null if no schedule is set. outputSchema: $ref: '#/components/schemas/SearchMonitorOutputSchemaOutput' metadata: anyOf: - type: object propertyNames: type: string additionalProperties: type: string description: Caller-provided key-value metadata for your own tracking. example: slack_channel_id: C123ABC slack_thread_id: '1745444400.123456' user_id: U123ABC - type: 'null' description: Optional key-value metadata for your own tracking. Echoed back in webhook deliveries so you can route updates to systems like Slack. example: slack_channel_id: C123ABC slack_thread_id: '1745444400.123456' user_id: U123ABC webhook: $ref: '#/components/schemas/SearchMonitorWebhookOutput' nextRunAt: anyOf: - type: string format: date-time - type: 'null' description: When the next scheduled run will occur. Null if no trigger is set. format: date-time 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 - name - status - search - trigger - outputSchema - metadata - webhook - nextRunAt - createdAt - updatedAt additionalProperties: false SearchMonitorContents: type: object properties: text: description: Text extraction options for each result. oneOf: - type: boolean title: Simple text retrieval description: If true, returns full page text with default settings. If false, disables text return. default: false - type: object properties: maxCharacters: anyOf: - type: integer minimum: 1 maximum: 10000 description: Maximum character limit for the full page text. Useful for controlling response size and API costs. Maximum supported value is 10000. example: 1000 - type: 'null' includeHtmlTags: anyOf: - type: boolean description: 'If true, include lightweight HTML tags in returned text instead of plain markdown-style text. Use maxAgeHours: 0 when you need this applied to freshly fetched content.' example: false default: false - type: 'null' verbosity: anyOf: - type: string enum: - compact - standard - full description: 'Controls text rendering verbosity. compact focuses on main content, standard includes more surrounding page context, and full requests the most complete rendered text. Some pages may produce identical standard and full output. Use maxAgeHours: 0 when you need this applied to freshly fetched content.' example: standard default: compact - type: 'null' includeSections: anyOf: - type: array items: type: string enum: - header - navigation - banner - body - sidebar - footer - metadata description: 'Best-effort. Only include content classified into these semantic page sections. Section classification may be unavailable or incomplete for some pages; validate output if strict filtering is required. Use maxAgeHours: 0 when you need this applied to freshly fetched content.' example: - body - header - type: 'null' excludeSections: anyOf: - type: array items: type: string enum: - header - navigation - banner - body - sidebar - footer - metadata description: 'Exclude content classified into these semantic page sections. Section classification is best-effort. Use maxAgeHours: 0 when you need this applied to freshly fetched content.' example: - navigation - footer - sidebar - type: 'null' title: Advanced text options description: Advanced options for controlling text extraction. Use this when you need to limit text length or include HTML structure. highlights: description: Text snippets the LLM identifies as most relevant from each page. oneOf: - type: boolean title: Simple highlights retrieval description: If true, returns highlights with default settings. If false, disables highlights. default: false - type: object properties: query: anyOf: - type: string description: Custom query that guides which highlights the LLM picks. example: Key advancements - type: 'null' maxCharacters: anyOf: - type: integer minimum: 1 maximum: 10000 description: Maximum number of characters to return for highlights. Controls the total length of highlight text returned per URL. Maximum supported value is 10000. example: 2000 - type: 'null' numSentences: anyOf: - type: integer minimum: 1 description: 'Deprecated and will be removed in a future release. Currently mapped to a character budget of about 1333 characters per sentence. Pass highlights: true for default highlights, or { query } to guide selection with your own query.' example: 1 deprecated: true - type: 'null' highlightsPerUrl: anyOf: - type: integer minimum: 1 description: 'Deprecated and will be removed in a future release. Currently ignored. Pass highlights: true for default highlights, or { query } to guide selection with your own query.' example: 1 deprecated: true - type: 'null' title: Advanced highlights options description: 'Advanced options for steering highlight extraction. Pass highlights: true for the highest-quality default; supply this object only when you need to guide selection with your own query.' summary: description: Return an LLM-generated summary. Pass `true` for defaults, or an object with `query` and `maxTokens`. oneOf: - type: boolean - type: object properties: query: anyOf: - type: string description: Custom query for the LLM-generated summary. example: Main developments - type: 'null' maxTokens: type: integer minimum: 1 description: Maximum tokens for the generated summary. extras: type: object properties: links: anyOf: - type: integer minimum: 0 maximum: 1000 description: Number of URLs to return from each webpage. example: 1 default: 0 - type: 'null' imageLinks: anyOf: - type: integer minimum: 0 maximum: 1000 description: Number of images to return for each result. example: 1 default: 0 - type: 'null' richImageLinks: anyOf: - type: integer minimum: 0 maximum: 1000 description: Number of rich image links to return for each result. default: 0 - type: 'null' richLinks: anyOf: - type: integer minimum: 0 maximum: 1000 description: Number of rich links to return for each result. default: 0 - type: 'null' codeBlocks: anyOf: - type: integer minimum: 0 maximum: 1000 description: Number of code blocks to return for each result. default: 0 - type: 'null' description: Extra parameters to pass. context: description: 'Deprecated: Use highlights or text instead. Returns page contents as a combined context string.' deprecated: true oneOf: - type: boolean description: 'Deprecated: Use highlights or text instead. Returns page contents as a combined context string.' example: true deprecated: true - type: object properties: maxCharacters: type: integer minimum: 1 maximum: 10000 description: Deprecated. Maximum character limit for the context string. Maximum supported value is 10000. example: 10000 description: 'Deprecated: Use highlights or text instead. Returns page contents as a combined context string.' deprecated: true livecrawl: description: Crawl strategy for fetching page content oneOf: - type: string enum: - never - always - fallback - preferred - type: string const: auto livecrawlTimeout: type: integer exclusiveMinimum: 0 maximum: 90000 description: The timeout for livecrawling in milliseconds. example: 1000 default: 10000 maxAgeHours: type: integer minimum: -1 maximum: 720 description: Maximum age of cached content in hours. Positive values use cached content if it is less than this many hours old; 0 fetches fresh content and is the supported way to apply text rendering options to newly fetched pages; -1 always uses cache; omitted uses fallback fetching when cached content is unavailable. Maximum supported value is 720 hours. example: 24 filterEmptyResults: type: boolean description: Filter out results with no content subpages: type: integer minimum: 0 maximum: 100 description: The number of subpages to crawl. The actual number crawled may be limited by system constraints. example: 1 default: 0 subpageTarget: description: Term to find specific subpages of search results. Can be a single string or an array of strings. example: sources oneOf: - type: string minLength: 1 maxLength: 100 - minItems: 0 maxItems: 100 type: array items: type: string minLength: 1 maxLength: 100 description: Content extraction options applied to each search result. All fields are optional. SearchMonitorContentsOutput: type: object properties: text: description: Text extraction options for each result. oneOf: - type: boolean title: Simple text retrieval description: If true, returns full page text with default settings. If false, disables text return. default: false - type: object properties: maxCharacters: anyOf: - type: integer minimum: 1 maximum: 10000 description: Maximum character limit for the full page text. Useful for controlling response size and API costs. Maximum supported value is 10000. example: 1000 - type: 'null' includeHtmlTags: anyOf: - type: boolean description: 'If true, include lightweight HTML tags in returned text instead of plain markdown-style text. Use maxAgeHours: 0 when you need this applied to freshly fetched content.' example: false default: false - type: 'null' verbosity: anyOf: - type: string enum: - compact - standard - full description: 'Controls text rendering verbosity. compact focuses on main content, standard includes more surrounding page context, and full requests the most complete rendered text. Some pages may produce identical standard and full output. Use maxAgeHours: 0 when you need this applied to freshly fetched content.' example: standard default: compact - type: 'null' includeSections: anyOf: - type: array items: type: string enum: - header - navigation - banner - body - sidebar - footer - metadata description: 'Best-effort. Only include content classified into these semantic page sections. Section classification may be unavailable or incomplete for some pages; validate output if strict filtering is required. Use maxAgeHours: 0 when you need this applied to freshly fetched content.' example: - body - header - type: 'null' excludeSections: anyOf: - type: array items: type: string enum: - header - navigation - banner - body - sidebar - footer - metadata description: 'Exclude content classified into these semantic page sections. Section classification is best-effort. Use maxAgeHours: 0 when you need this applied to freshly fetched content.' example: - navigation - footer - sidebar - type: 'null' additionalProperties: false title: Advanced text options description: Advanced options for controlling text extraction. Use this when you need to limit text length or include HTML structure. highlights: description: Text snippets the LLM identifies as most relevant from each page. oneOf: - type: boolean title: Simple highlights retrieval description: If true, returns highlights with default settings. If false, disables highlights. default: false - type: object properties: query: anyOf: - type: string description: Custom query that guides which highlights the LLM picks. example: Key advancements - type: 'null' maxCharacters: anyOf: - type: integer minimum: 1 maximum: 10000 description: Maximum number of characters to return for highlights. Controls the total length of highlight text returned per URL. Maximum supported value is 10000. example: 2000 - type: 'null' numSentences: anyOf: - type: integer minimum: 1 description: 'Deprecated and will be removed in a future release. Currently mapped to a character budget of about 1333 characters per sentence. Pass highlights: true for default highlights, or { query } to guide selection with your own query.' example: 1 deprecated: true - type: 'null' highlightsPerUrl: anyOf: - type: integer minimum: 1 description: 'Deprecated and will be removed in a future release. Currently ignored. Pass highlights: true for default highlights, or { query } to guide selection with your own query.' example: 1 deprecated: true - type: 'null' additionalProperties: false title: Advanced highlights options description: 'Advanced options for steering highlight extraction. Pass highlights: true for the highest-quality default; supply this object only when you need to guide selection with your own query.' summary: description: Return an LLM-generated summary. Pass `true` for defaults, or an object with `query` and `maxTokens`. oneOf: - type: boolean - type: object properties: query: anyOf: - type: string description: Custom query for the LLM-generated summary. example: Main developments - type: 'null' maxTokens: type: integer minimum: 1 description: Maximum tokens for the generated summary. additionalProperties: false extras: type: object properties: links: anyOf: - type: integer minimum: 0 maximum: 1000 description: Number of URLs to return from each webpage. example: 1 default: 0 - type: 'null' imageLinks: anyOf: - type: integer minimum: 0 maximum: 1000 description: Number of images to return for each result. example: 1 default: 0 - type: 'null' richImageLinks: anyOf: - type: integer minimum: 0 maximum: 1000 description: Number of rich image links to return for each result. default: 0 - type: 'null' richLinks: anyOf: - type: integer minimum: 0 maximum: 1000 description: Number of rich links to return for each result. default: 0 - type: 'null' codeBlocks: anyOf: - type: integer minimum: 0 maximum: 1000 description: Number of code blocks to return for each result. default: 0 - type: 'null' additionalProperties: false description: Extra parameters to pass. context: description: 'Deprecated: Use highlights or text instead. Returns page contents as a combined context string.' deprecated: true oneOf: - type: boolean description: 'Deprecated: Use highlights or text instead. Returns page contents as a combined context string.' example: true deprecated: true - type: object properties: maxCharacters: type: integer minimum: 1 maximum: 10000 description: Deprecated. Maximum character limit for the context string. Maximum supported value is 10000. example: 10000 additionalProperties: false description: 'Deprecated: Use highlights or text instead. Returns page contents as a combined context string.' deprecated: true livecrawl: description: Crawl strategy for fetching page content oneOf: - type: string enum: - never - always - fallback - preferred - type: string const: auto livecrawlTimeout: type: integer exclusiveMinimum: 0 maximum: 90000 description: The timeout for livecrawling in milliseconds. example: 1000 default: 10000 maxAgeHours: type: integer minimum: -1 maximum: 720 description: Maximum age of cached content in hours. Positive values use cached content if it is less than this many hours old; 0 fetches fresh content and is the supported way to apply text rendering options to newly fetched pages; -1 always uses cache; omitted uses fallback fetching when cached content is unavailable. Maximum supported value is 720 hours. example: 24 filterEmptyResults: type: boolean description: Filter out results with no content subpages: type: integer minimum: 0 maximum: 100 description: The number of subpages to crawl. The actual number crawled may be limited by system constraints. example: 1 default: 0 subpageTarget: description: Term to find specific subpages of search results. Can be a single string or an array of strings. example: sources oneOf: - type: string minLength: 1 maxLength: 100 - minItems: 0 maxItems: 100 type: array items: type: string minLength: 1 maxLength: 100 additionalProperties: false description: Content extraction options applied to each search result. All fields are optional. SearchMonitorOutputSchema: anyOf: - oneOf: - type: object properties: type: type: string const: text description: type: string required: - type - type: object properties: type: type: string const: object description: type: string properties: type: object propertyNames: type: string additionalProperties: $ref: '#/components/schemas/JsonValue' required: type: array items: type: string additionalProperties: type: boolean required: - type additionalProperties: $ref: '#/components/schemas/JsonValue' description: JSON schema for synthesized output. Supported root types are "text" and "object". When provided, the response includes an output object whose content matches this schema. Works with every search type and adds about 2 seconds of synthesis latency on top of the selected search type. type: object - type: 'null' description: 'Controls the format of the run output. Defaults to `{ "type": "text" }` if not specified. When `type` is `"text"`, the output is a plain text summary. When `type` is `"object"`, the output is structured JSON. If no `properties` are specified with `"object"` type, a schema is inferred automatically; otherwise the output adheres to the provided schema.' SearchMonitorOutputSchemaOutput: anyOf: - oneOf: - type: object properties: type: type: string const: text description: type: string required: - type additionalProperties: false - type: object properties: type: type: string const: object description: type: string properties: type: object propertyNames: type: string additionalProperties: $ref: '#/components/schemas/JsonValue' required: type: array items: type: string additionalProperties: type: boolean required: - type additionalProperties: $ref: '#/components/schemas/JsonValue' description: JSON schema for synthesized output. Supported root types are "text" and "object". When provided, the response includes an output object whose content matches this schema. Works with every search type and adds about 2 seconds of synthesis latency on top of the selected search type. type: object - type: 'null' description: 'Controls the format of the run output. Defaults to `{ "type": "text" }` if not specified. When `type` is `"text"`, the output is a plain text summary. When `type` is `"object"`, the output is structured JSON. If no `properties` are specified with `"object"` type, a schema is inferred automatically; otherwise the output adheres to the provided schema.' SearchMonitorRun: type: object properties: id: type: string description: The unique identifier for the run monitorId: type: string description: The monitor this run belongs to status: type: string enum: - pending - running - completed - failed - cancelled description: The status of the run output: anyOf: - $ref: '#/components/schemas/SearchMonitorRunOutput' - type: 'null' description: The output of the run. Null until the run completes. failReason: anyOf: - type: string enum: - api_key_invalid - insufficient_credits - invalid_params - rate_limited - search_unavailable - search_failed - internal_error - type: 'null' description: The reason the run failed. Null unless status is `failed`. startedAt: anyOf: - type: string format: date-time - type: 'null' description: When the run started executing format: date-time completedAt: anyOf: - type: string format: date-time - type: 'null' description: When the run completed successfully format: date-time failedAt: anyOf: - type: string format: date-time - type: 'null' description: When the run failed format: date-time cancelledAt: anyOf: - type: string format: date-time - type: 'null' description: When the run was cancelled format: date-time durationMs: anyOf: - type: integer - type: 'null' description: Total execution time in milliseconds 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 - monitorId - status - output - failReason - startedAt - completedAt - failedAt - cancelledAt - durationMs - createdAt - updatedAt additionalProperties: false SearchMonitorRunOutput: type: object properties: results: anyOf: - type: array items: type: object propertyNames: type: string additionalProperties: $ref: '#/components/schemas/JsonValue' - type: 'null' description: The search results content: description: Synthesized content from the search results. Shape depends on `outputSchema.type`. oneOf: - $ref: '#/components/schemas/JsonValue' - type: 'null' grounding: anyOf: - type: array items: type: object properties: field: type: string description: The output field this citation applies to citations: type: array items: type: object properties: url: type: string format: uri description: Source URL. title: type: string description: Source title. required: - url - title additionalProperties: false confidence: type: string enum: - low - medium - high description: Model-reported reliability for this field. required: - field - citations - confidence additionalProperties: false - type: 'null' description: Field-level citations with confidence levels additionalProperties: false SearchMonitorSearch: type: object properties: query: type: string minLength: 1 description: The query string for the search. example: Latest developments in LLM capabilities numResults: type: integer minimum: 1 maximum: 100 description: Number of results to return. Limits vary by search type. The maximum public limit is 100 results. Contact sales (hello@exa.ai) to discuss higher limits. example: 10 default: 10 contents: $ref: '#/components/schemas/SearchMonitorContents' required: - query SearchMonitorSearchOutput: type: object properties: query: type: string minLength: 1 description: The query string for the search. example: Latest developments in LLM capabilities numResults: type: integer minimum: 1 maximum: 100 description: Number of results to return. Limits vary by search type. The maximum public limit is 100 results. Contact sales (hello@exa.ai) to discuss higher limits. example: 10 default: 10 contents: $ref: '#/components/schemas/SearchMonitorContentsOutput' required: - query additionalProperties: false SearchMonitorTrigger: type: object properties: type: type: string const: interval description: The type of trigger. Currently only `interval` is supported. default: interval period: type: string description: A duration string specifying how often the monitor runs (e.g., "1h", "6h", "1d", "7d"). Single-unit only. Minimum interval is 1 hour. The schedule is anchored to the monitor's creation time (e.g., a daily monitor created at 2:30 PM runs daily around 2:30 PM). example: 6h required: - type - period SearchMonitorTriggerOutput: type: object properties: type: type: string const: interval description: The type of trigger. Currently only `interval` is supported. default: interval period: type: string description: A duration string specifying how often the monitor runs (e.g., "1h", "6h", "1d", "7d"). Single-unit only. Minimum interval is 1 hour. The schedule is anchored to the monitor's creation time (e.g., a daily monitor created at 2:30 PM runs daily around 2:30 PM). example: 6h required: - type - period additionalProperties: false SearchMonitorWebhook: type: object properties: url: type: string format: uri description: The HTTPS URL to receive webhook events. Must not point to localhost or private IP ranges. events: type: array items: type: string enum: - monitor.created - monitor.updated - monitor.deleted - monitor.run.created - monitor.run.completed description: Which events to subscribe to. Defaults to all events if not specified. required: - url SearchMonitorWebhookOutput: type: object properties: url: type: string format: uri description: The HTTPS URL to receive webhook events. Must not point to localhost or private IP ranges. events: type: array items: type: string enum: - monitor.created - monitor.updated - monitor.deleted - monitor.run.created - monitor.run.completed description: Which events to subscribe to. Defaults to all events if not specified. required: - url additionalProperties: false TriggerSearchMonitorResponse: type: object properties: triggered: type: boolean description: Whether the monitor was successfully triggered required: - triggered additionalProperties: false UpdateMonitor: type: - object properties: status: type: - string enum: - enabled - disabled description: The status of the monitor. metadata: type: - object additionalProperties: type: - string cadence: type: - object $ref: '#/components/schemas/MonitorCadence' behavior: type: - object $ref: '#/components/schemas/MonitorBehavior' UpdateSearchMonitorParameters: type: object properties: name: anyOf: - type: string - type: 'null' description: Update the monitor name status: type: string enum: - active - paused description: Update the monitor status (can only set to `active` or `paused`) search: type: object properties: query: type: string minLength: 1 description: The query string for the search. example: Latest developments in LLM capabilities numResults: type: integer minimum: 1 maximum: 100 description: Number of results to return. Limits vary by search type. The maximum public limit is 100 results. Contact sales (hello@exa.ai) to discuss higher limits. example: 10 default: 10 contents: $ref: '#/components/schemas/SearchMonitorContents' description: Partial search params to merge. All fields are optional for updates. trigger: anyOf: - type: object properties: type: type: string const: interval description: The type of trigger. Currently only `interval` is supported. default: interval period: type: string description: A duration string specifying how often the monitor runs (e.g., "1h", "6h", "1d", "7d"). Single-unit only. Minimum interval is 1 hour. - type: 'null' description: Update the schedule. Set to null to remove the schedule. outputSchema: $ref: '#/components/schemas/SearchMonitorOutputSchema' metadata: anyOf: - type: object propertyNames: type: string additionalProperties: type: string description: Caller-provided key-value metadata for your own tracking. example: slack_channel_id: C123ABC slack_thread_id: '1745444400.123456' user_id: U123ABC - type: 'null' description: Update metadata. Set to null to remove. Echoed back in webhook deliveries so you can route updates to systems like Slack. example: slack_channel_id: C123ABC slack_thread_id: '1745444400.123456' user_id: U123ABC webhook: type: object properties: url: type: string format: uri description: The HTTPS URL to receive webhook events. Must not point to localhost or private IP ranges. events: type: array items: type: string enum: - monitor.created - monitor.updated - monitor.deleted - monitor.run.created - monitor.run.completed description: Which events to subscribe to. Defaults to all events if not specified. description: Partial webhook params to merge. All fields are optional for updates. 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 .' bearer: type: http scheme: bearer description: 'Pass your Exa API key in the x-api-key header. You can also authenticate with Authorization: Bearer .'