{ "openapi": "3.1.0", "info": { "title": "Exa Public API", "version": "2.0.0" }, "servers": [ { "url": "https://api.exa.ai" } ], "security": [ { "apiKey": [] }, { "bearer": [] } ], "paths": { "/search": { "post": { "operationId": "search", "summary": "Search", "description": "Perform a search with an Exa prompt-engineered query and retrieve a list of relevant results. Optionally get contents.", "x-payment-info": { "price": { "mode": "dynamic", "currency": "USD", "min": "0.007", "max": "0.015" }, "protocols": [ { "x402": {} }, { "mpp": { "method": "tempo", "intent": "charge", "currency": "USDC.e" } } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } }, "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "x-exa-queued": { "$ref": "#/components/headers/XExaQueued" }, "x-exa-queue-ms": { "$ref": "#/components/headers/XExaQueueMs" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/SearchStreamChunk" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "402": { "description": "Payment required. API-key requests receive the standard error envelope when the team is out of credits or a spending budget is exceeded. On x402-priced endpoints, requests without an API key receive an x402 payment challenge with tag `X402_PAYMENT_REQUIRED` that describes how to pay.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "$ref": "#/components/schemas/X402PaymentChallenge" } ] } } } }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "429": { "$ref": "#/components/responses/TooManyRequestsResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "x-codeSamples": [ { "lang": "bash", "source": "curl -X POST https://api.exa.ai/search \\\n -H \"x-api-key: $EXA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"query\": \"\",\n \"type\": \"auto\",\n \"contents\": {\n \"highlights\": true\n }\n}'" }, { "lang": "javascript", "source": "import Exa from \"exa-js\";\n\nconst exa = new Exa(process.env.EXA_API_KEY);\n\nconst result = await exa.search(\"\", {\n type: \"auto\",\n contents: { highlights: true },\n});" }, { "lang": "python", "source": "from exa_py import Exa\n\nexa = Exa(api_key=\"YOUR_API_KEY\")\n\nresult = exa.search(\n \"\",\n type=\"auto\",\n contents={\"highlights\": True},\n)" } ] } }, "/contents": { "post": { "operationId": "getContents", "summary": "Contents", "x-payment-info": { "price": { "mode": "dynamic", "currency": "USD", "min": "0.001", "max": "0.010" }, "protocols": [ { "x402": {} }, { "mpp": { "method": "tempo", "intent": "charge", "currency": "USDC.e" } } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentsRequest" } } } }, "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "x-exa-queued": { "$ref": "#/components/headers/XExaQueued" }, "x-exa-queue-ms": { "$ref": "#/components/headers/XExaQueueMs" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "402": { "description": "Payment required. API-key requests receive the standard error envelope when the team is out of credits or a spending budget is exceeded. On x402-priced endpoints, requests without an API key receive an x402 payment challenge with tag `X402_PAYMENT_REQUIRED` that describes how to pay.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "$ref": "#/components/schemas/X402PaymentChallenge" } ] } } } }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "429": { "$ref": "#/components/responses/TooManyRequestsResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "x-codeSamples": [ { "lang": "bash", "source": "curl -X POST https://api.exa.ai/contents \\\n -H \"x-api-key: $EXA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"urls\": [\n \"\"\n ],\n \"highlights\": true\n}'" }, { "lang": "javascript", "source": "import Exa from \"exa-js\";\n\nconst exa = new Exa(process.env.EXA_API_KEY);\n\nconst result = await exa.getContents([\"\"], {\n highlights: true,\n});" }, { "lang": "python", "source": "from exa_py import Exa\n\nexa = Exa(api_key=\"YOUR_API_KEY\")\n\nresult = exa.get_contents(\n [\"\"],\n highlights=True,\n)" } ] } }, "/answer": { "post": { "operationId": "answer", "summary": "Answer", "description": "Performs a search based on the query and generates either a direct answer or a detailed summary with citations, depending on the query type.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerRequest" } } } }, "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "x-exa-queued": { "$ref": "#/components/headers/XExaQueued" }, "x-exa-queue-ms": { "$ref": "#/components/headers/XExaQueueMs" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerResponse" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/AnswerStreamChunk" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "402": { "$ref": "#/components/responses/PaymentRequiredResponse" }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "429": { "$ref": "#/components/responses/TooManyRequestsResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "x-codeSamples": [ { "lang": "bash", "source": "curl -X POST https://api.exa.ai/answer \\\n -H \"x-api-key: $EXA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"query\":\"\"}'" }, { "lang": "javascript", "source": "import Exa from \"exa-js\";\n\nconst exa = new Exa(process.env.EXA_API_KEY);\n\nconst result = await exa.answer(\"\");" }, { "lang": "python", "source": "from exa_py import Exa\n\nexa = Exa(api_key=\"YOUR_API_KEY\")\n\nresult = exa.answer(\"\")" } ] } }, "/findSimilar": { "post": { "operationId": "findSimilar", "summary": "Find similar links", "description": "Find links similar to the provided URL and optionally retrieve their contents. Deprecated: prefer `/search` with a query describing the source.", "x-exa-lifecycle": "deprecated", "deprecated": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindSimilarRequest" } } } }, "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "Deprecation": { "description": "Signals that this operation is deprecated.", "schema": { "type": "string" } }, "x-exa-queued": { "$ref": "#/components/headers/XExaQueued" }, "x-exa-queue-ms": { "$ref": "#/components/headers/XExaQueueMs" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindSimilarResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "402": { "$ref": "#/components/responses/PaymentRequiredResponse" }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "429": { "$ref": "#/components/responses/TooManyRequestsResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } } } }, "/monitors": { "post": { "operationId": "createMonitor", "summary": "Create a monitor", "description": "Creates a Monitor that runs an Exa search on a schedule and sends new results to your webhook. Each run searches recent content and drops results that match what earlier runs already returned, so your webhook receives only new developments.\n\nThe response includes a `webhookSecret` for verifying webhook signatures. It is returned only once, so store it securely.", "tags": ["Monitors"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSearchMonitorParameters" } } } }, "responses": { "201": { "description": "The created monitor with webhook secret", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSearchMonitorResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } }, "x-codeSamples": [ { "lang": "bash", "source": "curl -X POST https://api.exa.ai/monitors \\\n -H \"x-api-key: $EXA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ ... }'" }, { "lang": "javascript", "source": "import Exa from \"exa-js\";\n\nconst exa = new Exa(process.env.EXA_API_KEY);\n\nconst result = await exa.monitors.create({ ... });" }, { "lang": "python", "source": "from exa_py import Exa\n\nexa = Exa(api_key=\"YOUR_API_KEY\")\n\nresult = exa.monitors.create(...)" } ] }, "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", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSearchMonitorsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } }, "x-codeSamples": [ { "lang": "bash", "source": "curl -X GET https://api.exa.ai/monitors \\\n -H \"x-api-key: $EXA_API_KEY\"" }, { "lang": "javascript", "source": "import Exa from \"exa-js\";\n\nconst exa = new Exa(process.env.EXA_API_KEY);\n\nconst result = await exa.monitors.list();" }, { "lang": "python", "source": "from exa_py import Exa\n\nexa = Exa(api_key=\"YOUR_API_KEY\")\n\nresult = exa.monitors.list()" } ] } }, "/monitors/batch": { "post": { "operationId": "batchMonitors", "summary": "Batch action on monitors", "description": "Deletes, pauses, or unpauses the monitors that match the filter. Deletion is permanent. `dry_run` defaults to `true`, so a request only previews the affected monitors unless you set it to `false`. Repeat the request until `has_more` is `false` to process all matches.", "tags": ["Monitors"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchMonitorsRequest" } } } }, "responses": { "200": { "description": "Batch action result", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchMonitorsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/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", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchMonitor" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } }, "x-codeSamples": [ { "lang": "bash", "source": "curl -X GET https://api.exa.ai/monitors/ \\\n -H \"x-api-key: $EXA_API_KEY\"" }, { "lang": "javascript", "source": "import Exa from \"exa-js\";\n\nconst exa = new Exa(process.env.EXA_API_KEY);\n\nconst result = await exa.monitors.get(\"\");" }, { "lang": "python", "source": "from exa_py import Exa\n\nexa = Exa(api_key=\"YOUR_API_KEY\")\n\nresult = exa.monitors.get(\"\")" } ] }, "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", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchMonitor" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } }, "x-codeSamples": [ { "lang": "bash", "source": "curl -X PATCH https://api.exa.ai/monitors/ \\\n -H \"x-api-key: $EXA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ ... }'" }, { "lang": "javascript", "source": "import Exa from \"exa-js\";\n\nconst exa = new Exa(process.env.EXA_API_KEY);\n\nconst result = await exa.monitors.update(\"\", { ... });" }, { "lang": "python", "source": "from exa_py import Exa\n\nexa = Exa(api_key=\"YOUR_API_KEY\")\n\nresult = exa.monitors.update(\"\", ...)" } ] }, "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", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchMonitor" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } }, "x-codeSamples": [ { "lang": "bash", "source": "curl -X DELETE https://api.exa.ai/monitors/ \\\n -H \"x-api-key: $EXA_API_KEY\"" }, { "lang": "javascript", "source": "import Exa from \"exa-js\";\n\nconst exa = new Exa(process.env.EXA_API_KEY);\n\nconst result = await exa.monitors.delete(\"\");" }, { "lang": "python", "source": "from exa_py import Exa\n\nexa = Exa(api_key=\"YOUR_API_KEY\")\n\nresult = exa.monitors.delete(\"\")" } ] } }, "/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", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerSearchMonitorResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } }, "x-codeSamples": [ { "lang": "bash", "source": "curl -X POST https://api.exa.ai/monitors//trigger \\\n -H \"x-api-key: $EXA_API_KEY\"" }, { "lang": "javascript", "source": "import Exa from \"exa-js\";\n\nconst exa = new Exa(process.env.EXA_API_KEY);\n\nconst result = await exa.monitors.trigger(\"\");" }, { "lang": "python", "source": "from exa_py import Exa\n\nexa = Exa(api_key=\"YOUR_API_KEY\")\n\nresult = exa.monitors.trigger(\"\")" } ] } }, "/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", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSearchMonitorRunsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } }, "x-codeSamples": [ { "lang": "bash", "source": "curl -X GET https://api.exa.ai/monitors//runs \\\n -H \"x-api-key: $EXA_API_KEY\"" }, { "lang": "javascript", "source": "import Exa from \"exa-js\";\n\nconst exa = new Exa(process.env.EXA_API_KEY);\n\nconst result = await exa.monitors.runs.list(\"\");" }, { "lang": "python", "source": "from exa_py import Exa\n\nexa = Exa(api_key=\"YOUR_API_KEY\")\n\nresult = exa.monitors.runs.list(\"\")" } ] } }, "/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", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchMonitorRun" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } }, "x-codeSamples": [ { "lang": "bash", "source": "curl -X GET https://api.exa.ai/monitors//runs/ \\\n -H \"x-api-key: $EXA_API_KEY\"" }, { "lang": "javascript", "source": "import Exa from \"exa-js\";\n\nconst exa = new Exa(process.env.EXA_API_KEY);\n\nconst result = await exa.monitors.runs.get(\"\", \"\");" }, { "lang": "python", "source": "from exa_py import Exa\n\nexa = Exa(api_key=\"YOUR_API_KEY\")\n\nresult = exa.monitors.runs.get(\"\", \"\")" } ] } }, "/agent/runs": { "post": { "operationId": "createAgentRun", "summary": "Create a run", "description": "Create an asynchronous Agent run. By default, the API returns the run object immediately. Set `Accept: text/event-stream` to stream run lifecycle events until the run reaches a terminal status.", "tags": ["Agent"], "parameters": [ { "$ref": "#/components/parameters/AcceptHeader" }, { "$ref": "#/components/parameters/ExaBetaHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgentRunRequest" } } } }, "responses": { "200": { "description": "Agent run created", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRun" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/AgentRunEvent" } } } }, "400": { "description": "Invalid request.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "401": { "description": "Team context or authentication was not found.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "429": { "description": "Agent run concurrency limit reached.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "500": { "description": "Server error or run timeout.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } } }, "x-codeSamples": [ { "lang": "bash", "source": "curl -X POST https://api.exa.ai/agent/runs \\\n -H \"x-api-key: $EXA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ ... }'" }, { "lang": "javascript", "source": "import Exa from \"exa-js\";\n\nconst exa = new Exa(process.env.EXA_API_KEY);\n\nconst result = await exa.agent.runs.create({ ... });" }, { "lang": "python", "source": "from exa_py import Exa\n\nexa = Exa(api_key=\"YOUR_API_KEY\")\n\nresult = exa.agent.runs.create(...)" } ] }, "get": { "operationId": "listAgentRuns", "summary": "List runs", "description": "List Agent runs for your team, ordered from newest to oldest.", "tags": ["Agent"], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of results per page", "default": 20 } }, { "in": "query", "name": "cursor", "schema": { "description": "Cursor for pagination. Use the `nextCursor` value from the previous run list response.", "$ref": "#/components/schemas/AgentRunId" } } ], "responses": { "200": { "description": "Paginated Agent runs", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRunList" } } } }, "400": { "description": "Invalid request.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "401": { "description": "Team context or authentication was not found.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "500": { "description": "Server error or run timeout.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } } }, "x-codeSamples": [ { "lang": "bash", "source": "curl -X GET https://api.exa.ai/agent/runs \\\n -H \"x-api-key: $EXA_API_KEY\"" }, { "lang": "javascript", "source": "import Exa from \"exa-js\";\n\nconst exa = new Exa(process.env.EXA_API_KEY);\n\nconst result = await exa.agent.runs.list();" }, { "lang": "python", "source": "from exa_py import Exa\n\nexa = Exa(api_key=\"YOUR_API_KEY\")\n\nresult = exa.agent.runs.list()" } ] } }, "/agent/runs/{id}": { "get": { "operationId": "getAgentRun", "summary": "Get a run", "description": "Retrieve a single Agent run by ID.", "tags": ["Agent"], "parameters": [ { "in": "path", "name": "id", "schema": { "description": "Agent run ID.", "$ref": "#/components/schemas/AgentRunId" }, "required": true, "description": "Agent run ID." } ], "responses": { "200": { "description": "Agent run", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRun" } } } }, "400": { "description": "Invalid request.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "401": { "description": "Team context or authentication was not found.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "404": { "description": "Run not found.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "429": { "description": "Agent run concurrency limit reached.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "500": { "description": "Server error or run timeout.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } } }, "x-codeSamples": [ { "lang": "bash", "source": "curl -X GET https://api.exa.ai/agent/runs/ \\\n -H \"x-api-key: $EXA_API_KEY\"" }, { "lang": "javascript", "source": "import Exa from \"exa-js\";\n\nconst exa = new Exa(process.env.EXA_API_KEY);\n\nconst result = await exa.agent.runs.get(\"\");" }, { "lang": "python", "source": "from exa_py import Exa\n\nexa = Exa(api_key=\"YOUR_API_KEY\")\n\nresult = exa.agent.runs.get(\"\")" } ] }, "delete": { "operationId": "deleteAgentRun", "summary": "Delete a run", "description": "Delete a stored Agent run.", "tags": ["Agent"], "parameters": [ { "in": "path", "name": "id", "schema": { "description": "Agent run ID.", "$ref": "#/components/schemas/AgentRunId" }, "required": true, "description": "Agent run ID." } ], "responses": { "200": { "description": "Agent run deleted", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAgentRunResponse" } } } }, "400": { "description": "Invalid request.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "401": { "description": "Team context or authentication was not found.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "404": { "description": "Run not found.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "429": { "description": "Agent run concurrency limit reached.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "500": { "description": "Server error or run timeout.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } } }, "x-codeSamples": [ { "lang": "bash", "source": "curl -X DELETE https://api.exa.ai/agent/runs/ \\\n -H \"x-api-key: $EXA_API_KEY\"" }, { "lang": "javascript", "source": "import Exa from \"exa-js\";\n\nconst exa = new Exa(process.env.EXA_API_KEY);\n\nconst result = await exa.agent.runs.delete(\"\");" }, { "lang": "python", "source": "from exa_py import Exa\n\nexa = Exa(api_key=\"YOUR_API_KEY\")\n\nresult = exa.agent.runs.delete(\"\")" } ] } }, "/agent/runs/{id}/cancel": { "post": { "operationId": "cancelAgentRun", "summary": "Cancel a run", "description": "Cancel a queued or running Agent run immediately without returning any results. You are billed for usage accrued before cancellation. If the run has already reached a terminal status, the API returns the existing run.", "tags": ["Agent"], "parameters": [ { "in": "path", "name": "id", "schema": { "description": "Agent run ID.", "$ref": "#/components/schemas/AgentRunId" }, "required": true, "description": "Agent run ID." } ], "responses": { "200": { "description": "Agent run", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRun" } } } }, "400": { "description": "Invalid request.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "401": { "description": "Team context or authentication was not found.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "404": { "description": "Run not found.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "429": { "description": "Agent run concurrency limit reached.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "500": { "description": "Server error or run timeout.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } } }, "x-codeSamples": [ { "lang": "bash", "source": "curl -X POST https://api.exa.ai/agent/runs//cancel \\\n -H \"x-api-key: $EXA_API_KEY\"" }, { "lang": "javascript", "source": "import Exa from \"exa-js\";\n\nconst exa = new Exa(process.env.EXA_API_KEY);\n\nconst result = await exa.agent.runs.cancel(\"\");" }, { "lang": "python", "source": "from exa_py import Exa\n\nexa = Exa(api_key=\"YOUR_API_KEY\")\n\nresult = exa.agent.runs.cancel(\"\")" } ] } }, "/agent/runs/{id}/stop": { "post": { "operationId": "stopAgentRun", "summary": "Stop a run", "description": "Complete a running Agent run early, returning the results gathered so far. You are billed for usage accrued before the stop. Currently supported only for `ultra` effort runs. If the run has already reached a terminal status, the API returns the existing run.", "tags": ["Agent"], "parameters": [ { "in": "path", "name": "id", "schema": { "description": "Agent run ID.", "$ref": "#/components/schemas/AgentRunId" }, "required": true, "description": "Agent run ID." } ], "responses": { "200": { "description": "Agent run", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRun" } } } }, "400": { "description": "Invalid request.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "401": { "description": "Team context or authentication was not found.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "404": { "description": "Run not found.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "429": { "description": "Agent run concurrency limit reached.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "500": { "description": "Server error or run timeout.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } } }, "x-codeSamples": [ { "lang": "bash", "source": "curl -X POST https://api.exa.ai/agent/runs//stop \\\n -H \"x-api-key: $EXA_API_KEY\"" }, { "lang": "javascript", "source": "import Exa from \"exa-js\";\n\nconst exa = new Exa(process.env.EXA_API_KEY);\n\nconst result = await exa.beta.agent.runs.stop(\"\");" }, { "lang": "python", "source": "from exa_py import Exa\n\nexa = Exa(api_key=\"YOUR_API_KEY\")\n\nresult = exa.beta.agent.runs.stop(\"\")" } ] } }, "/agent/runs/{id}/events": { "get": { "operationId": "listAgentRunEvents", "summary": "List run events", "description": "List stored events for an Agent run. Set `Accept: text/event-stream` to replay stored events as server-sent events. Use `cursor` for JSON pagination or `Last-Event-ID` for SSE replay.", "tags": ["Agent"], "parameters": [ { "in": "path", "name": "id", "schema": { "description": "Agent run ID.", "$ref": "#/components/schemas/AgentRunId" }, "required": true, "description": "Agent run ID." }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of results per page", "default": 20 } }, { "in": "query", "name": "cursor", "schema": { "type": "string", "description": "Cursor for pagination. Use the `nextCursor` value from the previous event list response." } }, { "$ref": "#/components/parameters/AcceptHeader" }, { "$ref": "#/components/parameters/LastEventId" } ], "responses": { "200": { "description": "Agent run events", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRunEventList" } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/AgentRunEvent" } } } }, "400": { "description": "Invalid request.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "401": { "description": "Team context or authentication was not found.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "404": { "description": "Run not found.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "429": { "description": "Agent run concurrency limit reached.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } }, "500": { "description": "Server error or run timeout.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } } }, "x-codeSamples": [ { "lang": "bash", "source": "curl -X GET https://api.exa.ai/agent/runs//events \\\n -H \"x-api-key: $EXA_API_KEY\"" }, { "lang": "javascript", "source": "import Exa from \"exa-js\";\n\nconst exa = new Exa(process.env.EXA_API_KEY);\n\nconst result = await exa.agent.runs.events.list(\"\");" }, { "lang": "python", "source": "from exa_py import Exa\n\nexa = Exa(api_key=\"YOUR_API_KEY\")\n\nresult = exa.agent.runs.events.list(\"\")" } ] } }, "/batches": { "post": { "operationId": "createBatch", "summary": "Create a batch", "description": "Create a batch of requests to run asynchronously. Each request is dispatched to its target route and results are made available for download when the batch completes.", "tags": ["Batches"], "x-exa-lifecycle": "beta", "x-exa-beta-flag": "batches-2026-06-06", "parameters": [ { "$ref": "#/components/parameters/BatchesBetaHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBatchRequest" } } } }, "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } }, "get": { "operationId": "listBatches", "summary": "List batches", "description": "List batches for your team, ordered from newest to oldest.", "tags": ["Batches"], "x-exa-lifecycle": "beta", "x-exa-beta-flag": "batches-2026-06-06", "parameters": [ { "in": "query", "name": "cursor", "schema": { "type": "string", "description": "Pagination cursor from a previous response" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "description": "Maximum number of batches to return per page. Defaults to 100 when omitted; there is no upper bound.", "default": 100 } }, { "in": "query", "name": "status", "schema": { "type": "string", "const": "completed", "description": "Return only completed batches, ordered by expiry. Send it on every page request when paginating." } }, { "$ref": "#/components/parameters/BatchesBetaHeader" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchList" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/batches/{id}": { "get": { "operationId": "getBatch", "summary": "Get a batch", "description": "Retrieve a single batch by ID.", "tags": ["Batches"], "x-exa-lifecycle": "beta", "x-exa-beta-flag": "batches-2026-06-06", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1, "description": "Batch ID." }, "required": true, "description": "Batch ID." }, { "$ref": "#/components/parameters/BatchesBetaHeader" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } }, "delete": { "operationId": "deleteBatch", "summary": "Delete a batch", "description": "Soft-delete a batch in a terminal status.", "tags": ["Batches"], "x-exa-lifecycle": "beta", "x-exa-beta-flag": "batches-2026-06-06", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1, "description": "Batch ID." }, "required": true, "description": "Batch ID." }, { "$ref": "#/components/parameters/BatchesBetaHeader" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedBatch" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/batches/{id}/cancel": { "post": { "operationId": "cancelBatch", "summary": "Cancel a batch", "description": "Request cancellation of a batch. The batch stops scheduling new requests and drains in-flight work before settling to `cancelled`. Cancelling a batch that is already `cancelling` or `cancelled` is idempotent and returns the batch unchanged. A batch that has already reached a terminal status (`completed` or `expired`) cannot be cancelled and the request fails with a 409.", "tags": ["Batches"], "x-exa-lifecycle": "beta", "x-exa-beta-flag": "batches-2026-06-06", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string", "minLength": 1, "description": "Batch ID." }, "required": true, "description": "Batch ID." }, { "$ref": "#/components/parameters/BatchesBetaHeader" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Batch" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/v0/teams/me": { "get": { "operationId": "teams-me-get", "summary": "Get team info", "description": "Returns information about the authenticated team, including current concurrency usage and limits.", "tags": ["Teams"], "servers": [ { "url": "https://api.exa.ai/websets" } ], "responses": { "200": { "description": "Team information retrieved successfully", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsetsTeamInfo" } } } } } } }, "/v0/websets": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "post": { "operationId": "websets-create", "summary": "Create a Webset", "description": "Creates a new Webset with optional search, import, and enrichment configurations. The Webset will automatically begin processing once created.\n\nYou can specify an `externalId` to reference the Webset with your own identifiers for easier integration.", "tags": ["Websets"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebsetParameters" } } } }, "responses": { "201": { "description": "Webset created", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webset" } } } }, "409": { "description": "Webset with this externalId already exists", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } } } } }, "get": { "operationId": "websets-list", "summary": "List all Websets", "description": "Returns a list of Websets.\n\nYou can paginate through the results using the `cursor` parameter.\n\nYou can filter results using the `search` parameter to find Websets by ID, external ID, or title.", "tags": ["Websets"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "query", "name": "cursor", "schema": { "minLength": 1, "type": "string" }, "required": false, "description": "The cursor to paginate through the results" }, { "in": "query", "name": "limit", "schema": { "default": 25, "minimum": 1, "maximum": 100, "type": "number" }, "required": false, "description": "The number of Websets to return" }, { "in": "query", "name": "search", "schema": { "minLength": 2, "maxLength": 50, "type": "string" }, "required": false, "description": "Search term to filter Websets by ID, external ID, or title" } ], "responses": { "200": { "description": "List of Websets", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebsetsResponse" } } } } } } }, "/v0/websets/{id}": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "get": { "operationId": "websets-get", "summary": "Get a Webset", "description": "Returns a Webset by `id` or `externalId`, including its status, searches, imports, enrichments, and monitors.\n\nPass `expand=items` to include up to the first 100 items in the response.", "tags": ["Websets"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "The id or externalId of the Webset.", "required": true }, { "in": "query", "name": "expand", "schema": { "items": { "enum": ["items"], "type": "string" }, "type": "array" }, "required": false, "description": "Expand the response with the specified resources" } ], "responses": { "200": { "description": "Webset", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetWebsetResponse" } } } }, "404": { "description": "Webset not found", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } } } } }, "post": { "operationId": "websets-update", "summary": "Update a Webset", "description": "Updates the `title` or `metadata` of a Webset. Searches, imports, and enrichments are managed through their own endpoints.", "tags": ["Websets"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "The id or externalId of the Webset", "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebsetRequest" } } } }, "responses": { "200": { "description": "Webset updated", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webset" } } } }, "404": { "description": "Webset not found", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } } } } }, "delete": { "operationId": "websets-delete", "summary": "Delete a Webset", "description": "Deletes a Webset.\n\nOnce deleted, the Webset and all its Items will no longer be available.", "tags": ["Websets"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "The id or externalId of the Webset", "required": true } ], "responses": { "200": { "description": "Webset deleted", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webset" } } } }, "404": { "description": "Webset not found", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } } } } } }, "/v0/websets/{id}/cancel": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "post": { "operationId": "websets-cancel", "summary": "Cancel a running Webset", "description": "Cancels all operations being performed on a Webset.\n\nAny enrichment or search will be stopped and the Webset will be marked as `idle`.", "tags": ["Websets"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "The id or externalId of the Webset", "required": true } ], "responses": { "200": { "description": "Webset canceled", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webset" } } } } } } }, "/v0/websets/{webset}/searches": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "post": { "operationId": "websets-searches-create", "summary": "Create a Search", "description": "Creates a new Search for the Webset.\n\nThe default behavior is to reuse the previous Search results and evaluate them against the new criteria.", "tags": ["Searches"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "webset", "schema": { "type": "string" }, "description": "The id of the Webset", "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebsetSearchParameters" } } } }, "responses": { "200": { "description": "Webset Search created", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsetSearch" } } } } } } }, "/v0/websets/{webset}/searches/{id}": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "get": { "operationId": "websets-searches-get", "summary": "Get a Search", "description": "Gets a Search by id", "tags": ["Searches"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "webset", "schema": { "type": "string" }, "description": "The id of the Webset", "required": true }, { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "The id of the Search", "required": true } ], "responses": { "200": { "description": "Search retrieved", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsetSearch" } } } } } } }, "/v0/websets/{webset}/searches/{id}/cancel": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "post": { "operationId": "websets-searches-cancel", "summary": "Cancel a running Search", "description": "Cancels a currently running Search.\n\nYou can cancel all searches at once by using the `websets/:webset/cancel` endpoint.", "tags": ["Searches"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "webset", "schema": { "type": "string" }, "description": "The id of the Webset", "required": true }, { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "The id of the Search", "required": true } ], "responses": { "200": { "description": "Search canceled", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsetSearch" } } } } } } }, "/v0/websets/{webset}/enrichments": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "post": { "operationId": "websets-enrichments-create", "summary": "Create an Enrichment", "description": "Create an Enrichment for a Webset.", "tags": ["Enrichments"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "webset", "schema": { "type": "string" }, "description": "The id or externalId of the Webset", "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEnrichmentParameters" } } } }, "responses": { "200": { "description": "Enrichment created", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsetEnrichment" } } } } } } }, "/v0/websets/{webset}/enrichments/{id}": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "patch": { "operationId": "websets-enrichments-update", "summary": "Update an Enrichment", "description": "Update an Enrichment configuration for a Webset.", "tags": ["Enrichments"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "webset", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "id", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEnrichmentParameters" } } } }, "responses": { "200": { "description": "", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } } } } }, "get": { "operationId": "websets-enrichments-get", "summary": "Get an Enrichment", "description": "Returns an Enrichment configured on a Webset, including its status, description, format, and options.", "tags": ["Enrichments"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "webset", "schema": { "type": "string" }, "description": "The id or externalId of the Webset", "required": true }, { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "The id of the Enrichment", "required": true } ], "responses": { "200": { "description": "Enrichment", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsetEnrichment" } } } } } }, "delete": { "operationId": "websets-enrichments-delete", "summary": "Delete an Enrichment", "description": "When deleting an Enrichment, any running enrichments will be canceled and all existing `enrichment_result` generated by this Enrichment will no longer be available.", "tags": ["Enrichments"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "webset", "schema": { "type": "string" }, "description": "The id or externalId of the Webset", "required": true }, { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "The id of the Enrichment", "required": true } ], "responses": { "200": { "description": "Enrichment deleted", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsetEnrichment" } } } } } } }, "/v0/websets/{webset}/enrichments/{id}/cancel": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "post": { "operationId": "websets-enrichments-cancel", "summary": "Cancel a running Enrichment", "description": "All running enrichments will be canceled. You can not resume an Enrichment after it has been canceled.", "tags": ["Enrichments"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "webset", "schema": { "type": "string" }, "description": "The id or externalId of the Webset", "required": true }, { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "The id of the Enrichment", "required": true } ], "responses": { "200": { "description": "Enrichment cancelled", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsetEnrichment" } } } } } } }, "/v0/websets/{webset}/items/{id}": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "get": { "operationId": "websets-items-get", "summary": "Get an Item", "description": "Returns a Webset Item.", "tags": ["Items"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "webset", "schema": { "type": "string" }, "description": "The id or externalId of the Webset", "required": true }, { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "The id of the Webset item", "required": true } ], "responses": { "200": { "description": "Webset Item", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsetItem" } } } } } }, "delete": { "operationId": "websets-items-delete", "summary": "Delete an Item", "description": "Deletes an Item from the Webset.\n\nThis will cancel any enrichment process for it.", "tags": ["Items"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "webset", "schema": { "type": "string" }, "description": "The id or externalId of the Webset", "required": true }, { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "The id of the Webset item", "required": true } ], "responses": { "200": { "description": "Webset Item deleted", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsetItem" } } } } } } }, "/v0/websets/{webset}/items": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "get": { "operationId": "websets-items-list", "summary": "List all Items for a Webset", "description": "Returns a list of Webset Items.\n\nYou can paginate through the Items using the `cursor` parameter.", "tags": ["Items"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "webset", "schema": { "type": "string" }, "description": "The id or externalId of the Webset", "required": true }, { "in": "query", "name": "cursor", "schema": { "minLength": 1, "type": "string" }, "required": false, "description": "The cursor to paginate through the results" }, { "in": "query", "name": "limit", "schema": { "default": 20, "minimum": 1, "maximum": 100, "type": "integer" }, "required": false, "description": "The number of results to return" }, { "in": "query", "name": "sourceId", "schema": { "type": "string" }, "required": false, "description": "The id of the source" } ], "responses": { "200": { "description": "Webset Items", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebsetItemResponse" } } } } } } }, "/v0/websets/preview": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "post": { "operationId": "websets-preview", "summary": "Preview a webset", "description": "Returns how a search query will be interpreted before you create a Webset, including the detected entity, generated criteria, and suggested enrichments.", "tags": ["Websets Preview"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "query", "name": "search", "schema": { "type": "boolean" }, "required": false, "description": "Whether you want to search for a preview list of items or not" } ], "requestBody": { "required": true, "description": "Search parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewWebsetParameters" } } } }, "responses": { "200": { "description": "Preview of the webset", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewWebsetResponse" } } } }, "422": { "description": "Unable to detect entity or criteria from query", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } } } } } }, "/v0/monitors": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "post": { "operationId": "monitors-create", "summary": "Create a Monitor", "description": "To run a recurring Exa search and send new results to your webhook, use the [Monitors API](https://exa.ai/docs/reference/monitors/create-a-monitor). This endpoint creates a Monitor that searches for new Items for a Webset on a `cron` schedule in the given `timezone`.", "tags": ["Monitors"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMonitorParameters" } } } }, "responses": { "201": { "description": "Monitor created successfully", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Monitor" } } } } } }, "get": { "operationId": "monitors-list", "summary": "List Monitors", "description": "Lists all monitors for the Webset.", "tags": ["Monitors"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "query", "name": "cursor", "schema": { "minLength": 1, "type": "string" }, "required": false, "description": "The cursor to paginate through the results" }, { "in": "query", "name": "limit", "schema": { "default": 25, "minimum": 1, "maximum": 200, "type": "integer" }, "required": false, "description": "The number of results to return" }, { "in": "query", "name": "websetId", "schema": { "type": "string" }, "required": false, "description": "The id of the Webset to list monitors for" } ], "responses": { "200": { "description": "List of monitors", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMonitorsResponse" } } } } } } }, "/v0/monitors/{id}": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "get": { "operationId": "monitors-get", "summary": "Get Monitor", "description": "Gets a specific monitor.", "tags": ["Monitors"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "The id of the Monitor", "required": true } ], "responses": { "200": { "description": "Monitor details", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Monitor" } } } } } }, "patch": { "operationId": "monitors-update", "summary": "Update Monitor", "description": "Updates a monitor configuration.", "tags": ["Monitors"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "The id of the Monitor", "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMonitor" } } } }, "responses": { "200": { "description": "Monitor updated successfully", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Monitor" } } } } } }, "delete": { "operationId": "monitors-delete", "summary": "Delete Monitor", "description": "Deletes a monitor.", "tags": ["Monitors"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "The id of the Monitor", "required": true } ], "responses": { "200": { "description": "Monitor deleted successfully", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Monitor" } } } } } } }, "/v0/monitors/{monitor}/runs": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "get": { "operationId": "monitors-runs-list", "summary": "List Monitor Runs", "description": "Lists all runs for the Monitor.", "tags": ["Monitors Runs"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "monitor", "schema": { "type": "string" }, "description": "The id of the Monitor to list runs for", "required": true } ], "responses": { "200": { "description": "List of monitor runs", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMonitorRunsResponse" } } } } } } }, "/v0/monitors/{monitor}/runs/{id}": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "get": { "operationId": "monitors-runs-get", "summary": "Get Monitor Run", "description": "Gets a specific monitor run.", "tags": ["Monitors Runs"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "monitor", "schema": { "type": "string" }, "description": "The id of the Monitor to get the run for", "required": true }, { "in": "path", "name": "id", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Monitor run details", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorRun" } } } } } } }, "/v0/imports": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "post": { "operationId": "imports-create", "summary": "Create an Import", "description": "Creates an Import for your own data. Upload the file to the returned `uploadUrl` before `uploadValidUntil`, 1 hour after creation. Use an Import to enrich its records, to search within them with `scope`, or to leave them out of searches with `exclude`.", "tags": ["Imports"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateImportParameters" } } } }, "responses": { "201": { "description": "Import created successfully", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateImportResponse" } } } } } }, "get": { "operationId": "imports-list", "summary": "List Imports", "description": "Lists all imports for the Webset.", "tags": ["Imports"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "query", "name": "cursor", "schema": { "minLength": 1, "type": "string" }, "required": false, "description": "The cursor to paginate through the results" }, { "in": "query", "name": "limit", "schema": { "default": 25, "minimum": 1, "maximum": 200, "type": "integer" }, "required": false, "description": "The number of results to return" } ], "responses": { "200": { "description": "List of imports", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListImportsResponse" } } } } } } }, "/v0/imports/{id}": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "get": { "operationId": "imports-get", "summary": "Get Import", "description": "Gets a specific import.", "tags": ["Imports"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "The id of the Import", "required": true } ], "responses": { "200": { "description": "Import details", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Import" } } } } } }, "patch": { "operationId": "imports-update", "summary": "Update Import", "description": "Updates a import configuration.", "tags": ["Imports"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "The id of the Import", "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateImport" } } } }, "responses": { "200": { "description": "Import updated successfully", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Import" } } } } } }, "delete": { "operationId": "imports-delete", "summary": "Delete Import", "description": "Deletes a import.", "tags": ["Imports"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "The id of the Import", "required": true } ], "responses": { "200": { "description": "Import deleted successfully", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Import" } } } } } } }, "/v0/webhooks": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "post": { "operationId": "webhooks-create", "summary": "Create a Webhook", "description": "Creates a Webhook that delivers the selected events to your URL as they occur.\n\nThe response includes the signing `secret` used to verify deliveries; it is only returned on creation.", "tags": ["Webhooks"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookParameters" } } } }, "responses": { "200": { "description": "Webhook", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } } } }, "get": { "operationId": "webhooks-list", "summary": "List webhooks", "description": "Returns the active Webhooks for your team.\n\nYou can paginate through the results using the `cursor` parameter.", "tags": ["Webhooks"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "query", "name": "cursor", "schema": { "minLength": 1, "type": "string" }, "required": false, "description": "The cursor to paginate through the results" }, { "in": "query", "name": "limit", "schema": { "default": 25, "minimum": 1, "maximum": 200, "type": "integer" }, "required": false, "description": "The number of results to return" } ], "responses": { "200": { "description": "List of webhooks", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebhooksResponse" } } } } } } }, "/v0/webhooks/{id}": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "get": { "operationId": "webhooks-get", "summary": "Get a Webhook", "description": "Returns a Webhook by id, including its status, subscribed events, target URL, and metadata. The signing `secret` is not returned.", "tags": ["Webhooks"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "The id of the webhook", "required": true } ], "responses": { "200": { "description": "Webhook", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "404": { "description": "Webhook not found", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } } } } }, "patch": { "operationId": "webhooks-update", "summary": "Update a Webhook", "description": "Updates the target URL, subscribed events, or metadata of a Webhook. Omitted fields are left unchanged.", "tags": ["Webhooks"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "The id of the webhook", "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookParameters" } } } }, "responses": { "200": { "description": "Webhook", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "404": { "description": "Webhook not found", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } } } } }, "delete": { "operationId": "webhooks-delete", "summary": "Delete a Webhook", "description": "Deletes a Webhook. Its status becomes `inactive`, which stops future webhook deliveries to its URL.", "tags": ["Webhooks"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "The id of the webhook", "required": true } ], "responses": { "200": { "description": "Webhook", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "404": { "description": "Webhook not found", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } } } } } }, "/v0/webhooks/{id}/attempts": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "get": { "operationId": "webhooks-attempts-list", "summary": "List webhook attempts", "description": "List all attempts made by a Webhook ordered in descending order.", "tags": ["Webhooks Attempts"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "The ID of the webhook", "required": true }, { "in": "query", "name": "cursor", "schema": { "minLength": 1, "type": "string" }, "required": false, "description": "The cursor to paginate through the results" }, { "in": "query", "name": "limit", "schema": { "default": 25, "minimum": 1, "maximum": 200, "type": "integer" }, "required": false, "description": "The number of results to return" }, { "in": "query", "name": "eventType", "schema": { "$ref": "#/components/schemas/EventType" }, "required": false, "description": "The type of event to filter by" }, { "in": "query", "name": "successful", "schema": { "type": "boolean" }, "required": false, "description": "Filter attempts by their success status" } ], "responses": { "200": { "description": "List of webhook attempts", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebhookAttemptsResponse" } } } } } } }, "/v0/events": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "get": { "operationId": "events-list", "summary": "List all Events", "description": "List all events that have occurred in the system.\n\nYou can paginate through the results using the `cursor` parameter.", "tags": ["Events"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "query", "name": "cursor", "schema": { "minLength": 1, "type": "string" }, "required": false, "description": "The cursor to paginate through the results" }, { "in": "query", "name": "limit", "schema": { "default": 25, "minimum": 1, "maximum": 200, "type": "integer" }, "required": false, "description": "The number of results to return" }, { "in": "query", "name": "types", "schema": { "items": { "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" ], "type": "string" }, "type": "array" }, "required": false, "description": "The types of events to filter by" }, { "in": "query", "name": "createdBefore", "schema": { "format": "date-time", "type": "string" }, "required": false, "description": "Filter events created before or at this timestamp (inclusive). Must be a valid ISO 8601 datetime string. All times are in UTC." }, { "in": "query", "name": "createdAfter", "schema": { "format": "date-time", "type": "string" }, "required": false, "description": "Filter events created after or at this timestamp (inclusive). Must be a valid ISO 8601 datetime string. All times are in UTC." } ], "responses": { "200": { "description": "List of events", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEventsResponse" } } } } } } }, "/v0/events/{id}": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "get": { "operationId": "events-get", "summary": "Get an Event", "description": "Get a single Event by id.\n\nYou can subscribe to Events by creating a Webhook.", "tags": ["Events"], "security": [ { "apiKey": [] }, { "bearer": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "The id of the event", "required": true } ], "responses": { "200": { "description": "", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "404": { "description": "Event not found", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "required": true } } } } } } }, "components": { "schemas": { "SearchRequest": { "type": "object", "properties": { "includeDomains": { "anyOf": [ { "maxItems": 1200, "type": "array", "items": { "type": "string" }, "description": "List of domains or domain paths to include in the search. Each entry can be a hostname (for example, `example.com`), a hostname with a path prefix (for example, `example.com/docs`), or a wildcard subdomain (for example, `*.example.com`). If specified, results will only come from the matching domains or paths. Use this parameter for domain or path filtering instead of adding a `site:` operator to the query." }, { "type": "null" } ] }, "excludeDomains": { "anyOf": [ { "maxItems": 1200, "type": "array", "items": { "type": "string" }, "description": "List of domains or domain paths to exclude from search results. Each entry can be a hostname (for example, `example.com`), a hostname with a path prefix (for example, `example.com/docs`), or a wildcard subdomain (for example, `*.example.com`). If specified, no results will be returned from the matching domains or paths. Use this parameter for domain or path filtering instead of adding a `site:` operator to the query." }, { "type": "null" } ] }, "startPublishedDate": { "anyOf": [ { "type": "string", "description": "Only links with a published date after this will be returned. Must be specified in ISO 8601 format.", "format": "date-time" }, { "type": "null" } ] }, "endPublishedDate": { "anyOf": [ { "type": "string", "description": "Only links with a published date before this will be returned. Must be specified in ISO 8601 format.", "format": "date-time" }, { "type": "null" } ] }, "numResults": { "anyOf": [ { "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 support@exa.ai to discuss higher limits.", "default": 10 }, { "type": "null" } ] }, "moderation": { "anyOf": [ { "type": "boolean", "description": "Enable content moderation to filter unsafe content from search results.", "default": false }, { "type": "null" } ] }, "contents": { "anyOf": [ { "description": "Content options for text, highlights, summary, extras, and freshness controls.", "$ref": "#/components/schemas/ContentsOptions" }, { "type": "null" } ] }, "query": { "type": "string", "minLength": 1, "description": "The query string for the search." }, "additionalQueries": { "anyOf": [ { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "string" }, "description": "Additional query variations for deep-search variants. Only works with a deep-search type. When provided, these queries are used alongside the main query for broader results." }, { "type": "null" } ] }, "type": { "anyOf": [ { "type": "string", "const": "auto", "description": "The default. A balanced mode that optimizes for both quality and speed and is recommended for most applications.", "title": "auto" }, { "type": "string", "const": "lite", "description": "Low-cost, low-latency search for real-time and interactive experiences such as chat, voice agents, and autocomplete. Accepts only `query` (a single string), `objective`, `userIdentifier`, `metadata`, `category`, `numResults`, `contents.highlights`, `contents.text`, `contents.snapshotAsOf`, `userLocation`, `includeDomains`, `excludeDomains`, `startPublishedDate`, `endPublishedDate`, `moderation`, and `compliance`; a request that sets any other parameter is rejected. Lite serves content directly from Exa’s regularly refreshed search index, without fetching pages at query time. Freshness options that require live fetching are not supported.", "title": "lite" }, { "type": "string", "const": "deep-lite", "description": "Performs lightweight research with synthesized results and a consistent 4-second latency, lower than full deep search.", "title": "deep-lite" }, { "type": "string", "const": "deep", "description": "Conducts comprehensive multi-step research with synthesis.", "title": "deep" }, { "type": "string", "const": "instant", "description": "Legacy. Use `lite` instead. Runs a minimum-latency search that trades some search depth for speed. Unlike `lite`, it accepts every search parameter.", "x-exa-lifecycle": "legacy", "x-exa-replacement": "lite", "x-mint": { "post": ["Legacy"] }, "title": "instant" }, { "type": "string", "const": "fast", "description": "Legacy. Use `lite` instead. Runs a reduced-latency search for user-facing and interactive workflows. Unlike `lite`, it accepts every search parameter.", "x-exa-lifecycle": "legacy", "x-exa-replacement": "lite", "x-mint": { "post": ["Legacy"] }, "title": "fast" }, { "type": "string", "const": "deep-reasoning", "description": "Legacy. Use `deep` instead. Runs `deep` with stronger reasoning at each step, for complex analysis and decision-making tasks. For agentic, multi-step research, use the Agent API.", "x-exa-lifecycle": "legacy", "x-exa-replacement": "deep", "x-mint": { "post": ["Legacy"] }, "title": "deep-reasoning" }, { "type": "string", "title": "Other values" }, { "type": "null" } ], "description": "The search mode to use. Defaults to `auto`, a balanced mode recommended for most applications.\n\n- `auto`: The default. A balanced mode that optimizes for both quality and speed and is recommended for most applications.\n- `lite`: Low-cost, low-latency search for real-time and interactive experiences such as chat, voice agents, and autocomplete. Accepts only `query` (a single string), `objective`, `userIdentifier`, `metadata`, `category`, `numResults`, `contents.highlights`, `contents.text`, `contents.snapshotAsOf`, `userLocation`, `includeDomains`, `excludeDomains`, `startPublishedDate`, `endPublishedDate`, `moderation`, and `compliance`; a request that sets any other parameter is rejected. Lite serves content directly from Exa’s regularly refreshed search index, without fetching pages at query time. Freshness options that require live fetching are not supported.\n- `deep-lite`: Performs lightweight research with synthesized results and a consistent 4-second latency, lower than full deep search.\n- `deep`: Conducts comprehensive multi-step research with synthesis.\n- `instant`: Legacy. Use `lite` instead. Runs a minimum-latency search that trades some search depth for speed. Unlike `lite`, it accepts every search parameter.\n- `fast`: Legacy. Use `lite` instead. Runs a reduced-latency search for user-facing and interactive workflows. Unlike `lite`, it accepts every search parameter.\n- `deep-reasoning`: Legacy. Use `deep` instead. Runs `deep` with stronger reasoning at each step, for complex analysis and decision-making tasks. For agentic, multi-step research, use the Agent API.", "default": "auto", "x-exa-enum-open": true }, "category": { "anyOf": [ { "type": "string", "enum": [ "company", "publication", "news", "personal site", "financial report", "people" ], "description": "A data category to focus on. Other strings are accepted and used as category hints. `people` and `company` return higher-quality people profiles and company pages. `publication` returns scholarly publications such as research papers, preprints, and journal articles, with metadata like authors, venue, and citations. `company` and `people` do not support `startPublishedDate` or `endPublishedDate`, and `people` also does not support `excludeDomains`. Requests that set an unsupported filter return a 400 error." }, { "type": "null" } ] }, "userLocation": { "anyOf": [ { "description": "The end user's location, as a two-letter ISO 3166-1 country code (e.g. `US`) or an object with `country`, a `latitude` and `longitude` pair, or both. The country localizes results. Coordinates are used only for queries that name no place but depend on where the user is, such as \"coffee near me\". They do not set a country, so send `country` with them to localize results. Send only the precision your use case needs.", "oneOf": [ { "type": "string", "description": "The two-letter ISO 3166-1 country code of the user, e.g. `US`." }, { "type": "object", "properties": { "country": { "type": "string", "description": "The two-letter ISO 3166-1 country code of the user, e.g. `US`." } }, "required": ["country"], "additionalProperties": false, "description": "The user's country only. Equivalent to the string form." }, { "type": "object", "properties": { "country": { "type": "string", "description": "The two-letter ISO 3166-1 country code of the user, e.g. `US`." }, "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "The user's latitude in decimal degrees." }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "The user's longitude in decimal degrees." } }, "required": ["latitude", "longitude"], "additionalProperties": false, "description": "The user's coordinates, with an optional country." } ] }, { "type": "null" } ] }, "compliance": { "anyOf": [ { "type": "string", "enum": ["hipaa"], "description": "Enterprise-only compliance mode. Set to `hipaa` for HIPAA mode. Requires cache-only retrieval with supported parameters. See the HIPAA docs for details." }, { "type": "null" } ] }, "outputSchema": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/OutputSchemaText" }, { "$ref": "#/components/schemas/OutputSchemaObject" } ], "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 except `lite` and adds about 2 seconds of synthesis latency on top of the selected search type. Object schemas are limited to 10 properties in total (nested and array items properties count toward the limit) and 2 levels of nesting, and every array must define items.", "type": "object", "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/OutputSchemaText", "object": "#/components/schemas/OutputSchemaObject" } } }, { "type": "null" } ] }, "objective": { "anyOf": [ { "type": "string", "maxLength": 4096 }, { "type": "null" } ], "description": "The broader goal this search serves: the task the caller is working on, beyond the query itself. When exposing this field to an agent as a tool parameter, describe it as: \"Goal for this search turn; say which documents should rank first, which should be excluded, and what specific facts or figures to pull from them.\"" }, "userIdentifier": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ], "description": "An opaque ID your platform assigns to the end user this request is made for, such as a UUID. Lets Exa attribute usage to that end user rather than your whole team. Must not contain personal information such as an email address, phone number, username, or name. Hash such values before sending them. 1 to 64 characters: letters, digits, underscores, and hyphens. Retained even when your team has Zero Data Retention enabled. Does not affect results.", "example": "7f3a9c52-1d4e-4b8a-9e60-2c5d8a1f0b37" }, "systemPrompt": { "anyOf": [ { "type": "string", "description": "Additional instructions that guide generated output or agent behavior. Use this for source preferences, novelty constraints, duplication constraints, or other behavior guidance." }, { "type": "null" } ] }, "stream": { "anyOf": [ { "type": "boolean", "description": "Requests server-sent events for synthesized output streaming. Streaming is currently used only when outputSchema is provided; otherwise the endpoint returns the normal JSON search response.", "default": false }, { "type": "null" } ] }, "startCrawlDate": { "anyOf": [ { "type": "string", "format": "date-time", "description": "Deprecated. Ignored by the API. Setting it adds an `IGNORED_FIELD` warning to the response's `warnings`.", "x-exa-lifecycle": "deprecated", "deprecated": true }, { "type": "null" } ] }, "endCrawlDate": { "anyOf": [ { "type": "string", "format": "date-time", "description": "Deprecated. Ignored by the API. Setting it adds an `IGNORED_FIELD` warning to the response's `warnings`.", "x-exa-lifecycle": "deprecated", "deprecated": true }, { "type": "null" } ] }, "includeText": { "anyOf": [ { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 4096 } }, { "type": "null" } ], "description": "Deprecated. List of strings that must be present in the webpage text of results. Matching is approximate (word-level rather than exact phrase), so a multi-word entry can match pages where its words appear separately. Up to 50 strings, each up to 4096 characters.", "x-exa-lifecycle": "deprecated", "deprecated": true }, "excludeText": { "anyOf": [ { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 4096 } }, { "type": "null" } ], "description": "Deprecated. List of strings that must not be present in the webpage text of results. Matching is approximate (word-level rather than exact phrase). Up to 50 strings, each up to 4096 characters.", "x-exa-lifecycle": "deprecated", "deprecated": true }, "context": { "anyOf": [ { "description": "Deprecated. Use `highlights` or `text` instead. Returns page contents as a combined context string.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": ["highlights", "text"], "oneOf": [ { "type": "boolean", "description": "Deprecated. Use `highlights` or `text` instead. Returns page contents as a combined context string.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": ["highlights", "text"] }, { "type": "object", "properties": { "maxCharacters": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Maximum character limit for the context string." } }, "description": "Deprecated. Use `highlights` or `text` instead. Returns page contents as a combined context string.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": ["highlights", "text"] } ] }, { "type": "null" } ] } }, "required": ["query"] }, "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" } } ] }, "ContentsOptions": { "type": "object", "properties": { "text": { "anyOf": [ { "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": 1000000, "description": "Maximum character limit for the full page text. Useful for controlling response size and API costs." }, { "type": "null" } ] }, "includeHtmlTags": { "anyOf": [ { "type": "boolean", "description": "If true, include lightweight HTML tags in returned text instead of plain markdown-style text.", "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.", "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." }, { "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." }, { "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. Set `maxAgeHours: 0` to apply `includeHtmlTags`, `verbosity`, and section filters to freshly fetched content." } ] }, { "type": "null" } ] }, "highlights": { "anyOf": [ { "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." }, { "type": "null" } ] }, "verbosity": { "anyOf": [ { "type": "string", "enum": ["low", "medium", "high"], "description": "Preset highlight length: `low`, `medium`, and `high` allocate progressively larger token budgets for the returned highlights. With highlights.dynamic, the preset sets a single shared budget across the whole result set instead of a per-URL budget. Exact budgets are tuned by Exa and may change. Not compatible with maxCharacters or numSentences. Beta: requires the `Exa-Beta: dynamic-highlights-2026-08-28` request header; requests setting `verbosity` without it are rejected.", "x-exa-lifecycle": "beta", "x-exa-beta-flag": "dynamic-highlights-2026-08-28", "x-mint": { "post": ["Beta"] } }, { "type": "null" } ] }, "dynamic": { "anyOf": [ { "type": "boolean", "description": "Enable Dynamic Highlights (research preview): considers all results together and allocates a single shared context budget across the result set instead of a per-document budget. Not compatible with maxCharacters. Beta: requires the `Exa-Beta: dynamic-highlights-2026-08-28` request header; requests setting `dynamic` without it are rejected.", "x-exa-lifecycle": "beta", "x-exa-beta-flag": "dynamic-highlights-2026-08-28", "x-mint": { "post": ["Beta"] } }, { "type": "null" } ] }, "maxCharacters": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Maximum number of characters to return for highlights. Controls the total length of highlight text returned per URL. Not compatible with highlights.dynamic." }, { "type": "null" } ] }, "numSentences": { "anyOf": [ { "type": "integer", "minimum": 1, "description": "Deprecated. Use `maxCharacters` instead. 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.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": "maxCharacters" }, { "type": "null" } ] }, "highlightsPerUrl": { "anyOf": [ { "type": "integer", "minimum": 1, "description": "Deprecated. Currently ignored. Pass highlights: true for default highlights, or { query } to guide selection with your own query.", "x-exa-lifecycle": "deprecated", "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." } ] }, { "type": "null" } ] }, "summary": { "anyOf": [ { "type": "object", "properties": { "query": { "anyOf": [ { "type": "string", "description": "Custom query for the LLM-generated summary." }, { "type": "null" } ] }, "schema": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "description": "JSON schema for structured output from summary. See https://json-schema.org/overview/what-is-jsonschema for JSON Schema documentation." }, { "type": "null" } ] } }, "description": "Summary of the webpage." }, { "type": "null" } ] }, "extras": { "anyOf": [ { "type": "object", "properties": { "links": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Number of URLs to return from each webpage.", "default": 0 }, { "type": "null" } ] }, "imageLinks": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Number of images to return for each result.", "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, "default": 0, "description": "Deprecated. Number of rich links to return for each result.", "x-exa-lifecycle": "deprecated", "deprecated": true }, { "type": "null" } ] }, "codeBlocks": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "default": 0, "description": "Deprecated. Number of code blocks to return for each result.", "x-exa-lifecycle": "deprecated", "deprecated": true }, { "type": "null" } ] } }, "description": "Extra parameters to pass." }, { "type": "null" } ] }, "livecrawlTimeout": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 90000, "description": "The timeout for livecrawling in milliseconds.", "default": 10000 }, { "type": "null" } ] }, "maxAgeHours": { "anyOf": [ { "type": "integer", "minimum": -1, "maximum": 720, "description": "Maximum age of cached content, in hours, up to 720. Cached content younger than this is used, and older pages are fetched fresh. `0` always fetches fresh content and `-1` always uses the cache. When omitted, cached content is used when available and pages without it are fetched live." }, { "type": "null" } ] }, "snapshotAsOf": { "anyOf": [ { "description": "Return the newest stored version of each page as of this instant. Accepts an ISO 8601 date-time (`2026-01-15T00:00:00Z`) or a date-only value (`2026-01-15`), which is interpreted as midnight UTC. Historical requests are served from stored versions only and never fetch the live page.", "oneOf": [ { "type": "string", "description": "ISO 8601 date-time.", "format": "date-time" }, { "type": "string", "description": "ISO 8601 date (`YYYY-MM-DD`), interpreted as midnight UTC.", "format": "date" } ] }, { "type": "null" } ] }, "context": { "anyOf": [ { "description": "Deprecated. Use `highlights` or `text` instead. Returns page contents as a combined context string.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": ["highlights", "text"], "oneOf": [ { "type": "boolean", "description": "Deprecated. Use `highlights` or `text` instead. Returns page contents as a combined context string.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": ["highlights", "text"] }, { "type": "object", "properties": { "maxCharacters": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Maximum character limit for the context string." } }, "description": "Deprecated. Use `highlights` or `text` instead. Returns page contents as a combined context string.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": ["highlights", "text"] } ] }, { "type": "null" } ] }, "livecrawl": { "anyOf": [ { "type": "string", "enum": ["never", "always", "fallback", "preferred"], "description": "Deprecated. Use `maxAgeHours` instead. Does not guarantee freshly fetched content. Cannot be combined with `maxAgeHours`.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": "maxAgeHours" }, { "type": "null" } ] }, "crawledBeforeDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date-time", "description": "Deprecated. Use `snapshotAsOf` instead. Alias of snapshotAsOf with identical behavior.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": "snapshotAsOf" }, "subpages": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100, "default": 0, "description": "Deprecated. The number of subpages to crawl for each result. The actual number crawled may be limited by system constraints. To crawl subpages, send the result URLs to `/contents` with `subpages`.", "x-exa-lifecycle": "deprecated", "deprecated": true }, { "type": "null" } ] }, "subpageTarget": { "anyOf": [ { "description": "Deprecated. Term to find specific subpages of search results. Can be a single string or an array of strings. To target subpages, send the result URLs to `/contents` with `subpageTarget`.", "x-exa-lifecycle": "deprecated", "deprecated": true, "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "minItems": 0, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } } ] }, { "type": "null" } ] } } }, "OutputSchemaText": { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "description": { "type": "string" } }, "required": ["type"] }, "OutputSchemaObject": { "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" } }, "ContentsRequest": { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2048 }, "description": "Document IDs obtained from searches." }, "urls": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2048 }, "description": "URLs to crawl (backwards compatible with the `ids` parameter)." }, "compliance": { "anyOf": [ { "type": "string", "enum": ["hipaa"], "description": "Enterprise-only compliance mode. Set to `hipaa` for HIPAA mode. Requires cache-only retrieval with supported parameters. See the HIPAA docs for details." }, { "type": "null" } ] }, "userIdentifier": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ], "description": "An opaque ID your platform assigns to the end user this request is made for, such as a UUID. Lets Exa attribute usage to that end user rather than your whole team. Must not contain personal information such as an email address, phone number, username, or name. Hash such values before sending them. 1 to 64 characters: letters, digits, underscores, and hyphens. Retained even when your team has Zero Data Retention enabled. Does not affect results.", "example": "7f3a9c52-1d4e-4b8a-9e60-2c5d8a1f0b37" }, "text": { "anyOf": [ { "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": 5000000, "description": "Maximum character limit for the full page text. Useful for controlling response size and API costs. Defaults to 5,000,000." }, { "type": "null" } ] }, "includeHtmlTags": { "anyOf": [ { "type": "boolean", "description": "If true, include lightweight HTML tags in returned text instead of plain markdown-style text.", "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.", "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." }, { "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." }, { "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. Set `maxAgeHours: 0` to apply `includeHtmlTags`, `verbosity`, and section filters to freshly fetched content." } ] }, { "type": "null" } ] }, "highlights": { "anyOf": [ { "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." }, { "type": "null" } ] }, "verbosity": { "anyOf": [ { "type": "string", "enum": ["low", "medium", "high"], "description": "Preset highlight length: `low`, `medium`, and `high` allocate progressively larger token budgets for the returned highlights. With highlights.dynamic, the preset sets a single shared budget across the whole result set instead of a per-URL budget. Exact budgets are tuned by Exa and may change. Not compatible with maxCharacters or numSentences. Beta: requires the `Exa-Beta: dynamic-highlights-2026-08-28` request header; requests setting `verbosity` without it are rejected.", "x-exa-lifecycle": "beta", "x-exa-beta-flag": "dynamic-highlights-2026-08-28", "x-mint": { "post": ["Beta"] } }, { "type": "null" } ] }, "dynamic": { "anyOf": [ { "type": "boolean", "description": "Enable Dynamic Highlights (research preview): considers all results together and allocates a single shared context budget across the result set instead of a per-document budget. Not compatible with maxCharacters. Beta: requires the `Exa-Beta: dynamic-highlights-2026-08-28` request header; requests setting `dynamic` without it are rejected.", "x-exa-lifecycle": "beta", "x-exa-beta-flag": "dynamic-highlights-2026-08-28", "x-mint": { "post": ["Beta"] } }, { "type": "null" } ] }, "maxCharacters": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Maximum number of characters to return for highlights. Controls the total length of highlight text returned per URL. Not compatible with highlights.dynamic." }, { "type": "null" } ] }, "numSentences": { "anyOf": [ { "type": "integer", "minimum": 1, "description": "Deprecated. Use `maxCharacters` instead. 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.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": "maxCharacters" }, { "type": "null" } ] }, "highlightsPerUrl": { "anyOf": [ { "type": "integer", "minimum": 1, "description": "Deprecated. Currently ignored. Pass highlights: true for default highlights, or { query } to guide selection with your own query.", "x-exa-lifecycle": "deprecated", "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." } ] }, { "type": "null" } ] }, "summary": { "anyOf": [ { "type": "object", "properties": { "query": { "anyOf": [ { "type": "string", "description": "Custom query for the LLM-generated summary." }, { "type": "null" } ] }, "schema": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "description": "JSON schema for structured output from summary. See https://json-schema.org/overview/what-is-jsonschema for JSON Schema documentation." }, { "type": "null" } ] } }, "description": "Summary of the webpage." }, { "type": "null" } ] }, "extras": { "anyOf": [ { "type": "object", "properties": { "links": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Number of URLs to return from each webpage.", "default": 0 }, { "type": "null" } ] }, "imageLinks": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Number of images to return for each result.", "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." }, { "type": "null" } ] }, "livecrawlTimeout": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 90000, "description": "The timeout for livecrawling in milliseconds.", "default": 10000 }, { "type": "null" } ] }, "maxAgeHours": { "anyOf": [ { "type": "integer", "minimum": -1, "maximum": 720, "description": "Maximum age of cached content, in hours, up to 720. Cached content younger than this is used, and older pages are fetched fresh. `0` always fetches fresh content and `-1` always uses the cache. When omitted, cached content is used when available and pages without it are fetched live." }, { "type": "null" } ] }, "snapshotAsOf": { "anyOf": [ { "description": "Return the newest stored version of each page as of this instant. Accepts an ISO 8601 date-time (`2026-01-15T00:00:00Z`) or a date-only value (`2026-01-15`), which is interpreted as midnight UTC. Historical requests are served from stored versions only and never fetch the live page.", "oneOf": [ { "type": "string", "description": "ISO 8601 date-time.", "format": "date-time" }, { "type": "string", "description": "ISO 8601 date (`YYYY-MM-DD`), interpreted as midnight UTC.", "format": "date" } ] }, { "type": "null" } ] }, "subpages": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 100, "description": "The number of subpages to crawl. The actual number crawled may be limited by system constraints.", "default": 0 }, { "type": "null" } ] }, "subpageTarget": { "anyOf": [ { "description": "Term to find specific subpages of search results. Can be a single string or an array of strings.", "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "minItems": 0, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } } ] }, { "type": "null" } ] }, "context": { "anyOf": [ { "description": "Deprecated. Use `highlights` or `text` instead. Returns page contents as a combined context string.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": ["highlights", "text"], "oneOf": [ { "type": "boolean", "description": "Deprecated. Use `highlights` or `text` instead. Returns page contents as a combined context string.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": ["highlights", "text"] }, { "type": "object", "properties": { "maxCharacters": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Maximum character limit for the context string." } }, "description": "Deprecated. Use `highlights` or `text` instead. Returns page contents as a combined context string.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": ["highlights", "text"] } ] }, { "type": "null" } ] }, "livecrawl": { "anyOf": [ { "type": "string", "enum": ["never", "always", "fallback", "preferred"], "description": "Deprecated. Use `maxAgeHours` instead. Does not guarantee freshly fetched content. Cannot be combined with `maxAgeHours`.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": "maxAgeHours" }, { "type": "null" } ] }, "crawledBeforeDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "format": "date-time", "description": "Deprecated. Use `snapshotAsOf` instead. Alias of snapshotAsOf with identical behavior.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": "snapshotAsOf" } }, "description": "Provide either `ids` or `urls`, but not both.", "oneOf": [ { "required": ["ids"] }, { "required": ["urls"] } ] }, "AnswerRequest": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "Natural-language question or instructions for the request." }, "stream": { "type": "boolean", "description": "If true, the response is returned as a server-sent events (SSE) stream.", "default": false }, "text": { "type": "boolean", "title": "Simple text retrieval", "description": "If true, returns full page text with default settings. If false, disables text return.", "default": false }, "model": { "description": "The model used to generate the answer.", "default": "exa", "type": "string", "enum": ["exa", "exa-pro", "exa-research", "exa-fast"] }, "systemPrompt": { "type": "string", "description": "Additional instructions that guide generated output or agent behavior. Use this for source preferences, novelty constraints, duplication constraints, or other behavior guidance." }, "userLocation": { "anyOf": [ { "description": "The end user's location, as a two-letter ISO 3166-1 country code (e.g. `US`) or an object with `country`, a `latitude` and `longitude` pair, or both. The country localizes results. Coordinates are used only for queries that name no place but depend on where the user is, such as \"coffee near me\". They do not set a country, so send `country` with them to localize results. Send only the precision your use case needs.", "oneOf": [ { "type": "string", "description": "The two-letter ISO 3166-1 country code of the user, e.g. `US`." }, { "type": "object", "properties": { "country": { "type": "string", "description": "The two-letter ISO 3166-1 country code of the user, e.g. `US`." } }, "required": ["country"], "additionalProperties": false, "description": "The user's country only. Equivalent to the string form." }, { "type": "object", "properties": { "country": { "type": "string", "description": "The two-letter ISO 3166-1 country code of the user, e.g. `US`." }, "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "The user's latitude in decimal degrees." }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "The user's longitude in decimal degrees." } }, "required": ["latitude", "longitude"], "additionalProperties": false, "description": "The user's coordinates, with an optional country." } ] }, { "type": "null" } ] }, "outputSchema": { "type": "object", "properties": { "type": { "type": "string", "description": "The root schema type (typically \"object\")." }, "properties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "description": "An object where each key is a property name and each value is a JSON Schema describing that property (with `type`, `description`, etc)." }, "required": { "type": "array", "items": { "type": "string" }, "description": "List of required property names." }, "description": { "type": "string", "description": "A description of the schema." }, "additionalProperties": { "type": "boolean", "description": "Whether to allow properties not listed in `properties`.", "default": false } }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "description": "A [JSON Schema Draft 7](https://json-schema.org/draft-07) specification for the desired answer structure. When provided, the answer is returned as a structured object matching the schema instead of a plain string." }, "userIdentifier": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ], "description": "An opaque ID your platform assigns to the end user this request is made for, such as a UUID. Lets Exa attribute usage to that end user rather than your whole team. Must not contain personal information such as an email address, phone number, username, or name. Hash such values before sending them. 1 to 64 characters: letters, digits, underscores, and hyphens. Retained even when your team has Zero Data Retention enabled. Does not affect results.", "example": "7f3a9c52-1d4e-4b8a-9e60-2c5d8a1f0b37" } }, "required": ["query"] }, "FindSimilarRequest": { "type": "object", "properties": { "includeDomains": { "anyOf": [ { "maxItems": 1200, "type": "array", "items": { "type": "string" }, "description": "List of domains or domain paths to include in the search. Each entry can be a hostname (for example, `example.com`), a hostname with a path prefix (for example, `example.com/docs`), or a wildcard subdomain (for example, `*.example.com`). If specified, results will only come from the matching domains or paths. Use this parameter for domain or path filtering instead of adding a `site:` operator to the query." }, { "type": "null" } ] }, "excludeDomains": { "anyOf": [ { "maxItems": 1200, "type": "array", "items": { "type": "string" }, "description": "List of domains or domain paths to exclude from search results. Each entry can be a hostname (for example, `example.com`), a hostname with a path prefix (for example, `example.com/docs`), or a wildcard subdomain (for example, `*.example.com`). If specified, no results will be returned from the matching domains or paths. Use this parameter for domain or path filtering instead of adding a `site:` operator to the query." }, { "type": "null" } ] }, "startPublishedDate": { "anyOf": [ { "type": "string", "description": "Only links with a published date after this will be returned. Must be specified in ISO 8601 format.", "format": "date-time" }, { "type": "null" } ] }, "endPublishedDate": { "anyOf": [ { "type": "string", "description": "Only links with a published date before this will be returned. Must be specified in ISO 8601 format.", "format": "date-time" }, { "type": "null" } ] }, "numResults": { "anyOf": [ { "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 support@exa.ai to discuss higher limits.", "default": 10 }, { "type": "null" } ] }, "contents": { "anyOf": [ { "description": "Content options for text, highlights, summary, extras, and freshness controls.", "$ref": "#/components/schemas/ContentsOptions" }, { "type": "null" } ] }, "url": { "type": "string", "minLength": 3, "description": "The url for which you would like to find similar links." }, "category": { "anyOf": [ { "type": "string", "enum": [ "company", "publication", "news", "personal site", "financial report", "people" ], "description": "A data category to focus on. Other strings are accepted and used as category hints. `people` and `company` return higher-quality people profiles and company pages. `publication` returns scholarly publications such as research papers, preprints, and journal articles, with metadata like authors, venue, and citations. With `company` or `people`, domain, URL, published-date, and text filters are ignored." }, { "type": "null" } ] }, "excludeSourceDomain": { "anyOf": [ { "type": "boolean", "description": "If true, results from the same domain as the source url are excluded." }, { "type": "null" } ] }, "startCrawlDate": { "anyOf": [ { "type": "string", "format": "date-time", "description": "Deprecated. Ignored by the API.", "x-exa-lifecycle": "deprecated", "deprecated": true }, { "type": "null" } ] }, "endCrawlDate": { "anyOf": [ { "type": "string", "format": "date-time", "description": "Deprecated. Ignored by the API.", "x-exa-lifecycle": "deprecated", "deprecated": true }, { "type": "null" } ] }, "includeText": { "anyOf": [ { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 4096 } }, { "type": "null" } ], "description": "Deprecated. List of strings that must be present in the webpage text of results. Matching is approximate (word-level rather than exact phrase), so a multi-word entry can match pages where its words appear separately. Up to 50 strings, each up to 4096 characters. Ignored for the `company` and `people` categories.", "x-exa-lifecycle": "deprecated", "deprecated": true }, "excludeText": { "anyOf": [ { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 4096 } }, { "type": "null" } ], "description": "Deprecated. List of strings that must not be present in the webpage text of results. Matching is approximate (word-level rather than exact phrase). Up to 50 strings, each up to 4096 characters. Ignored for the `company` and `people` categories.", "x-exa-lifecycle": "deprecated", "deprecated": true } }, "required": ["url"] }, "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." }, "webhook": { "$ref": "#/components/schemas/SearchMonitorWebhook" } }, "required": ["search", "webhook"] }, "SearchMonitorSearch": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "The query string for the search." }, "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 support@exa.ai to discuss higher limits.", "default": 10 }, "includeDomains": { "description": "Restrict search results to these domains.", "type": "array", "items": { "type": "string" } }, "excludeDomains": { "description": "Exclude these domains from search results.", "type": "array", "items": { "type": "string" } }, "contents": { "$ref": "#/components/schemas/SearchMonitorContents" } }, "required": ["query"] }, "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": 1000000, "description": "Maximum character limit for the full page text. Useful for controlling response size and API costs." }, { "type": "null" } ] }, "includeHtmlTags": { "anyOf": [ { "type": "boolean", "description": "If true, include lightweight HTML tags in returned text instead of plain markdown-style text.", "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.", "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." }, { "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." }, { "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. Set `maxAgeHours: 0` to apply `includeHtmlTags`, `verbosity`, and section filters to freshly fetched content." } ] }, "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." }, { "type": "null" } ] }, "verbosity": { "anyOf": [ { "type": "string", "enum": ["low", "medium", "high"], "description": "Preset highlight length: `low`, `medium`, and `high` allocate progressively larger token budgets for the returned highlights. With highlights.dynamic, the preset sets a single shared budget across the whole result set instead of a per-URL budget. Exact budgets are tuned by Exa and may change. Not compatible with maxCharacters or numSentences. Beta: requires the `Exa-Beta: dynamic-highlights-2026-08-28` request header; requests setting `verbosity` without it are rejected.", "x-exa-lifecycle": "beta", "x-exa-beta-flag": "dynamic-highlights-2026-08-28", "x-mint": { "post": ["Beta"] } }, { "type": "null" } ] }, "dynamic": { "anyOf": [ { "type": "boolean", "description": "Enable Dynamic Highlights (research preview): considers all results together and allocates a single shared context budget across the result set instead of a per-document budget. Not compatible with maxCharacters. Beta: requires the `Exa-Beta: dynamic-highlights-2026-08-28` request header; requests setting `dynamic` without it are rejected.", "x-exa-lifecycle": "beta", "x-exa-beta-flag": "dynamic-highlights-2026-08-28", "x-mint": { "post": ["Beta"] } }, { "type": "null" } ] }, "maxCharacters": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Maximum number of characters to return for highlights. Controls the total length of highlight text returned per URL. Not compatible with highlights.dynamic." }, { "type": "null" } ] }, "numSentences": { "anyOf": [ { "type": "integer", "minimum": 1, "description": "Deprecated. Use `maxCharacters` instead. 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.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": "maxCharacters" }, { "type": "null" } ] }, "highlightsPerUrl": { "anyOf": [ { "type": "integer", "minimum": 1, "description": "Deprecated. Currently ignored. Pass highlights: true for default highlights, or { query } to guide selection with your own query.", "x-exa-lifecycle": "deprecated", "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`.", "oneOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/SummaryWithMaxTokensOptions" } ] }, "extras": { "type": "object", "properties": { "links": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Number of URLs to return from each webpage.", "default": 0 }, { "type": "null" } ] }, "imageLinks": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Number of images to return for each result.", "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, "default": 0, "description": "Deprecated. Number of rich links to return for each result.", "x-exa-lifecycle": "deprecated", "deprecated": true }, { "type": "null" } ] }, "codeBlocks": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "default": 0, "description": "Deprecated. Number of code blocks to return for each result.", "x-exa-lifecycle": "deprecated", "deprecated": true }, { "type": "null" } ] } }, "description": "Extra parameters to pass." }, "livecrawlTimeout": { "type": "integer", "exclusiveMinimum": 0, "maximum": 90000, "description": "The timeout for livecrawling in milliseconds.", "default": 10000 }, "maxAgeHours": { "type": "integer", "minimum": -1, "maximum": 720, "description": "Maximum age of cached content, in hours, up to 720. Cached content younger than this is used, and older pages are fetched fresh. `0` always fetches fresh content and `-1` always uses the cache. When omitted, cached content is used when available and pages without it are fetched live." }, "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.", "default": 0 }, "subpageTarget": { "description": "Term to find specific subpages of search results. Can be a single string or an array of strings.", "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "minItems": 0, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } } ] }, "context": { "description": "Deprecated. Use `highlights` or `text` instead. Returns page contents as a combined context string.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": ["highlights", "text"], "oneOf": [ { "type": "boolean", "description": "Deprecated. Use `highlights` or `text` instead. Returns page contents as a combined context string.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": ["highlights", "text"] }, { "type": "object", "properties": { "maxCharacters": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Maximum character limit for the context string." } }, "description": "Deprecated. Use `highlights` or `text` instead. Returns page contents as a combined context string.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": ["highlights", "text"] } ] }, "livecrawl": { "description": "Deprecated. Use `maxAgeHours` instead. Does not guarantee freshly fetched content. Cannot be combined with `maxAgeHours`.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": "maxAgeHours", "oneOf": [ { "type": "string", "enum": ["never", "always", "fallback", "preferred"] }, { "type": "string", "const": "auto" } ] } }, "description": "Content extraction options applied to each search result. All fields are optional." }, "SummaryWithMaxTokensOptions": { "type": "object", "properties": { "query": { "anyOf": [ { "type": "string", "description": "Custom query for the LLM-generated summary." }, { "type": "null" } ] }, "maxTokens": { "type": "integer", "minimum": 1, "description": "Deprecated. Maximum tokens for the generated summary.", "x-exa-lifecycle": "deprecated", "deprecated": true } } }, "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)." } }, "required": ["type", "period"] }, "SearchMonitorOutputSchema": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/OutputSchemaText" }, { "$ref": "#/components/schemas/OutputSchemaObject" } ], "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 except `lite` and adds about 2 seconds of synthesis latency on top of the selected search type. Object schemas are limited to 10 properties in total (nested and array items properties count toward the limit) and 2 levels of nesting, and every array must define items.", "type": "object", "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/OutputSchemaText", "object": "#/components/schemas/OutputSchemaObject" } } }, { "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." }, "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"] }, "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"] }, "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." }, "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 support@exa.ai to discuss higher limits.", "default": 10 }, "includeDomains": { "description": "Restrict search results to these domains.", "type": "array", "items": { "type": "string" } }, "excludeDomains": { "description": "Exclude these domains from search results.", "type": "array", "items": { "type": "string" } }, "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." }, { "type": "null" } ], "description": "Update metadata. Set to null to remove. Echoed back in webhook deliveries so you can route updates to systems like Slack." }, "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." } } }, "CreateAgentRunRequest": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "Natural-language question or instructions for the request." }, "systemPrompt": { "type": "string", "description": "Additional instructions that guide generated output or agent behavior. Use this for source preferences, novelty constraints, duplication constraints, or other behavior guidance." }, "effort": { "$ref": "#/components/schemas/AgentEffort" }, "input": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "description": "A JSON object record." }, "description": "Records the agent should process or enrich." }, "exclusion": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "description": "A JSON object record." }, "description": "Records or entities the agent should avoid returning." } }, "description": "Records to process and records or entities to exclude from the answer." }, "outputSchema": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "description": "JSON Schema for validated structured output in `output.structured`. Fields unsupported by evidence may be returned as `null`. Supports draft-07, 2019-09, and 2020-12 via `$schema`." }, { "type": "null" } ] }, "previousRunId": { "description": "Completed run ID to continue from. Must belong to the same team.", "$ref": "#/components/schemas/AgentRunId" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Caller-provided metadata stored with the run." }, "dataSources": { "maxItems": 5, "type": "array", "items": { "$ref": "#/components/schemas/AgentDataSource" }, "description": "Exa Connect data providers to enable for the run. Each entry enables all of that provider's tools." }, "budget": { "$ref": "#/components/schemas/AgentBudget" }, "userIdentifier": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ], "description": "An opaque ID your platform assigns to the end user this request is made for, such as a UUID. Lets Exa attribute usage to that end user rather than your whole team. Must not contain personal information such as an email address, phone number, username, or name. Hash such values before sending them. 1 to 64 characters: letters, digits, underscores, and hyphens. Retained even when your team has Zero Data Retention enabled. Does not affect results.", "example": "7f3a9c52-1d4e-4b8a-9e60-2c5d8a1f0b37" } }, "required": ["query"] }, "AgentEffort": { "type": "string", "enum": ["minimal", "low", "medium", "high", "xhigh", "auto", "ultra"], "description": "Cost and reasoning effort preference for the run. `auto` lets Exa choose the appropriate effort. `ultra` is the highest-effort tier for work where completeness and thoroughness matter more than latency or cost, including large list building, deep multi-source research, and criteria that are hard to verify.", "default": "auto" }, "AgentRunId": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[A-Za-z0-9_.:-]+$", "description": "Agent run ID. New run IDs are returned with the `agent_run_` prefix." }, "AgentDataSource": { "type": "object", "properties": { "provider": { "description": "Exa Connect data provider to enable for the run. All provider tools are available by default.", "$ref": "#/components/schemas/AgentDataSourceProvider" } }, "required": ["provider"] }, "AgentDataSourceProvider": { "type": "string", "minLength": 1, "description": "Identifier of an Exa Connect data provider, such as `fiber` or `financial_datasets`. A team can use the self-serve providers and any provider enabled for it; requesting any other provider returns a 400." }, "AgentBudget": { "type": "object", "properties": { "maxCostDollars": { "type": "number", "description": "Accepts $1 to $100. For `auto` and `ultra`, caps total run cost with default caps of $5 and $20 respectively. For fixed efforts, caps contact-enrichment calls using the budget remaining after the fixed request price, without limiting research or reasoning steps. Fixed efforts have no default cap, and an explicit cap must cover the fixed request price." }, "maxDurationSeconds": { "type": "integer", "description": "Soft wall-clock ceiling for the run in seconds. Accepts 300–10,800 (5 minutes to 3 hours) and applies only to `ultra`. As the run approaches the limit, the agent stops starting new work and returns what it has found with `stopReason: \"time_limit_reached\"`." } }, "description": "Per-run cost or contact-enrichment limits, depending on effort, and an `ultra` duration limit." }, "CreateBatchRequest": { "type": "object", "properties": { "requests": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/BatchRequestItem" }, "description": "The requests to enqueue. Each `customId` must be unique within the batch." }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Caller-provided metadata stored with the batch." } }, "required": ["requests"] }, "BatchRequestItem": { "type": "object", "properties": { "customId": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Your unique handle for this request; keys the result and must be unique in the batch." }, "method": { "type": "string", "const": "POST", "description": "HTTP method of the batched request. POST-only in v1." }, "url": { "type": "string", "enum": ["/search", "/agent/runs"], "description": "Target API route for the request." }, "body": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "description": "Request body for the target route. Must be a JSON object; `stream: true` is not allowed." } }, "required": ["customId", "method", "url", "body"] }, "AnswerStreamTextDeltaChunk": { "type": "object", "properties": { "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0, "description": "Index of this streamed choice." }, "delta": { "type": "object", "properties": { "role": { "type": "string", "const": "assistant" }, "content": { "type": "string" }, "refusal": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "description": "Incremental answer content emitted by the model." }, "finish_reason": { "description": "Reason this streamed choice finished, when present.", "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["index", "delta"], "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, "description": "Streamed completion choices in the OpenAI chat completions format." } }, "required": ["choices"], "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, "SearchResponse": { "oneOf": [ { "$ref": "#/components/schemas/SearchSynthesisResponse" }, { "$ref": "#/components/schemas/SearchResultsResponse" } ] }, "SearchSynthesisResponse": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for the request." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResultOutput" }, "description": "A list of search results containing title, URL, published date, and author." }, "costDollars": { "$ref": "#/components/schemas/CostDollarsOutput" }, "searchTime": { "type": "number", "description": "Server-side processing time in milliseconds. May exclude output synthesis time, so it can be lower than end-to-end latency." }, "warnings": { "description": "Warnings about the request, such as a field that has no effect. Log them; do not pass them to a model. Omitted when there are none.", "type": "array", "items": { "$ref": "#/components/schemas/SearchWarningOutput" } }, "notices": { "description": "Notices about how the results were produced. Pass them to your model with the results. Omitted when there are none.", "type": "array", "items": { "$ref": "#/components/schemas/SearchNoticeOutput" } }, "output": { "$ref": "#/components/schemas/SearchSynthesisOutputOutput" }, "resolvedSearchType": { "description": "Deprecated. May be an empty string. Do not branch on this value.", "x-exa-lifecycle": "deprecated", "deprecated": true, "type": "string" }, "context": { "type": "string", "description": "Deprecated. Use `results[].highlights` or `results[].text` instead. Combined context string from search results.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": ["results[].highlights", "results[].text"] } }, "required": ["results", "output"], "additionalProperties": false }, "SearchResultsResponse": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for the request." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResultOutput" }, "description": "A list of search results containing title, URL, published date, and author." }, "costDollars": { "$ref": "#/components/schemas/CostDollarsOutput" }, "searchTime": { "type": "number", "description": "Server-side processing time in milliseconds. May exclude output synthesis time, so it can be lower than end-to-end latency." }, "warnings": { "description": "Warnings about the request, such as a field that has no effect. Log them; do not pass them to a model. Omitted when there are none.", "type": "array", "items": { "$ref": "#/components/schemas/SearchWarningOutput" } }, "notices": { "description": "Notices about how the results were produced. Pass them to your model with the results. Omitted when there are none.", "type": "array", "items": { "$ref": "#/components/schemas/SearchNoticeOutput" } }, "resolvedSearchType": { "description": "Deprecated. May be an empty string. Do not branch on this value.", "x-exa-lifecycle": "deprecated", "deprecated": true, "type": "string" }, "context": { "type": "string", "description": "Deprecated. Use `results[].highlights` or `results[].text` instead. Combined context string from search results.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": ["results[].highlights", "results[].text"] } }, "required": ["results"], "additionalProperties": false }, "ErrorResponse": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for the request." }, "error": { "type": "string", "description": "Human-readable message describing the error." }, "tag": { "type": "string", "description": "Machine-readable error tag identifying the failure. The set of tags is open-ended: new tags may be added at any time, so treat unrecognized tags as a generic error of the response's HTTP status. Known tags are listed as examples." } }, "required": ["requestId", "error", "tag"], "additionalProperties": false, "description": "Standard error envelope returned by the Exa API for failed requests." }, "X402PaymentChallenge": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for the request." }, "error": { "type": "string", "description": "Human-readable message describing the error." }, "tag": { "type": "string", "description": "Machine-readable error tag identifying the failure. The set of tags is open-ended: new tags may be added at any time, so treat unrecognized tags as a generic error of the response's HTTP status. Known tags are listed as examples." }, "x402Version": { "type": "number", "description": "Version of the x402 protocol used to build this challenge." }, "resource": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the priced resource being requested." }, "description": { "type": "string", "description": "Human-readable resource description." }, "mimeType": { "type": "string", "description": "MIME type of the priced resource." } }, "required": ["url", "description", "mimeType"], "additionalProperties": false, "description": "The priced resource this challenge applies to." }, "accepts": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "An accepted x402 payment requirement (scheme, network, amount, payTo, asset, maxTimeoutSeconds, and scheme-specific `extra` fields)." }, "description": "Payment requirements the server accepts, one per supported rail." }, "extensions": { "description": "Optional x402 protocol extensions (e.g. Bazaar or AgentKit discovery metadata).", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["requestId", "error", "tag", "x402Version", "resource", "accepts"], "additionalProperties": false, "description": "x402 payment challenge: the standard error envelope extended with x402 payment metadata." }, "ContentsResponse": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for the request." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResultOutput" } }, "statuses": { "description": "Status information for each requested URL or document ID.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The URL or document ID that was requested." }, "status": { "type": "string", "enum": ["success", "error"], "description": "Status of the content fetch operation." }, "source": { "description": "Where the returned content was sourced from.", "type": "string", "enum": ["cached", "crawled"] }, "error": { "anyOf": [ { "type": "object", "properties": { "tag": { "description": "Specific error type.", "type": "string" }, "httpStatusCode": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 599 }, { "type": "null" } ], "description": "The corresponding HTTP status code." } }, "additionalProperties": false }, { "type": "null" } ], "description": "Error details, only present when status is \"error\"." } }, "required": ["id", "status"], "additionalProperties": false } }, "costDollars": { "$ref": "#/components/schemas/CostDollarsOutput" }, "searchTime": { "type": "number", "description": "Server-side processing time in milliseconds. May exclude output synthesis time, so it can be lower than end-to-end latency." }, "context": { "type": "string", "description": "Deprecated. Use `results[].highlights` or `results[].text` instead. Combined context string from search results.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": ["results[].highlights", "results[].text"] } }, "additionalProperties": false }, "AnswerResponse": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for the request." }, "answer": { "description": "The generated answer based on search results. Returns a string by default, or a structured object matching the provided outputSchema.", "oneOf": [ { "type": "string" }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "citations": { "description": "Search results used to generate the answer.", "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "The title of the search result." }, "url": { "type": "string", "description": "The URL of the search result.", "format": "uri" }, "publishedDate": { "description": "An estimate of the creation date, from parsing HTML content, as an ISO 8601 date-time in UTC (`YYYY-MM-DDTHH:mm:ss.sssZ`). A date known only to the day has the time `00:00:00.000Z`.", "format": "date-time", "type": "string" }, "author": { "description": "If available, the author of the content.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "description": "The temporary ID for the document. Useful for the /contents endpoint.", "type": "string" }, "image": { "description": "The URL of an image associated with the search result, if available.", "format": "uri", "type": "string" }, "favicon": { "description": "The URL of the favicon for the search result's domain.", "format": "uri", "type": "string" }, "text": { "description": "The full text content of each source. Only present when text contents are requested.", "type": "string" } }, "required": ["title", "url"], "additionalProperties": false } }, "costDollars": { "$ref": "#/components/schemas/CostDollarsOutput" } }, "required": ["answer"], "additionalProperties": false }, "FindSimilarResponse": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for the request." }, "results": { "description": "A list of search results containing title, URL, published date, and author.", "type": "array", "items": { "$ref": "#/components/schemas/FindSimilarResult" } }, "costDollars": { "$ref": "#/components/schemas/CostDollarsOutput" }, "searchTime": { "type": "number", "description": "Server-side processing time in milliseconds. May exclude output synthesis time, so it can be lower than end-to-end latency." }, "context": { "type": "string", "description": "Deprecated. Use `results[].highlights` or `results[].text` instead. Combined context string from search results.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": ["results[].highlights", "results[].text"] } }, "additionalProperties": false }, "FindSimilarResult": { "type": "object", "properties": { "title": { "type": "string", "description": "The title of the search result." }, "url": { "type": "string", "description": "The URL of the search result.", "format": "uri" }, "publishedDate": { "description": "An estimate of the creation date, from parsing HTML content, as an ISO 8601 date-time in UTC (`YYYY-MM-DDTHH:mm:ss.sssZ`). A date known only to the day has the time `00:00:00.000Z`.", "format": "date-time", "type": "string" }, "author": { "description": "If available, the author of the content.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "description": "The temporary ID for the document. Useful for the /contents endpoint.", "type": "string" }, "image": { "description": "The URL of an image associated with the search result, if available.", "format": "uri", "type": "string" }, "favicon": { "description": "The URL of the favicon for the search result's domain.", "format": "uri", "type": "string" }, "text": { "description": "The full content text of the search result.", "type": "string" }, "highlights": { "description": "Array of highlights extracted from the search result content.", "type": "array", "items": { "type": "string" } }, "summary": { "description": "Summary of the webpage.", "type": "string" }, "subpages": { "description": "Array of subpages for the search result.", "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "The title of the search result." }, "url": { "type": "string", "description": "The URL of the search result.", "format": "uri" }, "publishedDate": { "description": "An estimate of the creation date, from parsing HTML content, as an ISO 8601 date-time in UTC (`YYYY-MM-DDTHH:mm:ss.sssZ`). A date known only to the day has the time `00:00:00.000Z`.", "format": "date-time", "type": "string" }, "author": { "description": "If available, the author of the content.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "description": "The temporary ID for the document. Useful for the /contents endpoint.", "type": "string" }, "image": { "description": "The URL of an image associated with the search result, if available.", "format": "uri", "type": "string" }, "favicon": { "description": "The URL of the favicon for the search result's domain.", "format": "uri", "type": "string" } }, "required": ["title", "url"], "additionalProperties": false } }, "entities": { "description": "Structured entity data for company, person, publication, or product search results. Returned for supported entity-backed categories and for product listing pages.", "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/SearchCompanyEntityOutput" }, { "$ref": "#/components/schemas/SearchPersonEntityOutput" }, { "$ref": "#/components/schemas/SearchPublicationEntityOutput" } ], "type": "object", "discriminator": { "propertyName": "type", "mapping": { "company": "#/components/schemas/SearchCompanyEntityOutput", "person": "#/components/schemas/SearchPersonEntityOutput", "publication": "#/components/schemas/SearchPublicationEntityOutput" } } } }, "extras": { "description": "Results from extras. Each field is returned only when requested via contents.extras.", "type": "object", "properties": { "links": { "description": "Array of links from the search result.", "type": "array", "items": { "type": "string" } }, "imageLinks": { "description": "Array of image URLs from the search result.", "type": "array", "items": { "type": "string" } }, "richImageLinks": { "description": "Array of images with their alt text, in the order the images appear on the page.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL of the image." }, "alt": { "description": "The alt text of the image, when the page provides one.", "type": "string" } }, "required": ["url"], "additionalProperties": false } }, "richLinks": { "description": "Array of links with their anchor text, in the order they appear on the page.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL of the link." }, "anchor": { "description": "The anchor text of the link, when the page provides one.", "type": "string" } }, "required": ["url"], "additionalProperties": false } }, "codeBlocks": { "description": "Array of code blocks from the search result.", "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "The contents of the code block." }, "source": { "type": "string", "description": "The language the code block is annotated with, if any." } }, "required": ["text", "source"], "additionalProperties": false } } }, "additionalProperties": false }, "score": { "description": "Similarity score between the source url and the result. Higher values mean more similar; the scale is not normalized, so compare scores only within a single response.", "format": "float", "type": "number" } }, "required": ["title", "url"], "additionalProperties": false }, "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." }, { "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." }, "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 }, "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 }, "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." }, { "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." }, "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 }, "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 }, "TriggerSearchMonitorResponse": { "type": "object", "properties": { "triggered": { "type": "boolean", "description": "Whether the monitor was successfully triggered" } }, "required": ["triggered"], "additionalProperties": false }, "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 }, "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", "source_not_available", "forbidden", "search_unavailable", "search_failed", "internal_error" ] }, { "type": "null" } ], "description": "The reason the run failed. Null unless status is `failed`. `source_not_available` means the search requested a domain Exa cannot return (remove it from the search), and `forbidden` means the request was otherwise not permitted." }, "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 }, "AgentRun": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/AgentRunId" }, "object": { "type": "string", "const": "agent_run" }, "status": { "$ref": "#/components/schemas/AgentRunStatus" }, "stopReason": { "anyOf": [ { "$ref": "#/components/schemas/AgentStopReason" }, { "type": "null" } ], "description": "Why the run stopped. `null` while the run is queued or running. Every reason except `error` and `cancelled` means the run completed and returned what it found. Clients should accept values not listed here." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the run was created" }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "format": "date-time" }, "request": { "anyOf": [ { "$ref": "#/components/schemas/AgentRunRequest" }, { "type": "null" } ] }, "error": { "anyOf": [ { "$ref": "#/components/schemas/AgentError" }, { "type": "null" } ], "description": "Why the run failed. `null` unless `status` is `failed`." }, "output": { "$ref": "#/components/schemas/AgentRunOutput" }, "usage": { "$ref": "#/components/schemas/AgentUsage" }, "costDollars": { "$ref": "#/components/schemas/AgentCostDollars" } }, "required": [ "id", "object", "status", "stopReason", "createdAt", "completedAt", "request", "error", "output", "usage", "costDollars" ], "additionalProperties": false }, "AgentRunStatus": { "type": "string", "enum": ["queued", "running", "completed", "failed", "cancelled"] }, "AgentStopReason": { "anyOf": [ { "type": "string", "const": "schema_satisfied", "description": "The agent finished the task before reaching any limit." }, { "type": "string", "const": "budget_reached", "description": "The run reached `budget.maxCostDollars`." }, { "type": "string", "const": "time_limit_reached", "description": "The run reached `budget.maxDurationSeconds`." }, { "type": "string", "const": "iteration_limit_reached", "description": "The run reached its maximum number of agent steps." }, { "type": "string", "const": "token_limit_reached", "description": "The run reached its limit on model tokens." }, { "type": "string", "const": "stopped", "description": "You stopped the run." }, { "type": "string", "const": "error", "description": "The run failed." }, { "type": "string", "const": "cancelled", "description": "The run was cancelled." }, { "type": "string" } ], "x-exa-enum-open": true }, "AgentRunRequest": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "Natural-language question or instructions for the request." }, "systemPrompt": { "type": "string", "description": "Additional instructions that guide generated output or agent behavior. Use this for source preferences, novelty constraints, duplication constraints, or other behavior guidance." }, "effort": { "$ref": "#/components/schemas/AgentEffort" }, "input": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "description": "A JSON object record." }, "description": "Records the agent should process or enrich." }, "exclusion": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "description": "A JSON object record." }, "description": "Records or entities the agent should avoid returning." } }, "additionalProperties": false }, "outputSchema": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "description": "JSON Schema for validated structured output in `output.structured`. Fields unsupported by evidence may be returned as `null`. Supports draft-07, 2019-09, and 2020-12 via `$schema`." }, { "type": "null" } ] }, "previousRunId": { "$ref": "#/components/schemas/AgentRunId" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Caller-provided key-value metadata for your own tracking." }, "dataSources": { "type": "array", "items": { "$ref": "#/components/schemas/AgentDataSourceOutput" }, "description": "Exa Connect data providers configured for the run." }, "budget": { "$ref": "#/components/schemas/AgentBudgetOutput" } }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" }, "description": "Canonicalized request fields stored with the run." }, "AgentError": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "INVALID_REQUEST", "AUTHENTICATION_ERROR", "RATE_LIMIT_ERROR", "NOT_FOUND", "SERVER_ERROR" ] }, "code": { "type": "string", "enum": [ "INVALID_REQUEST", "TEAM_NOT_FOUND", "RUN_NOT_FOUND", "PREVIOUS_RUN_NOT_FOUND", "PREVIOUS_RUN_NOT_COMPLETED", "CONCURRENCY_LIMIT_REACHED", "INVALID_OUTPUT_SCHEMA", "INVALID_DATA_SOURCE", "TIMEOUT", "SERVER_ERROR" ] }, "message": { "type": "string" } }, "required": ["type", "code", "message"], "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, "AgentRunOutput": { "type": "object", "properties": { "text": { "type": "string", "description": "Natural-language answer or summary." }, "structured": { "anyOf": [ { "$ref": "#/components/schemas/JsonValue" }, { "type": "null" } ], "description": "JSON shaped by `outputSchema`; fields unsupported by evidence may be `null`. `null` when no schema was provided." }, "grounding": { "type": "array", "items": { "$ref": "#/components/schemas/AgentGrounding" }, "description": "Field-level citations emitted by the run." } }, "required": ["text", "structured", "grounding"], "additionalProperties": false }, "AgentGrounding": { "type": "object", "properties": { "field": { "type": "string", "description": "Output field the citations support." }, "citations": { "type": "array", "items": { "$ref": "#/components/schemas/AgentCitation" } }, "confidence": { "anyOf": [ { "type": "string", "enum": ["low", "medium", "high"], "description": "Model-reported reliability for this field." }, { "type": "null" } ] } }, "required": ["field", "citations"], "additionalProperties": false }, "AgentCitation": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Source URL." }, "title": { "type": "string", "description": "Source title." } }, "required": ["url"], "additionalProperties": false }, "AgentUsage": { "type": "object", "properties": { "agentComputeUnits": { "type": "number", "minimum": 0 }, "searches": { "type": "number", "minimum": 0 }, "emails": { "type": "number", "minimum": 0 }, "phoneNumbers": { "type": "number", "minimum": 0 }, "dataSources": { "$ref": "#/components/schemas/AgentDataSourceUsage" } }, "required": ["agentComputeUnits", "searches", "emails", "phoneNumbers"], "additionalProperties": false, "description": "Billed usage for the run. When an `auto` or `ultra` run's metered cost exceeds `budget.maxCostDollars`, the run is billed the budget and each quantity except `dataSources` is scaled down in proportion, so quantities can be fractional." }, "AgentDataSourceUsage": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0 }, "description": "Per-provider tool call counts for Exa Connect data sources used during the run. Keys are provider names (e.g. `fiber`, `similarweb`). Only providers with non-zero usage are included." }, "AgentCostDollars": { "type": "object", "properties": { "total": { "type": "number", "minimum": 0 }, "agentCompute": { "type": "number", "minimum": 0 }, "search": { "type": "number", "minimum": 0 }, "emails": { "type": "number", "minimum": 0 }, "phoneNumbers": { "type": "number", "minimum": 0 }, "dataSources": { "$ref": "#/components/schemas/AgentDataSourceCost" } }, "required": ["total", "agentCompute", "search", "emails", "phoneNumbers"], "additionalProperties": false }, "AgentDataSourceCost": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number", "minimum": 0 }, "description": "Per-provider cost in dollars for Exa Connect data sources used during the run. Keys are provider names (e.g. `fiber`, `similarweb`). Only providers with non-zero usage are included." }, "AgentRunEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Event ID within the run." }, "event": { "type": "string", "enum": [ "agent_run.created", "agent_run.started", "agent_run.completed", "agent_run.failed", "agent_run.cancelled" ] }, "data": { "$ref": "#/components/schemas/JsonValue" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the event was created" } }, "required": ["id", "event", "data", "createdAt"], "additionalProperties": false }, "AgentErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/AgentError" } }, "required": ["error"], "additionalProperties": false }, "AgentRunList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentRun" } }, "hasMore": { "type": "boolean", "description": "Whether there are more results" }, "nextCursor": { "anyOf": [ { "$ref": "#/components/schemas/AgentRunId" }, { "type": "null" } ] } }, "required": ["object", "data", "hasMore", "nextCursor"], "additionalProperties": false }, "DeleteAgentRunResponse": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/AgentRunId" }, "object": { "type": "string", "const": "agent_run.deleted" }, "deleted": { "type": "boolean", "const": true } }, "required": ["id", "object", "deleted"], "additionalProperties": false }, "AgentRunEventList": { "type": "object", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentRunEvent" } }, "hasMore": { "type": "boolean", "description": "Whether there are more results" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["object", "data", "hasMore", "nextCursor"], "additionalProperties": false }, "Batch": { "type": "object", "properties": { "id": { "type": "string", "description": "Batch ID. New batch IDs are returned with the `batch_` prefix." }, "object": { "type": "string", "const": "batch", "description": "The object type, always `batch`." }, "status": { "$ref": "#/components/schemas/BatchStatus" }, "requestCounts": { "$ref": "#/components/schemas/BatchRequestCounts" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the batch was created." }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the batch expires, or `null` if it does not expire.", "format": "date-time" }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the batch reached a terminal status, or `null` while it is still running.", "format": "date-time" }, "resultsUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Short-lived download URL for the batch results file (JSONL), or `null` until the batch completes. Fetch it directly, without an API key. Retrieve the batch again for a fresh URL after it expires." }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Caller-provided key-value metadata for your own tracking." } }, "required": [ "id", "object", "status", "requestCounts", "createdAt", "expiresAt", "endedAt", "resultsUrl", "metadata" ], "additionalProperties": false }, "BatchStatus": { "type": "string", "enum": ["in_progress", "completed", "cancelling", "cancelled", "expired"], "description": "Lifecycle status of the batch." }, "BatchRequestCounts": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Total requests in the batch." }, "completed": { "type": "integer", "minimum": 0, "description": "Requests that have completed successfully." }, "failed": { "type": "integer", "minimum": 0, "description": "Requests that have failed." } }, "required": ["total", "completed", "failed"], "additionalProperties": false }, "BatchList": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "The object type, always `list`." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Batch" }, "description": "The page of batches, newest first." }, "hasMore": { "type": "boolean", "description": "Whether there are more results" }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page" } }, "required": ["object", "data", "hasMore", "nextCursor"], "additionalProperties": false }, "DeletedBatch": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the deleted batch." }, "object": { "type": "string", "const": "batch.deleted", "description": "The object type, always `batch.deleted`." }, "deleted": { "type": "boolean", "const": true, "description": "Always `true` for a successful delete." } }, "required": ["id", "object", "deleted"], "additionalProperties": false }, "WebsetsTeamInfo": { "type": "object", "properties": { "object": { "type": "string", "const": "team", "description": "The object type, always `\"team\"`." }, "id": { "type": "string", "description": "Unique identifier for the team." }, "name": { "type": "string", "description": "Name of the team." }, "concurrency": { "type": "object", "properties": { "active": { "type": "integer", "description": "Number of requests currently being processed." }, "queued": { "type": "integer", "description": "Number of requests currently queued." } }, "required": ["active", "queued"], "additionalProperties": false, "description": "Current concurrency usage." }, "limits": { "type": "object", "properties": { "maxConcurrent": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Maximum number of concurrent requests allowed. Null means unlimited." }, "maxQueued": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Maximum number of queued requests allowed. Null means unlimited." } }, "required": ["maxConcurrent", "maxQueued"], "additionalProperties": false, "description": "Concurrency limits for the team." } }, "required": ["object", "id", "name", "concurrency", "limits"], "additionalProperties": false }, "AnswerStreamChunk": { "description": "Schema for each JSON payload emitted in an `/answer` server-sent event stream. Each event is emitted as `data: `.", "oneOf": [ { "$ref": "#/components/schemas/AnswerStreamTextDeltaChunk" }, { "$ref": "#/components/schemas/AnswerStreamCitationsChunkOutput" }, { "$ref": "#/components/schemas/AnswerStreamCostChunkOutput" }, { "$ref": "#/components/schemas/AnswerStreamErrorChunkOutput" } ] }, "SearchStreamChunk": { "oneOf": [ { "$ref": "#/components/schemas/SearchStreamTextDeltaChunkOutput" }, { "$ref": "#/components/schemas/SearchStreamGroundingChunkOutput" }, { "$ref": "#/components/schemas/SearchStreamResultsChunkOutput" }, { "$ref": "#/components/schemas/SearchStreamResetChunkOutput" }, { "$ref": "#/components/schemas/SearchStreamDoneChunkOutput" }, { "$ref": "#/components/schemas/SearchStreamErrorChunkOutput" } ], "description": "Schema for each JSON payload emitted in a `/search` server-sent event stream. Each event is emitted as `data: ` and the stream terminates with `data: [DONE]`, which is not represented by this JSON schema.", "type": "object", "discriminator": { "propertyName": "type", "mapping": { "text-delta": "#/components/schemas/SearchStreamTextDeltaChunkOutput", "grounding": "#/components/schemas/SearchStreamGroundingChunkOutput", "results": "#/components/schemas/SearchStreamResultsChunkOutput", "stream-reset": "#/components/schemas/SearchStreamResetChunkOutput", "done": "#/components/schemas/SearchStreamDoneChunkOutput", "error": "#/components/schemas/SearchStreamErrorChunkOutput" } } }, "SearchResultOutput": { "type": "object", "properties": { "title": { "type": "string", "description": "The title of the search result." }, "url": { "type": "string", "description": "The URL of the search result.", "format": "uri" }, "publishedDate": { "description": "An estimate of the creation date, from parsing HTML content, as an ISO 8601 date-time in UTC (`YYYY-MM-DDTHH:mm:ss.sssZ`). A date known only to the day has the time `00:00:00.000Z`.", "format": "date-time", "type": "string" }, "author": { "description": "If available, the author of the content.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "description": "The temporary ID for the document. Useful for the /contents endpoint.", "type": "string" }, "image": { "description": "The URL of an image associated with the search result, if available.", "format": "uri", "type": "string" }, "favicon": { "description": "The URL of the favicon for the search result's domain.", "format": "uri", "type": "string" }, "text": { "description": "The full content text of the search result.", "type": "string" }, "highlights": { "description": "Array of highlights extracted from the search result content.", "type": "array", "items": { "type": "string" } }, "summary": { "description": "Summary of the webpage.", "type": "string" }, "subpages": { "description": "Array of subpages for the search result.", "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "The title of the search result." }, "url": { "type": "string", "description": "The URL of the search result.", "format": "uri" }, "publishedDate": { "description": "An estimate of the creation date, from parsing HTML content, as an ISO 8601 date-time in UTC (`YYYY-MM-DDTHH:mm:ss.sssZ`). A date known only to the day has the time `00:00:00.000Z`.", "format": "date-time", "type": "string" }, "author": { "description": "If available, the author of the content.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "description": "The temporary ID for the document. Useful for the /contents endpoint.", "type": "string" }, "image": { "description": "The URL of an image associated with the search result, if available.", "format": "uri", "type": "string" }, "favicon": { "description": "The URL of the favicon for the search result's domain.", "format": "uri", "type": "string" } }, "required": ["title", "url"], "additionalProperties": false } }, "entities": { "description": "Structured entity data for company, person, publication, or product search results. Returned for supported entity-backed categories and for product listing pages.", "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/SearchCompanyEntityOutput" }, { "$ref": "#/components/schemas/SearchPersonEntityOutput" }, { "$ref": "#/components/schemas/SearchPublicationEntityOutput" } ], "type": "object", "discriminator": { "propertyName": "type", "mapping": { "company": "#/components/schemas/SearchCompanyEntityOutput", "person": "#/components/schemas/SearchPersonEntityOutput", "publication": "#/components/schemas/SearchPublicationEntityOutput" } } } }, "extras": { "description": "Results from extras. Each field is returned only when requested via contents.extras.", "type": "object", "properties": { "links": { "description": "Array of links from the search result.", "type": "array", "items": { "type": "string" } }, "imageLinks": { "description": "Array of image URLs from the search result.", "type": "array", "items": { "type": "string" } }, "richImageLinks": { "description": "Array of images with their alt text, in the order the images appear on the page.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL of the image." }, "alt": { "description": "The alt text of the image, when the page provides one.", "type": "string" } }, "required": ["url"], "additionalProperties": false } }, "richLinks": { "description": "Array of links with their anchor text, in the order they appear on the page.", "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL of the link." }, "anchor": { "description": "The anchor text of the link, when the page provides one.", "type": "string" } }, "required": ["url"], "additionalProperties": false } }, "codeBlocks": { "description": "Array of code blocks from the search result.", "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "The contents of the code block." }, "source": { "type": "string", "description": "The language the code block is annotated with, if any." } }, "required": ["text", "source"], "additionalProperties": false } } }, "additionalProperties": false } }, "required": ["title", "url"], "additionalProperties": false }, "SearchCompanyEntityOutput": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable company entity identifier." }, "type": { "type": "string", "const": "company", "description": "Entity discriminator." }, "version": { "type": "integer", "minimum": 1, "description": "Entity schema version." }, "properties": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company name." }, "foundedYear": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Year the company was founded." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Short company description." }, "workforce": { "anyOf": [ { "type": "object", "properties": { "total": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Total estimated employee count." } }, "required": ["total"], "additionalProperties": false }, { "type": "null" } ], "description": "Company workforce information." }, "headquarters": { "anyOf": [ { "type": "object", "properties": { "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company headquarters street address." }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company headquarters city." }, "postalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company headquarters postal code." }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company headquarters country." } }, "required": ["address", "city", "postalCode", "country"], "additionalProperties": false }, { "type": "null" } ], "description": "Company headquarters information." }, "financials": { "anyOf": [ { "type": "object", "properties": { "revenueAnnual": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Estimated annual revenue in USD." }, "fundingTotal": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Total funding raised in USD." }, "fundingLatestRound": { "anyOf": [ { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Funding round name." }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Funding round date." }, "amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Funding round amount in USD." } }, "required": ["name", "date", "amount"], "additionalProperties": false }, { "type": "null" } ], "description": "Most recent funding round, when available." } }, "required": ["revenueAnnual", "fundingTotal", "fundingLatestRound"], "additionalProperties": false }, { "type": "null" } ], "description": "Company financial information." }, "webTraffic": { "anyOf": [ { "type": "object", "properties": { "visitsMonthly": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Estimated monthly website visits." }, "countryRank": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Estimated website traffic rank within the company's primary country." }, "avgDurationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Estimated average visit duration, in seconds." }, "history": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "number", "description": "Estimated monthly visits for this period." }, "dateFrom": { "type": "string", "description": "Start month for this value, formatted as YYYY-MM." }, "dateTo": { "type": "string", "description": "End month for this value, formatted as YYYY-MM." } }, "required": ["value", "dateFrom", "dateTo"], "additionalProperties": false }, "description": "Historical monthly website visits." } }, "required": ["visitsMonthly", "countryRank", "avgDurationSeconds", "history"], "additionalProperties": false }, { "type": "null" } ], "description": "Company web traffic information." }, "research": { "anyOf": [ { "type": "object", "properties": { "worksCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of works with an affiliated author." }, "citationCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Lifetime citation count." }, "areas": { "type": "array", "items": { "type": "string" }, "description": "Ranked research areas, most active first." }, "notableWorks": { "type": "array", "items": { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publication title." }, "year": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Publication year." }, "venue": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publication venue." }, "citationCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of works citing this publication." }, "doi": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Digital Object Identifier." }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved publication entity identifier, when available." }, "type": { "anyOf": [ { "type": "string", "enum": [ "article", "book", "book-chapter", "dataset", "dissertation", "preprint", "report", "review" ] }, { "type": "null" } ], "description": "Publication type." } }, "required": [ "title", "year", "venue", "citationCount", "doi", "id", "type" ], "additionalProperties": false }, "description": "Most-cited notable works." }, "topResearchers": { "type": "array", "items": { "type": "object", "properties": { "person": { "anyOf": [ { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Referenced person name." }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Referenced person entity identifier." } }, "required": ["name", "id"], "additionalProperties": false }, { "type": "null" } ], "description": "Referenced researcher." }, "worksCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of works produced at the organization." }, "citationCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of citations for works produced at the organization." } }, "required": ["person", "worksCount", "citationCount"], "additionalProperties": false }, "description": "Researchers ordered by works produced at the organization." } }, "required": [ "worksCount", "citationCount", "areas", "notableWorks", "topResearchers" ], "additionalProperties": false }, { "type": "null" } ], "description": "Company research information." } }, "required": [ "name", "foundedYear", "description", "workforce", "headquarters", "financials", "webTraffic", "research" ], "additionalProperties": false, "description": "Company-specific entity fields." } }, "required": ["id", "type", "version", "properties"], "additionalProperties": false }, "SearchPersonEntityOutput": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable person entity identifier." }, "type": { "type": "string", "const": "person", "description": "Entity discriminator." }, "version": { "type": "integer", "minimum": 1, "description": "Entity schema version." }, "properties": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Person name." }, "firstName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Person first name." }, "lastName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Person last name." }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Person location." }, "workHistory": { "type": "array", "items": { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Role title." }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Role location." }, "dates": { "anyOf": [ { "type": "object", "properties": { "from": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Start date for the date range." }, "to": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "End date for the date range." } }, "required": ["from", "to"], "additionalProperties": false }, { "type": "null" } ], "description": "Role date range." }, "company": { "anyOf": [ { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Referenced company identifier." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Referenced company name." } }, "required": ["id", "name"], "additionalProperties": false }, { "type": "null" } ], "description": "Company for this role." } }, "required": ["title", "location", "dates", "company"], "additionalProperties": false }, "description": "Known professional roles for this person." }, "educationHistory": { "type": "array", "items": { "type": "object", "properties": { "degree": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Degree or credential." }, "dates": { "anyOf": [ { "type": "object", "properties": { "from": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Start date for the date range." }, "to": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "End date for the date range." } }, "required": ["from", "to"], "additionalProperties": false }, { "type": "null" } ], "description": "Education date range." }, "institution": { "anyOf": [ { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Referenced institution identifier." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Referenced institution name." } }, "required": ["id", "name"], "additionalProperties": false }, { "type": "null" } ], "description": "Education institution." } }, "required": ["degree", "dates", "institution"], "additionalProperties": false }, "description": "Known education history for this person." }, "research": { "anyOf": [ { "type": "object", "properties": { "worksCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Lifetime number of works." }, "citationCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Lifetime citation count." }, "hIndex": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Research h-index." }, "firstPublicationYear": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Year of the first publication." }, "latestPublicationYear": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Year of the latest publication." }, "areas": { "type": "array", "items": { "type": "string" }, "description": "Ranked research areas, most active first." }, "notableWorks": { "type": "array", "items": { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publication title." }, "year": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Publication year." }, "venue": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publication venue." }, "citationCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of works citing this publication." }, "doi": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Digital Object Identifier." }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved publication entity identifier, when available." }, "type": { "anyOf": [ { "type": "string", "enum": [ "article", "book", "book-chapter", "dataset", "dissertation", "preprint", "report", "review" ] }, { "type": "null" } ], "description": "Publication type." } }, "required": [ "title", "year", "venue", "citationCount", "doi", "id", "type" ], "additionalProperties": false }, "description": "Most-cited notable works." } }, "required": [ "worksCount", "citationCount", "hIndex", "firstPublicationYear", "latestPublicationYear", "areas", "notableWorks" ], "additionalProperties": false }, { "type": "null" } ], "description": "Person research information." } }, "required": [ "name", "firstName", "lastName", "location", "workHistory", "educationHistory", "research" ], "additionalProperties": false, "description": "Person-specific entity fields." } }, "required": ["id", "type", "version", "properties"], "additionalProperties": false }, "SearchPublicationEntityOutput": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable publication entity identifier." }, "type": { "type": "string", "const": "publication", "description": "Entity discriminator." }, "version": { "type": "integer", "minimum": 1, "description": "Entity schema version." }, "properties": { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publication title." }, "year": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Publication year." }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publication date." }, "type": { "anyOf": [ { "type": "string", "enum": [ "article", "book", "book-chapter", "dataset", "dissertation", "preprint", "report", "review" ] }, { "type": "null" } ], "description": "Publication type." }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publication language." }, "citationCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of works citing this publication (incoming references)." }, "authors": { "type": "array", "items": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Author display name." }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved person entity identifier, when available." } }, "required": ["name", "id"], "additionalProperties": false }, "description": "Ordered list of authors." }, "referenceCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of works this publication cites (outgoing references)." }, "abstract": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publication abstract text." }, "doi": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bare DOI identifier (e.g. 10.1234/abcd)." } }, "required": [ "title", "year", "date", "type", "language", "citationCount", "authors", "referenceCount", "abstract", "doi" ], "additionalProperties": false, "description": "Publication-specific entity fields." } }, "required": ["id", "type", "version", "properties"], "additionalProperties": false }, "CostDollarsOutput": { "type": "object", "properties": { "total": { "description": "Estimated total dollar cost for the completed request. This response value is not an invoice record.", "format": "float", "type": "number" }, "search": { "description": "Estimated search cost by retrieval mode. Some search types report their cost only in `total`.", "type": "object", "properties": { "neural": { "description": "Cost of neural search operations.", "format": "float", "type": "number" }, "keyword": { "description": "Cost of keyword search operations.", "format": "float", "type": "number" } }, "additionalProperties": false }, "summary": { "description": "Cost of per-result summaries requested with `contents.summary` on `/search` and `/findSimilar` requests.", "format": "float", "type": "number" }, "contents": { "description": "Cost breakdown for `/contents` requests.", "type": "object", "properties": { "text": { "description": "Cost of text extraction.", "format": "float", "type": "number" }, "highlights": { "description": "Cost of highlight extraction.", "format": "float", "type": "number" }, "summary": { "description": "Cost of per-result summary generation.", "format": "float", "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Estimated dollar cost of the request. Which fields appear depends on the endpoint." }, "SearchWarningOutput": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable warning code, UPPER_SNAKE. `IGNORED_FIELD`: the field at `path` is accepted and has no effect. Codes are an open set: tolerate codes you do not recognize.", "example": "IGNORED_FIELD" }, "path": { "type": "string", "description": "JSON Pointer to the request field the warning is about.", "example": "/startCrawlDate" }, "message": { "type": "string", "description": "Human-readable and complete on its own: what to change in the request." } }, "required": ["code", "path", "message"], "additionalProperties": false, "description": "A note about the request itself, for whoever maintains the code that builds it. Log it; do not pass it to a model. A warning never changes the status code or the results." }, "SearchNoticeOutput": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable notice code, UPPER_SNAKE. `RESTRICTIONS_RELAXED`: the `site:` or exact-phrase restrictions written in the query matched nothing, so the results come from a search with them removed; filters set in the request body were kept. Codes are an open set: tolerate codes you do not recognize.", "example": "RESTRICTIONS_RELAXED" }, "path": { "type": "string", "description": "JSON Pointer to the request field the notice is about.", "example": "/query" }, "message": { "type": "string", "description": "Human-readable and complete on its own; written to be shown to a model." }, "details": { "description": "Optional extra context for a harness or model. An open object: no schema is promised for its keys, and it never carries information that `message` lacks.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["code", "path", "message"], "additionalProperties": false, "description": "A note about how the results were produced, written to be passed to a model with the results." }, "SearchSynthesisOutputOutput": { "type": "object", "properties": { "content": { "description": "Synthesized content. String by default, or object when outputSchema is provided.", "oneOf": [ { "type": "string" }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ] }, "grounding": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Field path in output.content, for example content or companies[0].funding." }, "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 }, "description": "Sources supporting this output field." }, "confidence": { "type": "string", "enum": ["low", "medium", "high"], "description": "Model-reported reliability for this field." } }, "required": ["field", "citations", "confidence"], "additionalProperties": false }, "description": "Field-level grounding for synthesized output." } }, "required": ["content", "grounding"], "additionalProperties": false, "description": "Synthesized output. Returned when outputSchema is provided." }, "SearchStreamTextDeltaChunkOutput": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for the request." }, "type": { "type": "string", "const": "text-delta" }, "delta": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "delta": { "type": "object", "properties": { "role": { "type": "string", "const": "assistant" }, "content": { "type": "string" }, "citations": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Source URL." }, "title": { "type": "string", "description": "Source title." }, "id": { "type": "string" } }, "required": ["url", "title", "id"], "additionalProperties": false } } }, "additionalProperties": false }, "finish_reason": { "oneOf": [ { "type": "string", "const": "stop" }, { "type": "null" } ] } }, "required": ["index", "delta", "finish_reason"], "additionalProperties": false } } }, "required": ["type", "delta"], "additionalProperties": false }, "SearchStreamGroundingChunkOutput": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for the request." }, "type": { "type": "string", "const": "grounding" }, "grounding": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "Field path in output.content, for example content or companies[0].funding." }, "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 }, "description": "Sources supporting this output field." }, "confidence": { "type": "string", "enum": ["low", "medium", "high"], "description": "Model-reported reliability for this field." } }, "required": ["field", "citations", "confidence"], "additionalProperties": false }, "description": "Field-level grounding for synthesized output." }, "citations": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Source URL." }, "title": { "type": "string", "description": "Source title." }, "id": { "type": "string" } }, "required": ["url", "title", "id"], "additionalProperties": false } }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "delta": { "type": "object", "properties": { "role": { "type": "string", "const": "assistant" }, "content": { "type": "string" }, "citations": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Source URL." }, "title": { "type": "string", "description": "Source title." }, "id": { "type": "string" } }, "required": ["url", "title", "id"], "additionalProperties": false } } }, "additionalProperties": false }, "finish_reason": { "oneOf": [ { "type": "string", "const": "stop" }, { "type": "null" } ] } }, "required": ["index", "delta", "finish_reason"], "additionalProperties": false } } }, "required": ["type", "grounding"], "additionalProperties": false }, "SearchStreamResultsChunkOutput": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for the request." }, "type": { "type": "string", "const": "results" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResultOutput" } }, "warnings": { "description": "Warnings about the request, such as a field that has no effect. Log them; do not pass them to a model. Omitted when there are none.", "type": "array", "items": { "$ref": "#/components/schemas/SearchWarningOutput" } }, "notices": { "description": "Notices about how the results were produced. Pass them to your model with the results. Omitted when there are none.", "type": "array", "items": { "$ref": "#/components/schemas/SearchNoticeOutput" } } }, "required": ["type", "results"], "additionalProperties": false }, "SearchStreamResetChunkOutput": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for the request." }, "type": { "type": "string", "const": "stream-reset" }, "streamReset": { "type": "boolean", "const": true } }, "required": ["type", "streamReset"], "additionalProperties": false }, "SearchStreamDoneChunkOutput": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for the request." }, "type": { "type": "string", "const": "done" }, "output": { "anyOf": [ { "$ref": "#/components/schemas/SearchSynthesisOutputOutput" }, { "type": "null" } ] }, "searchTime": { "type": "number", "description": "Server-side processing time in milliseconds. May exclude output synthesis time, so it can be lower than end-to-end latency." }, "costDollars": { "$ref": "#/components/schemas/CostDollarsOutput" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": 0 }, "delta": { "type": "object", "properties": { "role": { "type": "string", "const": "assistant" }, "content": { "type": "string" }, "citations": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Source URL." }, "title": { "type": "string", "description": "Source title." }, "id": { "type": "string" } }, "required": ["url", "title", "id"], "additionalProperties": false } } }, "additionalProperties": false }, "finish_reason": { "oneOf": [ { "type": "string", "const": "stop" }, { "type": "null" } ] } }, "required": ["index", "delta", "finish_reason"], "additionalProperties": false } } }, "required": ["type", "output", "searchTime"], "additionalProperties": false }, "SearchStreamErrorChunkOutput": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for the request." }, "type": { "type": "string", "const": "error" }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"], "additionalProperties": false } }, "required": ["type", "error"], "additionalProperties": false }, "AnswerStreamCitationsChunkOutput": { "type": "object", "properties": { "citations": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "The title of the search result." }, "url": { "type": "string", "description": "The URL of the search result.", "format": "uri" }, "publishedDate": { "description": "An estimate of the creation date, from parsing HTML content, as an ISO 8601 date-time in UTC (`YYYY-MM-DDTHH:mm:ss.sssZ`). A date known only to the day has the time `00:00:00.000Z`.", "format": "date-time", "type": "string" }, "author": { "description": "If available, the author of the content.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "description": "The temporary ID for the document. Useful for the /contents endpoint.", "type": "string" }, "image": { "description": "The URL of an image associated with the search result, if available.", "format": "uri", "type": "string" }, "favicon": { "description": "The URL of the favicon for the search result's domain.", "format": "uri", "type": "string" }, "text": { "description": "The full text content of each source. Only present when text contents are requested.", "type": "string" } }, "required": ["title", "url"], "additionalProperties": false }, "description": "Search results cited by the final streamed answer." } }, "required": ["citations"], "additionalProperties": false }, "AnswerStreamCostChunkOutput": { "type": "object", "properties": { "costDollars": { "$ref": "#/components/schemas/CostDollarsOutput" }, "requestId": { "type": "string", "description": "Unique identifier for the request." } }, "required": ["costDollars"], "additionalProperties": false }, "AnswerStreamErrorChunkOutput": { "type": "object", "properties": { "tag": { "type": "string", "const": "ERROR" }, "payload": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": ["code", "message"], "additionalProperties": false }, "requestId": { "type": "string", "description": "Unique identifier for the request." } }, "required": ["error"], "additionalProperties": false } }, "required": ["tag", "payload"], "additionalProperties": false }, "SearchMonitorSearchOutput": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "The query string for the search." }, "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 support@exa.ai to discuss higher limits.", "default": 10 }, "includeDomains": { "description": "Restrict search results to these domains.", "type": "array", "items": { "type": "string" } }, "excludeDomains": { "description": "Exclude these domains from search results.", "type": "array", "items": { "type": "string" } }, "contents": { "$ref": "#/components/schemas/SearchMonitorContentsOutput" } }, "required": ["query"], "additionalProperties": false }, "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": 1000000, "description": "Maximum character limit for the full page text. Useful for controlling response size and API costs." }, { "type": "null" } ] }, "includeHtmlTags": { "anyOf": [ { "type": "boolean", "description": "If true, include lightweight HTML tags in returned text instead of plain markdown-style text.", "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.", "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." }, { "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." }, { "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. Set `maxAgeHours: 0` to apply `includeHtmlTags`, `verbosity`, and section filters to freshly fetched content." } ] }, "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." }, { "type": "null" } ] }, "verbosity": { "anyOf": [ { "type": "string", "enum": ["low", "medium", "high"], "description": "Preset highlight length: `low`, `medium`, and `high` allocate progressively larger token budgets for the returned highlights. With highlights.dynamic, the preset sets a single shared budget across the whole result set instead of a per-URL budget. Exact budgets are tuned by Exa and may change. Not compatible with maxCharacters or numSentences. Beta: requires the `Exa-Beta: dynamic-highlights-2026-08-28` request header; requests setting `verbosity` without it are rejected.", "x-exa-lifecycle": "beta", "x-exa-beta-flag": "dynamic-highlights-2026-08-28", "x-mint": { "post": ["Beta"] } }, { "type": "null" } ] }, "dynamic": { "anyOf": [ { "type": "boolean", "description": "Enable Dynamic Highlights (research preview): considers all results together and allocates a single shared context budget across the result set instead of a per-document budget. Not compatible with maxCharacters. Beta: requires the `Exa-Beta: dynamic-highlights-2026-08-28` request header; requests setting `dynamic` without it are rejected.", "x-exa-lifecycle": "beta", "x-exa-beta-flag": "dynamic-highlights-2026-08-28", "x-mint": { "post": ["Beta"] } }, { "type": "null" } ] }, "maxCharacters": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Maximum number of characters to return for highlights. Controls the total length of highlight text returned per URL. Not compatible with highlights.dynamic." }, { "type": "null" } ] }, "numSentences": { "anyOf": [ { "type": "integer", "minimum": 1, "description": "Deprecated. Use `maxCharacters` instead. 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.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": "maxCharacters" }, { "type": "null" } ] }, "highlightsPerUrl": { "anyOf": [ { "type": "integer", "minimum": 1, "description": "Deprecated. Currently ignored. Pass highlights: true for default highlights, or { query } to guide selection with your own query.", "x-exa-lifecycle": "deprecated", "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`.", "oneOf": [ { "type": "boolean" }, { "$ref": "#/components/schemas/SummaryWithMaxTokensOptionsOutput" } ] }, "extras": { "type": "object", "properties": { "links": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Number of URLs to return from each webpage.", "default": 0 }, { "type": "null" } ] }, "imageLinks": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Number of images to return for each result.", "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, "default": 0, "description": "Deprecated. Number of rich links to return for each result.", "x-exa-lifecycle": "deprecated", "deprecated": true }, { "type": "null" } ] }, "codeBlocks": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "default": 0, "description": "Deprecated. Number of code blocks to return for each result.", "x-exa-lifecycle": "deprecated", "deprecated": true }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Extra parameters to pass." }, "livecrawlTimeout": { "type": "integer", "exclusiveMinimum": 0, "maximum": 90000, "description": "The timeout for livecrawling in milliseconds.", "default": 10000 }, "maxAgeHours": { "type": "integer", "minimum": -1, "maximum": 720, "description": "Maximum age of cached content, in hours, up to 720. Cached content younger than this is used, and older pages are fetched fresh. `0` always fetches fresh content and `-1` always uses the cache. When omitted, cached content is used when available and pages without it are fetched live." }, "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.", "default": 0 }, "subpageTarget": { "description": "Term to find specific subpages of search results. Can be a single string or an array of strings.", "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "minItems": 0, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } } ] }, "context": { "description": "Deprecated. Use `highlights` or `text` instead. Returns page contents as a combined context string.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": ["highlights", "text"], "oneOf": [ { "type": "boolean", "description": "Deprecated. Use `highlights` or `text` instead. Returns page contents as a combined context string.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": ["highlights", "text"] }, { "type": "object", "properties": { "maxCharacters": { "type": "integer", "minimum": 1, "maximum": 1000000, "description": "Maximum character limit for the context string." } }, "additionalProperties": false, "description": "Deprecated. Use `highlights` or `text` instead. Returns page contents as a combined context string.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": ["highlights", "text"] } ] }, "livecrawl": { "description": "Deprecated. Use `maxAgeHours` instead. Does not guarantee freshly fetched content. Cannot be combined with `maxAgeHours`.", "x-exa-lifecycle": "deprecated", "deprecated": true, "x-exa-replacement": "maxAgeHours", "oneOf": [ { "type": "string", "enum": ["never", "always", "fallback", "preferred"] }, { "type": "string", "const": "auto" } ] } }, "additionalProperties": false, "description": "Content extraction options applied to each search result. All fields are optional." }, "SummaryWithMaxTokensOptionsOutput": { "type": "object", "properties": { "query": { "anyOf": [ { "type": "string", "description": "Custom query for the LLM-generated summary." }, { "type": "null" } ] }, "maxTokens": { "type": "integer", "minimum": 1, "description": "Deprecated. Maximum tokens for the generated summary.", "x-exa-lifecycle": "deprecated", "deprecated": true } }, "additionalProperties": false }, "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)." } }, "required": ["type", "period"], "additionalProperties": false }, "SearchMonitorOutputSchemaOutput": { "anyOf": [ { "oneOf": [ { "$ref": "#/components/schemas/OutputSchemaTextOutput" }, { "$ref": "#/components/schemas/OutputSchemaObject" } ], "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 except `lite` and adds about 2 seconds of synthesis latency on top of the selected search type. Object schemas are limited to 10 properties in total (nested and array items properties count toward the limit) and 2 levels of nesting, and every array must define items.", "type": "object", "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/OutputSchemaTextOutput", "object": "#/components/schemas/OutputSchemaObject" } } }, { "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." }, "OutputSchemaTextOutput": { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "description": { "type": "string" } }, "required": ["type"], "additionalProperties": false }, "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 }, "AgentDataSourceOutput": { "type": "object", "properties": { "provider": { "description": "Exa Connect data provider to enable for the run. All provider tools are available by default.", "$ref": "#/components/schemas/AgentDataSourceProvider" } }, "required": ["provider"], "additionalProperties": false }, "AgentBudgetOutput": { "type": "object", "properties": { "maxCostDollars": { "type": "number", "description": "Accepts $1 to $100. For `auto` and `ultra`, caps total run cost with default caps of $5 and $20 respectively. For fixed efforts, caps contact-enrichment calls using the budget remaining after the fixed request price, without limiting research or reasoning steps. Fixed efforts have no default cap, and an explicit cap must cover the fixed request price." }, "maxDurationSeconds": { "type": "integer", "description": "Soft wall-clock ceiling for the run in seconds. Accepts 300–10,800 (5 minutes to 3 hours) and applies only to `ultra`. As the run approaches the limit, the agent stops starting new work and returns what it has found with `stopReason: \"time_limit_reached\"`." } }, "additionalProperties": false, "description": "Per-run cost or contact-enrichment limits, depending on effort, and an `ultra` duration limit." }, "CreateWebsetParameters": { "properties": { "title": { "minLength": 1, "type": "string", "description": "Optional name that appears anywhere the Webset is displayed. Leave empty to have Exa generate one automatically.", "examples": ["Leading climate tech startups"], "nullable": true }, "search": { "properties": { "query": { "minLength": 1, "maxLength": 5000, "description": "Natural language search query describing what you are looking for.\n\nBe specific and descriptive about your requirements, characteristics, and any constraints that help narrow down the results.\n\nAny URLs provided will be crawled and used as additional context for the search.", "examples": [ "Marketing agencies based in the US, that focus on consumer products.", "AI startups in Europe that raised Series A funding in 2024", "SaaS companies with 50-200 employees in the fintech space" ], "type": "string" }, "count": { "default": 10, "description": "Number of Items the Webset will attempt to find.\n\nThe actual number of Items found may be less than this number depending on the search complexity.", "minimum": 1, "type": "number" }, "entity": { "description": "Entity the Webset returns results for. Detected from the query when omitted.", "$ref": "#/components/schemas/Entity" }, "criteria": { "description": "Criteria every Item is evaluated against. Generated from the query when omitted.", "minItems": 1, "maxItems": 5, "items": { "title": "CreateCriterionParameters", "$ref": "#/components/schemas/CreateCriterionParameters" }, "type": "array" }, "maxPeoplePerCompany": { "description": "Optional soft cap for people searches. When set, the search will try to include at most this many matching people from the same current employer company.", "minimum": 1, "type": "integer" }, "recall": { "description": "Whether to estimate how many relevant results exist for this search. The estimate is returned in the search's `recall` field.", "type": "boolean" }, "exclude": { "description": "Imports or Websets whose items are left out of this search's results.", "items": { "properties": { "source": { "enum": ["import", "webset"], "type": "string" }, "id": { "minLength": 1, "description": "The ID of the source to exclude.", "type": "string" } }, "required": ["source", "id"], "type": "object" }, "type": "array" }, "scope": { "description": "Limit the search to specific sources (existing imports or websets). Any results found within these sources matching the search criteria will be included in the Webset.", "items": { "properties": { "source": { "enum": ["import", "webset"], "type": "string" }, "id": { "minLength": 1, "description": "The ID of the source to search.", "type": "string" }, "relationship": { "properties": { "definition": { "description": "What the relationship of the entities you hope to find is relative to the entities contained in the provided source.", "type": "string" }, "limit": { "minimum": 1, "maximum": 10, "type": "number" } }, "required": ["definition", "limit"], "type": "object" } }, "required": ["source", "id"], "type": "object" }, "type": "array" } }, "required": ["query"], "description": "Create initial search for the Webset.", "type": "object" }, "import": { "description": "Import data from existing Websets and Imports into this Webset.", "items": { "properties": { "source": { "enum": ["import", "webset"], "type": "string" }, "id": { "minLength": 1, "description": "The ID of the source to import.", "type": "string" }, "evaluate": { "description": "When true, items from this import will be evaluated against the search criteria. Requires a search to be provided.", "type": "boolean" } }, "required": ["source", "id"], "type": "object" }, "type": "array" }, "enrichments": { "description": "Enrichments that extract additional data from each Item added to the Webset.", "items": { "title": "CreateEnrichmentParameters", "$ref": "#/components/schemas/CreateEnrichmentParameters" }, "type": "array" }, "exclude": { "description": "Global exclusion sources (existing imports or websets) that apply to all operations within this Webset. Any results found within these sources will be omitted across all search and import operations.", "items": { "properties": { "source": { "enum": ["import", "webset"], "type": "string" }, "id": { "minLength": 1, "description": "The ID of the source to exclude.", "type": "string" } }, "required": ["source", "id"], "type": "object" }, "type": "array" }, "externalId": { "description": "The external identifier for the webset.\n\nYou can use this to reference the Webset by your own internal identifiers.", "maxLength": 300, "type": "string" }, "metadata": { "description": "Set of key-value pairs you want to associate with this object.", "propertyNames": { "maxLength": 250, "type": "string" }, "additionalProperties": { "maxLength": 1000, "type": "string" }, "type": "object" } }, "examples": [ { "search": { "query": "Marketing agencies based in the US, that focus on consumer products.", "count": 10 } } ], "type": "object" }, "Entity": { "oneOf": [ { "$ref": "#/components/schemas/CompanyEntity" }, { "$ref": "#/components/schemas/PersonEntity" }, { "$ref": "#/components/schemas/ArticleEntity" }, { "$ref": "#/components/schemas/ResearchPaperEntity" }, { "$ref": "#/components/schemas/CustomEntity" } ] }, "CompanyEntity": { "properties": { "type": { "type": "string", "const": "company", "default": "company" } }, "required": ["type"], "title": "Company", "type": "object" }, "PersonEntity": { "properties": { "type": { "type": "string", "const": "person", "default": "person" } }, "required": ["type"], "title": "Person", "type": "object" }, "ArticleEntity": { "properties": { "type": { "type": "string", "const": "article", "default": "article" } }, "required": ["type"], "title": "Article", "type": "object" }, "ResearchPaperEntity": { "properties": { "type": { "type": "string", "const": "research_paper", "default": "research_paper" } }, "required": ["type"], "title": "Research Paper", "type": "object" }, "CustomEntity": { "properties": { "description": { "minLength": 2, "maxLength": 200, "type": "string" }, "type": { "type": "string", "const": "custom", "default": "custom" } }, "required": ["type", "description"], "title": "Custom", "type": "object" }, "CreateCriterionParameters": { "properties": { "description": { "minLength": 1, "maxLength": 1000, "description": "The description of the criterion", "type": "string" } }, "required": ["description"], "type": "object" }, "WebsetEnrichmentFormat": { "enum": ["text", "date", "number", "options", "email", "phone", "url"], "type": "string" }, "CreateEnrichmentParameters": { "properties": { "description": { "minLength": 1, "maxLength": 5000, "description": "Provide a description of the enrichment task you want to perform to each Webset Item.", "type": "string" }, "format": { "description": "Format of the enrichment response.\n\nWe automatically select the best format based on the description. If you want to explicitly specify the format, you can do so here.", "$ref": "#/components/schemas/WebsetEnrichmentFormat" }, "options": { "description": "When the format is options, the different options for the enrichment agent to choose from.", "minItems": 1, "maxItems": 150, "items": { "properties": { "label": { "description": "The label of the option", "type": "string" } }, "required": ["label"], "type": "object" }, "type": "array" }, "metadata": { "description": "Set of key-value pairs you want to associate with this object.", "propertyNames": { "maxLength": 250, "type": "string" }, "additionalProperties": { "maxLength": 1000, "type": "string" }, "type": "object" } }, "required": ["description"], "type": "object" }, "UpdateWebsetRequest": { "properties": { "metadata": { "propertyNames": { "maxLength": 250, "type": "string" }, "additionalProperties": { "maxLength": 1000, "type": "string" }, "type": "object", "description": "Set of key-value pairs you want to associate with this object.", "nullable": true }, "title": { "description": "Optional name that appears anywhere the Webset is displayed.", "examples": ["Leading climate tech startups"], "minLength": 1, "type": "string" } }, "type": "object" }, "CreateWebsetSearchParameters": { "properties": { "count": { "minimum": 1, "description": "Number of Items the Search will attempt to find.\n\nThe actual number of Items found may be less than this number depending on the query complexity.", "type": "number" }, "query": { "minLength": 1, "maxLength": 5000, "description": "Natural language search query describing what you are looking for.\n\nBe specific and descriptive about your requirements, characteristics, and any constraints that help narrow down the results.\n\nAny URLs provided will be crawled and used as additional context for the search.", "examples": [ "Marketing agencies based in the US, that focus on consumer products. Get brands worked with and city", "AI startups in Europe that raised Series A funding in 2024", "SaaS companies with 50-200 employees in the fintech space" ], "type": "string" }, "entity": { "description": "Entity the search returns results for. Detected from the query when omitted.", "$ref": "#/components/schemas/Entity" }, "criteria": { "description": "Criteria every Item is evaluated against. Generated from the query when omitted.", "minItems": 1, "maxItems": 5, "items": { "title": "CreateCriterionParameters", "$ref": "#/components/schemas/CreateCriterionParameters" }, "type": "array" }, "maxPeoplePerCompany": { "description": "Optional soft cap for people searches. When set, the search will try to include at most this many matching people from the same current employer company.", "minimum": 1, "type": "integer" }, "exclude": { "description": "Imports or Websets whose items are left out of this search's results.", "items": { "properties": { "source": { "enum": ["import", "webset"], "type": "string" }, "id": { "minLength": 1, "description": "The ID of the source to exclude.", "type": "string" } }, "required": ["source", "id"], "type": "object" }, "type": "array" }, "scope": { "description": "Limit the search to specific sources (existing imports). Any results found within these sources matching the search criteria will be included in the Webset.", "items": { "properties": { "source": { "enum": ["import", "webset"], "type": "string" }, "id": { "minLength": 1, "description": "The ID of the source to search.", "type": "string" }, "relationship": { "properties": { "definition": { "description": "What the relationship of the entities you hope to find is relative to the entities contained in the provided source.", "type": "string" }, "limit": { "minimum": 1, "maximum": 10, "type": "number" } }, "required": ["definition", "limit"], "type": "object" } }, "required": ["source", "id"], "type": "object" }, "type": "array" }, "recall": { "description": "Whether to estimate how many relevant results exist for this search. The estimate is returned in the search's `recall` field.", "type": "boolean" }, "behavior": { "default": "override", "description": "How this search interacts with existing items in the Webset:\n\n- **override**: Replace existing items and evaluate all items against new criteria\n- **append**: Add new items to existing ones, keeping items that match the new criteria", "$ref": "#/components/schemas/WebsetSearchBehavior" }, "metadata": { "description": "Set of key-value pairs you want to associate with this object.", "propertyNames": { "maxLength": 250, "type": "string" }, "additionalProperties": { "maxLength": 1000, "type": "string" }, "type": "object" } }, "required": ["count", "query"], "type": "object" }, "WebsetSearchBehavior": { "enum": ["override", "append"], "type": "string" }, "UpdateEnrichmentParameters": { "properties": { "description": { "description": "Provide a description of the enrichment task you want to perform to each Webset Item.", "minLength": 1, "maxLength": 5000, "type": "string" }, "format": { "description": "Format of the enrichment response.\n\nWe automatically select the best format based on the description. If you want to explicitly specify the format, you can do so here.", "$ref": "#/components/schemas/WebsetEnrichmentFormat" }, "options": { "description": "When the format is options, the different options for the enrichment agent to choose from.", "minItems": 1, "maxItems": 150, "items": { "properties": { "label": { "description": "The label of the option", "type": "string" } }, "required": ["label"], "type": "object" }, "type": "array" }, "metadata": { "propertyNames": { "maxLength": 250, "type": "string" }, "additionalProperties": { "maxLength": 1000, "type": "string" }, "type": "object", "description": "Set of key-value pairs you want to associate with this object.", "nullable": true } }, "type": "object" }, "PreviewWebsetParameters": { "properties": { "search": { "properties": { "query": { "minLength": 1, "maxLength": 5000, "description": "Natural language search query describing what you are looking for.\n\nBe specific and descriptive about your requirements, characteristics, and any constraints that help narrow down the results.", "examples": [ "Marketing agencies based in the US, that focus on consumer products. Get brands worked with and city", "AI startups in Europe that raised Series A funding in 2024", "SaaS companies with 50-200 employees in the fintech space" ], "type": "string" }, "entity": { "description": "Entity to search for. Detected from the query when omitted.", "$ref": "#/components/schemas/Entity" }, "count": { "default": 10, "description": "When query parameter search=true, the number of preview items to return.", "minimum": 1, "maximum": 10, "type": "number" } }, "required": ["query"], "type": "object" } }, "required": ["search"], "type": "object" }, "CreateMonitorParameters": { "properties": { "websetId": { "description": "The id of the Webset", "type": "string" }, "cadence": { "description": "How often the monitor will run", "$ref": "#/components/schemas/MonitorCadence" }, "behavior": { "description": "Behavior to perform when monitor runs", "$ref": "#/components/schemas/MonitorBehavior" }, "metadata": { "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "type": "object" } }, "required": ["websetId", "cadence", "behavior"], "type": "object" }, "MonitorCadence": { "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": { "default": "Etc/UTC", "description": "IANA timezone (e.g., \"America/New_York\")", "type": "string" } }, "required": ["cron"], "type": "object" }, "MonitorBehavior": { "properties": { "config": { "properties": { "query": { "description": "The query to search for. By default, the query from the last search is used.", "minLength": 2, "maxLength": 10000, "type": "string" }, "criteria": { "description": "The criteria to search for. By default, the criteria from the last search is used.", "maxItems": 5, "items": { "properties": { "description": { "minLength": 2, "maxLength": 1000, "type": "string" } }, "required": ["description"], "type": "object" }, "type": "array" }, "entity": { "title": "Entity", "description": "The entity to search for. By default, the entity from the last search/import is used.", "$ref": "#/components/schemas/Entity" }, "count": { "exclusiveMinimum": 0, "description": "The maximum number of results to find", "type": "number" }, "behavior": { "default": "append", "description": "The behaviour of the Search when it is added to a Webset.", "$ref": "#/components/schemas/WebsetSearchBehavior" } }, "required": ["count"], "description": "Search parameters for each Monitor run.", "type": "object" }, "type": { "type": "string", "const": "search", "default": "search", "description": "Configure the Monitor to find new Items matching your search criteria" } }, "required": ["type", "config"], "type": "object" }, "UpdateMonitor": { "properties": { "metadata": { "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "type": "object" }, "status": { "description": "The status of the monitor.", "enum": ["enabled", "disabled"], "type": "string" }, "cadence": { "$ref": "#/components/schemas/MonitorCadence" }, "behavior": { "$ref": "#/components/schemas/MonitorBehavior" } }, "type": "object" }, "CreateImportParameters": { "discriminator": { "propertyName": "format" }, "oneOf": [ { "properties": { "size": { "maximum": 50000000, "description": "The size of the file in bytes. Maximum size is 50 MB.", "type": "number" }, "count": { "description": "The number of records to import", "type": "number" }, "title": { "description": "The title of the import", "type": "string" }, "format": { "enum": ["csv"], "description": "The file format. The CSV must include a column that identifies each entity, or the import fails.", "type": "string" }, "metadata": { "description": "Set of key-value pairs you want to associate with this object.", "propertyNames": { "maxLength": 250, "type": "string" }, "additionalProperties": { "maxLength": 1000, "type": "string" }, "type": "object" }, "entity": { "description": "The type of entity each row describes.", "$ref": "#/components/schemas/Entity" }, "csv": { "description": "When format is `csv`, these are the specific import parameters.", "properties": { "identifier": { "description": "Column containing the key identifier for the entity (e.g. URL, Name, etc.). If not provided, we will try to infer it from the file.", "minimum": 0, "type": "integer" } }, "type": "object" } }, "required": ["size", "count", "format", "entity"], "type": "object" } ] }, "UpdateImport": { "properties": { "metadata": { "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "type": "object" }, "title": { "type": "string" } }, "type": "object" }, "CreateWebhookParameters": { "properties": { "events": { "minItems": 1, "maxItems": 19, "items": { "$ref": "#/components/schemas/EventType" }, "description": "The events to trigger the webhook", "type": "array" }, "url": { "format": "uri", "description": "The URL to send the webhook to", "type": "string" }, "metadata": { "description": "Set of key-value pairs you want to associate with this object.", "propertyNames": { "maxLength": 250, "type": "string" }, "additionalProperties": { "maxLength": 1000, "type": "string" }, "type": "object" } }, "required": ["events", "url"], "type": "object" }, "EventType": { "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" ], "type": "string" }, "UpdateWebhookParameters": { "properties": { "events": { "description": "The events to trigger the webhook", "minItems": 1, "maxItems": 19, "items": { "$ref": "#/components/schemas/EventType" }, "type": "array" }, "url": { "description": "The URL to send the webhook to", "format": "uri", "type": "string" }, "metadata": { "description": "Set of key-value pairs you want to associate with this object.", "propertyNames": { "maxLength": 250, "type": "string" }, "additionalProperties": { "maxLength": 1000, "type": "string" }, "type": "object" } }, "type": "object" }, "Webset": { "properties": { "id": { "description": "The unique identifier for the webset", "type": "string" }, "object": { "const": "webset", "default": "webset", "description": "The type of object", "type": "string" }, "status": { "enum": ["idle", "pending", "running", "paused"], "description": "The status of the webset", "title": "WebsetStatus", "type": "string" }, "externalId": { "type": "string", "description": "The external identifier for the webset", "nullable": true }, "title": { "type": "string", "description": "The title of the webset", "nullable": true }, "searches": { "items": { "$ref": "#/components/schemas/WebsetSearch" }, "description": "The searches that have been performed on the webset.", "type": "array" }, "imports": { "items": { "$ref": "#/components/schemas/Import" }, "description": "Imports that have been performed on the webset.", "type": "array" }, "enrichments": { "items": { "$ref": "#/components/schemas/WebsetEnrichment" }, "description": "The Enrichments to apply to the Webset Items.", "type": "array" }, "monitors": { "items": { "$ref": "#/components/schemas/Monitor" }, "description": "The Monitors for the Webset.", "type": "array" }, "excludes": { "description": "The Excludes sources (existing imports or websets) that apply to all operations within this Webset. Any results found within these sources will be omitted across all search and import operations.", "items": { "properties": { "source": { "enum": ["import", "webset"], "type": "string" }, "id": { "type": "string" } }, "required": ["source", "id"], "type": "object" }, "type": "array" }, "metadata": { "default": {}, "description": "Set of key-value pairs you want to associate with this object.", "propertyNames": { "maxLength": 250, "type": "string" }, "additionalProperties": { "maxLength": 1000, "type": "string" }, "type": "object" }, "dashboardUrl": { "format": "uri", "description": "The URL to view the webset in the Exa dashboard", "type": "string" }, "createdAt": { "format": "date-time", "description": "The date and time the webset was created", "type": "string" }, "updatedAt": { "format": "date-time", "description": "The date and time the webset was updated", "type": "string" } }, "required": [ "id", "object", "status", "externalId", "title", "searches", "imports", "enrichments", "monitors", "dashboardUrl", "createdAt", "updatedAt" ], "type": "object" }, "WebsetSearch": { "properties": { "id": { "description": "The unique identifier for the search", "type": "string" }, "object": { "const": "webset_search", "default": "webset_search", "description": "The type of object", "type": "string" }, "websetId": { "description": "The unique identifier for the Webset this search belongs to", "type": "string" }, "status": { "enum": ["created", "pending", "running", "completed", "canceled"], "description": "The status of the search", "title": "WebsetSearchStatus", "type": "string" }, "query": { "minLength": 1, "maxLength": 5000, "description": "The query used to create the search.", "type": "string" }, "entity": { "$ref": "#/components/schemas/Entity", "description": "The entity the search will return results for.\n\nWhen no entity is provided during creation, we will automatically select the best entity based on the query.", "nullable": true }, "criteria": { "items": { "properties": { "description": { "minLength": 1, "maxLength": 1000, "description": "The description of the criterion", "type": "string" }, "successRate": { "minimum": 0, "maximum": 100, "description": "Value between 0 and 100 representing the percentage of results that meet the criterion.", "type": "number" } }, "required": ["description", "successRate"], "type": "object" }, "description": "The criteria the search will use to evaluate the results. If not provided, we will automatically generate them for you.", "type": "array" }, "count": { "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.", "type": "number" }, "maxPeoplePerCompany": { "minimum": 1, "type": "integer", "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", "description": "The behavior of the search when it is added to a Webset.\n\n- `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.\n- `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.", "$ref": "#/components/schemas/WebsetSearchBehavior" }, "exclude": { "items": { "properties": { "source": { "enum": ["import", "webset"], "type": "string" }, "id": { "type": "string" } }, "required": ["source", "id"], "type": "object" }, "description": "Sources (existing imports or websets) used to omit certain results to be found during the search.", "type": "array" }, "scope": { "items": { "properties": { "source": { "enum": ["import", "webset"], "type": "string" }, "id": { "type": "string" }, "relationship": { "properties": { "definition": { "description": "What the relationship of the entities you hope to find is relative to the entities contained in the provided source.", "type": "string" }, "limit": { "minimum": 1, "maximum": 10, "type": "number" } }, "required": ["definition", "limit"], "type": "object" } }, "required": ["source", "id"], "type": "object" }, "description": "Sources the search is limited to. Empty when the search covers the whole web.", "type": "array" }, "progress": { "properties": { "found": { "description": "The number of results found so far", "type": "number" }, "analyzed": { "description": "The number of results analyzed so far", "type": "number" }, "completion": { "minimum": 0, "maximum": 100, "description": "The completion percentage of the search", "type": "number" }, "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", "type": "object" }, "recall": { "properties": { "expected": { "properties": { "total": { "description": "The estimated total number of potential matches", "type": "number" }, "confidence": { "enum": ["high", "medium", "low"], "description": "The confidence in the estimate", "type": "string" }, "bounds": { "properties": { "min": { "description": "The minimum estimated total number of potential matches", "type": "number" }, "max": { "description": "The maximum estimated total number of potential matches", "type": "number" } }, "required": ["min", "max"], "type": "object" } }, "required": ["total", "confidence", "bounds"], "type": "object" }, "reasoning": { "description": "The reasoning for the estimate", "type": "string" } }, "required": ["expected", "reasoning"], "type": "object", "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.", "propertyNames": { "maxLength": 250, "type": "string" }, "additionalProperties": { "maxLength": 1000, "type": "string" }, "type": "object" }, "canceledAt": { "format": "date-time", "type": "string", "description": "The date and time the search was canceled", "nullable": true }, "canceledReason": { "$ref": "#/components/schemas/WebsetSearchCanceledReason", "description": "The reason the search was canceled", "nullable": true }, "createdAt": { "format": "date-time", "description": "The date and time the search was created", "type": "string" }, "updatedAt": { "format": "date-time", "description": "The date and time the search was updated", "type": "string" } }, "required": [ "id", "object", "websetId", "status", "query", "entity", "criteria", "count", "maxPeoplePerCompany", "exclude", "scope", "progress", "recall", "canceledAt", "canceledReason", "createdAt", "updatedAt" ], "type": "object" }, "WebsetSearchCanceledReason": { "enum": ["webset_deleted", "webset_canceled", "out_of_credits"], "type": "string" }, "Import": { "properties": { "id": { "description": "The unique identifier for the Import", "type": "string" }, "object": { "enum": ["import"], "description": "The type of object", "type": "string" }, "status": { "enum": ["pending", "processing", "completed", "failed", "canceled"], "description": "The status of the Import", "type": "string" }, "format": { "enum": ["csv", "webset"], "description": "The format of the import.", "type": "string" }, "entity": { "$ref": "#/components/schemas/Entity", "description": "The type of entity the import contains.", "nullable": true }, "title": { "description": "The title of the import", "type": "string" }, "count": { "description": "The number of entities in the import", "type": "number" }, "metadata": { "propertyNames": { "maxLength": 250, "type": "string" }, "additionalProperties": { "maxLength": 1000, "type": "string" }, "description": "Set of key-value pairs you want to associate with this object.", "type": "object" }, "failedReason": { "enum": ["invalid_format", "invalid_file_content", "missing_identifier"], "type": "string", "description": "The reason the import failed", "nullable": true }, "failedAt": { "format": "date-time", "type": "string", "description": "When the import failed", "nullable": true }, "failedMessage": { "type": "string", "description": "A human readable message of the import failure", "nullable": true }, "createdAt": { "format": "date-time", "description": "When the import was created", "type": "string" }, "updatedAt": { "format": "date-time", "description": "When the import was last updated", "type": "string" } }, "required": [ "id", "object", "status", "format", "entity", "title", "count", "metadata", "failedReason", "failedAt", "failedMessage", "createdAt", "updatedAt" ], "type": "object" }, "WebsetEnrichment": { "properties": { "id": { "description": "The unique identifier for the enrichment", "type": "string" }, "object": { "const": "webset_enrichment", "default": "webset_enrichment", "description": "The type of object", "type": "string" }, "status": { "enum": ["pending", "canceled", "completed"], "description": "The status of the enrichment", "title": "WebsetEnrichmentStatus", "type": "string" }, "websetId": { "description": "The unique identifier for the Webset this enrichment belongs to.", "type": "string" }, "title": { "type": "string", "description": "The title of the enrichment.\n\nThis will be automatically generated based on the description and format.", "nullable": true }, "description": { "description": "The description of the enrichment task provided during the creation of the enrichment.", "type": "string" }, "format": { "$ref": "#/components/schemas/WebsetEnrichmentFormat", "description": "The format of the enrichment response.", "nullable": true }, "options": { "items": { "properties": { "label": { "description": "The label of the option", "type": "string" } }, "required": ["label"], "type": "object" }, "type": "array", "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.\n\nThis will be automatically generated based on the description and format.", "nullable": true }, "metadata": { "default": {}, "description": "The metadata of the enrichment", "propertyNames": { "maxLength": 250, "type": "string" }, "additionalProperties": { "maxLength": 1000, "type": "string" }, "type": "object" }, "createdAt": { "format": "date-time", "description": "The date and time the enrichment was created", "type": "string" }, "updatedAt": { "format": "date-time", "description": "The date and time the enrichment was updated", "type": "string" } }, "required": [ "id", "object", "status", "websetId", "title", "description", "format", "options", "instructions", "createdAt", "updatedAt" ], "type": "object" }, "Monitor": { "properties": { "id": { "description": "The unique identifier for the Monitor", "type": "string" }, "object": { "enum": ["monitor"], "description": "The type of object", "type": "string" }, "status": { "enum": ["enabled", "disabled"], "description": "The status of the Monitor", "type": "string" }, "websetId": { "description": "The id of the Webset the Monitor belongs to", "type": "string" }, "cadence": { "description": "How often the monitor will run", "$ref": "#/components/schemas/MonitorCadence" }, "behavior": { "description": "Behavior to perform when monitor runs", "$ref": "#/components/schemas/MonitorBehavior" }, "lastRun": { "$ref": "#/components/schemas/MonitorRun", "title": "MonitorRun", "description": "The last run of the monitor", "nullable": true }, "nextRunAt": { "format": "date-time", "type": "string", "description": "Date and time when the next run will occur in", "nullable": true }, "metadata": { "propertyNames": { "maxLength": 250, "type": "string" }, "additionalProperties": { "maxLength": 1000, "type": "string" }, "description": "Set of key-value pairs you want to associate with this object.", "type": "object" }, "createdAt": { "format": "date-time", "description": "When the monitor was created", "type": "string" }, "updatedAt": { "format": "date-time", "description": "When the monitor was last updated", "type": "string" } }, "required": [ "id", "object", "status", "websetId", "cadence", "behavior", "lastRun", "nextRunAt", "metadata", "createdAt", "updatedAt" ], "type": "object" }, "MonitorRun": { "properties": { "id": { "description": "The unique identifier for the Monitor Run", "type": "string" }, "object": { "enum": ["monitor_run"], "description": "The type of object", "type": "string" }, "monitorId": { "description": "The monitor that the run is associated with", "type": "string" }, "status": { "enum": ["created", "running", "completed", "canceled", "failed"], "description": "The status of the Monitor Run", "type": "string" }, "completedAt": { "format": "date-time", "type": "string", "description": "When the run completed", "nullable": true }, "failedAt": { "format": "date-time", "type": "string", "description": "When the run failed", "nullable": true }, "failedReason": { "type": "string", "description": "The reason the run failed", "nullable": true }, "canceledAt": { "format": "date-time", "type": "string", "description": "When the run was canceled", "nullable": true }, "createdAt": { "format": "date-time", "description": "When the run was created", "type": "string" }, "updatedAt": { "format": "date-time", "description": "When the run was last updated", "type": "string" }, "type": { "type": "string", "enum": ["search", "refresh"], "description": "The type of the Monitor Run" } }, "required": [ "id", "object", "monitorId", "status", "type", "completedAt", "failedAt", "failedReason", "canceledAt", "createdAt", "updatedAt" ], "type": "object" }, "ListWebsetsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Webset" }, "description": "The list of websets", "type": "array" }, "hasMore": { "description": "Whether there are more results to paginate through", "type": "boolean" }, "nextCursor": { "type": "string", "description": "The cursor to paginate through the next set of results", "nullable": true } }, "required": ["data", "hasMore", "nextCursor"], "type": "object" }, "GetWebsetResponse": { "allOf": [ { "$ref": "#/components/schemas/Webset" }, { "properties": { "items": { "description": "When expand query parameter contains `items`, this will contain the items in the webset", "items": { "$ref": "#/components/schemas/WebsetItem" }, "type": "array" } }, "type": "object" } ] }, "WebsetItem": { "properties": { "id": { "description": "The unique identifier for the Webset Item", "type": "string" }, "object": { "const": "webset_item", "default": "webset_item", "description": "The type of object", "type": "string" }, "source": { "enum": ["search", "import"], "description": "The source of the Item", "type": "string" }, "sourceId": { "description": "The unique identifier for the source", "type": "string" }, "sourceEntityId": { "description": "The original identifier used to resolve this item (e.g., email, name, or URL). Only relevant when the source is import.", "type": "string" }, "scopeId": { "description": "The import that sourced this item, when the item came from a scoped search with evaluate enabled on the import.", "type": "string" }, "websetId": { "description": "The unique identifier for the Webset this Item belongs to.", "type": "string" }, "properties": { "description": "The properties of the Item", "oneOf": [ { "$ref": "#/components/schemas/WebsetItemPersonProperties" }, { "$ref": "#/components/schemas/WebsetItemCompanyProperties" }, { "$ref": "#/components/schemas/WebsetItemArticleProperties" }, { "$ref": "#/components/schemas/WebsetItemResearchPaperProperties" }, { "$ref": "#/components/schemas/WebsetItemCustomProperties" } ] }, "evaluations": { "items": { "$ref": "#/components/schemas/WebsetItemEvaluation" }, "description": "The criteria evaluations of the item", "type": "array" }, "enrichments": { "items": { "$ref": "#/components/schemas/EnrichmentResult" }, "type": "array", "description": "The enrichments results of the Webset item", "nullable": true }, "createdAt": { "format": "date-time", "description": "The date and time the item was created", "type": "string" }, "updatedAt": { "format": "date-time", "description": "The date and time the item was last updated", "type": "string" } }, "required": [ "id", "object", "source", "sourceId", "websetId", "properties", "evaluations", "enrichments", "createdAt", "updatedAt" ], "type": "object" }, "WebsetItemPersonProperties": { "properties": { "url": { "format": "uri", "description": "The URL of the person profile", "type": "string" }, "description": { "description": "Short description of the relevance of the person", "type": "string" }, "person": { "properties": { "name": { "description": "The name of the person", "type": "string" }, "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": { "properties": { "name": { "description": "The name of the company", "type": "string" }, "location": { "type": "string", "description": "The location the person is working at the company", "nullable": true } }, "required": ["name", "location"], "type": "object", "title": "WebsetItemPersonCompanyPropertiesFields", "nullable": true }, "pictureUrl": { "format": "uri", "type": "string", "description": "The image URL of the person", "nullable": true }, "workHistory": { "items": { "properties": { "title": { "type": "string", "description": "Job title or position", "nullable": true }, "location": { "type": "string", "description": "Work location", "nullable": true }, "dates": { "properties": { "from": { "type": "string", "description": "Start date", "nullable": true }, "to": { "type": "string", "description": "End date", "nullable": true } }, "required": ["from", "to"], "type": "object", "title": "WebsetItemPersonDateRange", "description": "Employment dates", "nullable": true }, "company": { "properties": { "id": { "type": "string", "description": "Entity ID of the company", "nullable": true }, "name": { "type": "string", "description": "Company name", "nullable": true }, "linkedinUrl": { "type": "string", "description": "LinkedIn URL of the company", "nullable": true } }, "required": ["id", "name", "linkedinUrl"], "type": "object", "title": "WebsetItemPersonWorkHistoryCompanyRef", "nullable": true } }, "required": ["title", "location", "dates", "company"], "title": "WebsetItemPersonWorkHistoryEntry", "type": "object" }, "description": "The work history of the person", "type": "array" }, "educationHistory": { "items": { "properties": { "degree": { "type": "string", "description": "Degree obtained", "nullable": true }, "dates": { "properties": { "from": { "type": "string", "description": "Start date", "nullable": true }, "to": { "type": "string", "description": "End date", "nullable": true } }, "required": ["from", "to"], "type": "object", "title": "WebsetItemPersonDateRange", "description": "Education dates", "nullable": true }, "institution": { "properties": { "id": { "type": "string", "description": "Entity ID of the institution", "nullable": true }, "name": { "type": "string", "description": "Institution name", "nullable": true }, "linkedinUrl": { "type": "string", "description": "LinkedIn URL of the institution", "nullable": true } }, "required": ["id", "name", "linkedinUrl"], "type": "object", "title": "WebsetItemPersonEducationInstitutionRef", "nullable": true } }, "required": ["degree", "dates", "institution"], "title": "WebsetItemPersonEducationHistoryEntry", "type": "object" }, "description": "The education history of the person", "type": "array" } }, "required": [ "name", "location", "position", "company", "pictureUrl", "workHistory", "educationHistory" ], "title": "WebsetItemPersonPropertiesFields", "type": "object" }, "type": { "type": "string", "const": "person", "default": "person" } }, "required": ["type", "url", "description", "person"], "title": "Person", "type": "object" }, "WebsetItemCompanyProperties": { "properties": { "url": { "format": "uri", "description": "The URL of the company website", "type": "string" }, "description": { "description": "Short description of the relevance of the company", "type": "string" }, "content": { "type": "string", "description": "The text content of the company website", "nullable": true }, "company": { "properties": { "name": { "description": "The name of the company", "type": "string" }, "location": { "type": "string", "description": "The main location of the company", "nullable": true }, "employees": { "type": "integer", "description": "The number of employees of the company", "nullable": true }, "industry": { "type": "string", "description": "The industry of the company", "nullable": true }, "about": { "type": "string", "description": "A short description of the company", "nullable": true }, "logoUrl": { "format": "uri", "type": "string", "description": "The logo URL of the company", "nullable": true }, "foundedYear": { "type": "number", "description": "The year the company was founded", "nullable": true }, "headquarters": { "properties": { "address": { "type": "string", "description": "The street address of the headquarters", "nullable": true }, "city": { "type": "string", "description": "The city of the headquarters", "nullable": true }, "state": { "type": "string", "description": "The state or region of the headquarters", "nullable": true }, "postalCode": { "type": "string", "description": "The postal code of the headquarters", "nullable": true }, "country": { "type": "string", "description": "The country of the headquarters", "nullable": true }, "countryCode": { "type": "string", "description": "The ISO country code of the headquarters", "nullable": true } }, "required": ["address", "city", "state", "postalCode", "country", "countryCode"], "type": "object", "title": "WebsetItemCompanyHeadquarters", "description": "The structured headquarters address of the company", "nullable": true }, "financials": { "properties": { "revenueAnnual": { "type": "number", "description": "The annual revenue of the company (USD)", "nullable": true }, "fundingTotal": { "type": "number", "description": "The total funding raised by the company (USD)", "nullable": true }, "fundingLatestRound": { "properties": { "name": { "type": "string", "description": "The name of the funding round (e.g. Series A)", "nullable": true }, "date": { "type": "string", "description": "The date of the funding round", "nullable": true }, "amount": { "type": "number", "description": "The amount raised in the funding round (USD)", "nullable": true } }, "required": ["name", "date", "amount"], "type": "object", "title": "WebsetItemCompanyFundingRound", "description": "The latest funding round", "nullable": true } }, "required": ["revenueAnnual", "fundingTotal", "fundingLatestRound"], "type": "object", "title": "WebsetItemCompanyFinancials", "description": "Financial information about the company", "nullable": true }, "webTraffic": { "properties": { "visitsMonthly": { "type": "number", "description": "The estimated monthly website visits", "nullable": true }, "uniqueVisitors": { "type": "number", "description": "The estimated monthly unique visitors", "nullable": true } }, "required": ["visitsMonthly", "uniqueVisitors"], "type": "object", "title": "WebsetItemCompanyWebTraffic", "description": "Web traffic metrics for the company", "nullable": true } }, "required": [ "name", "location", "employees", "industry", "about", "logoUrl", "foundedYear", "headquarters", "financials", "webTraffic" ], "title": "WebsetItemCompanyPropertiesFields", "type": "object" }, "type": { "type": "string", "const": "company", "default": "company" } }, "required": ["type", "url", "description", "content", "company"], "title": "Company", "type": "object" }, "WebsetItemArticleProperties": { "properties": { "url": { "format": "uri", "description": "The URL of the article", "type": "string" }, "description": { "description": "Short description of the relevance of the article", "type": "string" }, "content": { "type": "string", "description": "The text content for the article", "nullable": true }, "article": { "properties": { "title": { "type": "string", "description": "The title of the article", "nullable": true }, "author": { "type": "string", "description": "The author(s) of the article", "nullable": true }, "publishedAt": { "type": "string", "description": "The date and time the article was published", "nullable": true } }, "required": ["title", "author", "publishedAt"], "title": "WebsetItemArticlePropertiesFields", "type": "object" }, "type": { "type": "string", "const": "article", "default": "article" } }, "required": ["type", "url", "description", "content", "article"], "title": "Article", "type": "object" }, "WebsetItemResearchPaperProperties": { "properties": { "url": { "format": "uri", "description": "The URL of the research paper", "type": "string" }, "description": { "description": "Short description of the relevance of the research paper", "type": "string" }, "content": { "type": "string", "description": "The text content of the research paper", "nullable": true }, "researchPaper": { "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", "type": "object" }, "type": { "type": "string", "const": "research_paper", "default": "research_paper" } }, "required": ["type", "url", "description", "content", "researchPaper"], "title": "Research Paper", "type": "object" }, "WebsetItemCustomProperties": { "properties": { "url": { "format": "uri", "description": "The URL of the Item", "type": "string" }, "description": { "description": "Short description of the Item", "type": "string" }, "content": { "type": "string", "description": "The text content of the Item", "nullable": true }, "custom": { "properties": { "title": { "type": "string", "description": "The title of the website", "nullable": true }, "author": { "type": "string", "description": "The author(s) of the website", "nullable": true }, "publishedAt": { "type": "string", "description": "The date and time the website was published", "nullable": true } }, "required": ["title", "author", "publishedAt"], "title": "WebsetItemCustomPropertiesFields", "type": "object" }, "type": { "type": "string", "const": "custom", "default": "custom" } }, "required": ["type", "url", "description", "content", "custom"], "title": "Custom", "type": "object" }, "WebsetItemEvaluation": { "properties": { "criterion": { "description": "The description of the criterion", "type": "string" }, "reasoning": { "description": "The reasoning for the result of the evaluation", "type": "string" }, "satisfied": { "enum": ["yes", "no", "unclear"], "description": "The satisfaction of the criterion", "type": "string" }, "references": { "default": [], "description": "The references used to generate the result.", "items": { "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": { "format": "uri", "description": "The URL of the reference", "type": "string" } }, "required": ["title", "snippet", "url"], "type": "object" }, "type": "array" } }, "required": ["criterion", "reasoning", "satisfied"], "type": "object" }, "EnrichmentResult": { "properties": { "object": { "const": "enrichment_result", "default": "enrichment_result", "description": "The type of object", "type": "string" }, "status": { "enum": ["pending", "completed", "canceled"], "description": "The status of the enrichment result.", "type": "string" }, "format": { "$ref": "#/components/schemas/WebsetEnrichmentFormat" }, "result": { "items": { "type": "string" }, "type": "array", "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": { "items": { "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": { "format": "uri", "description": "The URL of the reference", "type": "string" } }, "required": ["title", "snippet", "url"], "type": "object" }, "description": "The references used to generate the result.", "type": "array" }, "enrichmentId": { "description": "The id of the Enrichment that generated the result", "type": "string" } }, "required": [ "object", "status", "format", "result", "reasoning", "references", "enrichmentId" ], "type": "object" }, "ListWebsetItemResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/WebsetItem" }, "description": "The list of webset items", "type": "array" }, "hasMore": { "description": "Whether there are more Items to paginate through", "type": "boolean" }, "nextCursor": { "type": "string", "description": "The cursor to paginate through the next set of Items", "nullable": true } }, "required": ["data", "hasMore", "nextCursor"], "type": "object" }, "PreviewWebsetResponse": { "properties": { "search": { "properties": { "entity": { "description": "Detected entity from the query.", "oneOf": [ { "$ref": "#/components/schemas/CompanyEntity" }, { "$ref": "#/components/schemas/PersonEntity" }, { "$ref": "#/components/schemas/ArticleEntity" }, { "$ref": "#/components/schemas/ResearchPaperEntity" }, { "$ref": "#/components/schemas/CustomEntity" } ] }, "criteria": { "items": { "properties": { "description": { "type": "string" } }, "required": ["description"], "type": "object" }, "description": "Detected criteria from the query.", "type": "array" } }, "required": ["entity", "criteria"], "type": "object" }, "enrichments": { "items": { "properties": { "description": { "description": "Description of the enrichment.", "type": "string" }, "format": { "enum": ["text", "date", "number", "options", "email", "phone", "url"], "description": "Format of the enrichment.", "type": "string" }, "options": { "description": "When format is options, the options detected from the query.", "items": { "properties": { "label": { "description": "Label of the option.", "type": "string" } }, "required": ["label"], "type": "object" }, "type": "array" } }, "required": ["description", "format"], "type": "object" }, "description": "Detected enrichments from the query.", "type": "array" }, "items": { "items": { "$ref": "#/components/schemas/WebsetItemPreview" }, "description": "Preview items matching the search criteria.", "type": "array" } }, "required": ["search", "enrichments", "items"], "type": "object" }, "WebsetItemPreview": { "properties": { "id": { "description": "The unique identifier for the preview item", "type": "string" }, "properties": { "description": "The properties of the preview item", "oneOf": [ { "$ref": "#/components/schemas/WebsetItemPersonProperties" }, { "$ref": "#/components/schemas/WebsetItemCompanyProperties" }, { "$ref": "#/components/schemas/WebsetItemArticleProperties" }, { "$ref": "#/components/schemas/WebsetItemResearchPaperProperties" }, { "$ref": "#/components/schemas/WebsetItemCustomProperties" } ] }, "createdAt": { "format": "date-time", "description": "The date and time the preview was created", "type": "string" } }, "required": ["id", "properties", "createdAt"], "type": "object" }, "ListMonitorsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Monitor" }, "description": "The list of monitors", "type": "array" }, "hasMore": { "description": "Whether there are more results to paginate through", "type": "boolean" }, "nextCursor": { "type": "string", "description": "The cursor to paginate through the next set of results", "nullable": true } }, "required": ["data", "hasMore", "nextCursor"], "type": "object" }, "ListMonitorRunsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/MonitorRun" }, "description": "The list of monitor runs", "type": "array" }, "hasMore": { "description": "Whether there are more results to paginate through", "type": "boolean" }, "nextCursor": { "type": "string", "description": "The cursor to paginate through the next set of results", "nullable": true } }, "required": ["data", "hasMore", "nextCursor"], "type": "object" }, "CreateImportResponse": { "properties": { "id": { "description": "The unique identifier for the Import", "type": "string" }, "object": { "enum": ["import"], "description": "The type of object", "type": "string" }, "status": { "enum": ["pending", "processing", "completed", "failed", "canceled"], "description": "The status of the Import", "type": "string" }, "format": { "enum": ["csv", "webset"], "description": "The format of the import.", "type": "string" }, "entity": { "$ref": "#/components/schemas/Entity", "description": "The type of entity the import contains.", "nullable": true }, "title": { "description": "The title of the import", "type": "string" }, "count": { "description": "The number of entities in the import", "type": "number" }, "metadata": { "propertyNames": { "maxLength": 250, "type": "string" }, "additionalProperties": { "maxLength": 1000, "type": "string" }, "description": "Set of key-value pairs you want to associate with this object.", "type": "object" }, "failedReason": { "enum": ["invalid_format", "invalid_file_content", "missing_identifier"], "type": "string", "description": "The reason the import failed", "nullable": true }, "failedAt": { "format": "date-time", "type": "string", "description": "When the import failed", "nullable": true }, "failedMessage": { "type": "string", "description": "A human readable message of the import failure", "nullable": true }, "createdAt": { "format": "date-time", "description": "When the import was created", "type": "string" }, "updatedAt": { "format": "date-time", "description": "When the import was last updated", "type": "string" }, "uploadUrl": { "description": "The URL to upload the file to", "type": "string" }, "uploadValidUntil": { "description": "The date and time until the upload URL is valid. The upload URL will be valid for 1 hour.", "type": "string" } }, "required": [ "id", "object", "status", "format", "entity", "title", "count", "metadata", "failedReason", "failedAt", "failedMessage", "createdAt", "updatedAt", "uploadUrl", "uploadValidUntil" ], "description": "An Import with the URL to upload your file to.", "type": "object" }, "ListImportsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Import" }, "description": "The list of imports", "type": "array" }, "hasMore": { "description": "Whether there are more results to paginate through", "type": "boolean" }, "nextCursor": { "type": "string", "description": "The cursor to paginate through the next set of results", "nullable": true } }, "required": ["data", "hasMore", "nextCursor"], "type": "object" }, "Webhook": { "properties": { "id": { "description": "The unique identifier for the webhook", "type": "string" }, "object": { "const": "webhook", "default": "webhook", "description": "The type of object", "type": "string" }, "status": { "enum": ["active", "inactive"], "title": "WebhookStatus", "description": "The status of the webhook", "type": "string" }, "events": { "minItems": 1, "items": { "$ref": "#/components/schemas/EventType" }, "description": "The events to trigger the webhook", "type": "array" }, "url": { "format": "uri", "description": "The URL to send the webhook to", "type": "string" }, "secret": { "type": "string", "description": "The secret to verify the webhook signature. Only returned on Webhook creation.", "nullable": true }, "metadata": { "default": {}, "description": "The metadata of the webhook", "propertyNames": { "maxLength": 250, "type": "string" }, "additionalProperties": { "maxLength": 1000, "type": "string" }, "type": "object" }, "createdAt": { "format": "date-time", "description": "The date and time the webhook was created", "type": "string" }, "updatedAt": { "format": "date-time", "description": "The date and time the webhook was last updated", "type": "string" } }, "required": ["id", "object", "status", "events", "url", "secret", "createdAt", "updatedAt"], "type": "object" }, "ListWebhooksResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Webhook" }, "description": "The list of webhooks", "type": "array" }, "hasMore": { "description": "Whether there are more results to paginate through", "type": "boolean" }, "nextCursor": { "type": "string", "description": "The cursor to paginate through the next set of results", "nullable": true } }, "required": ["data", "hasMore", "nextCursor"], "type": "object" }, "ListWebhookAttemptsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/WebhookAttempt" }, "description": "The list of webhook attempts", "type": "array" }, "hasMore": { "description": "Whether there are more results to paginate through", "type": "boolean" }, "nextCursor": { "type": "string", "description": "The cursor to paginate through the next set of results", "nullable": true } }, "required": ["data", "hasMore", "nextCursor"], "type": "object" }, "WebhookAttempt": { "properties": { "id": { "description": "The unique identifier for the webhook attempt", "type": "string" }, "object": { "const": "webhook_attempt", "default": "webhook_attempt", "description": "The type of object", "type": "string" }, "eventId": { "description": "The unique identifier for the event", "type": "string" }, "eventType": { "description": "The type of event", "$ref": "#/components/schemas/EventType" }, "webhookId": { "description": "The unique identifier for the webhook", "type": "string" }, "url": { "description": "The URL that was used during the attempt", "type": "string" }, "successful": { "description": "Whether the attempt was successful", "type": "boolean" }, "responseHeaders": { "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "The headers of the response", "type": "object" }, "responseBody": { "type": "string", "description": "The body of the response", "nullable": true }, "responseStatusCode": { "description": "The status code of the response", "type": "number" }, "attempt": { "description": "The attempt number of the webhook", "type": "number" }, "attemptedAt": { "format": "date-time", "description": "The date and time the webhook attempt was made", "type": "string" } }, "required": [ "id", "object", "eventId", "eventType", "webhookId", "url", "successful", "responseHeaders", "responseBody", "responseStatusCode", "attempt", "attemptedAt" ], "type": "object" }, "ListEventsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Event", "discriminator": { "propertyName": "type" } }, "description": "The list of events", "type": "array" }, "hasMore": { "description": "Whether there are more results to paginate through", "type": "boolean" }, "nextCursor": { "type": "string", "description": "The cursor to paginate through the next set of results", "nullable": true } }, "required": ["data", "hasMore", "nextCursor"], "type": "object" }, "Event": { "title": "Event", "discriminator": { "propertyName": "type" }, "oneOf": [ { "properties": { "id": { "description": "The unique identifier for the event", "type": "string" }, "object": { "const": "event", "default": "event", "description": "The type of object", "type": "string" }, "data": { "$ref": "#/components/schemas/Webset" }, "createdAt": { "format": "date-time", "description": "The date and time the event was created", "type": "string" }, "type": { "type": "string", "const": "webset.created", "default": "webset.created", "description": "The type of event" } }, "required": ["id", "object", "type", "data", "createdAt"], "title": "WebsetCreatedEvent", "type": "object" }, { "properties": { "id": { "description": "The unique identifier for the event", "type": "string" }, "object": { "const": "event", "default": "event", "description": "The type of object", "type": "string" }, "data": { "$ref": "#/components/schemas/Webset" }, "createdAt": { "format": "date-time", "description": "The date and time the event was created", "type": "string" }, "type": { "type": "string", "const": "webset.deleted", "default": "webset.deleted", "description": "The type of event" } }, "required": ["id", "object", "type", "data", "createdAt"], "title": "WebsetDeletedEvent", "type": "object" }, { "properties": { "id": { "description": "The unique identifier for the event", "type": "string" }, "object": { "const": "event", "default": "event", "description": "The type of object", "type": "string" }, "data": { "$ref": "#/components/schemas/Webset" }, "createdAt": { "format": "date-time", "description": "The date and time the event was created", "type": "string" }, "type": { "type": "string", "const": "webset.idle", "default": "webset.idle", "description": "The type of event" } }, "required": ["id", "object", "type", "data", "createdAt"], "title": "WebsetIdleEvent", "type": "object" }, { "properties": { "id": { "description": "The unique identifier for the event", "type": "string" }, "object": { "const": "event", "default": "event", "description": "The type of object", "type": "string" }, "data": { "$ref": "#/components/schemas/Webset" }, "createdAt": { "format": "date-time", "description": "The date and time the event was created", "type": "string" }, "type": { "type": "string", "const": "webset.paused", "default": "webset.paused", "description": "The type of event" } }, "required": ["id", "object", "type", "data", "createdAt"], "title": "WebsetPausedEvent", "type": "object" }, { "properties": { "id": { "description": "The unique identifier for the event", "type": "string" }, "object": { "const": "event", "default": "event", "description": "The type of object", "type": "string" }, "data": { "$ref": "#/components/schemas/WebsetItem" }, "createdAt": { "format": "date-time", "description": "The date and time the event was created", "type": "string" }, "type": { "type": "string", "const": "webset.item.created", "default": "webset.item.created", "description": "The type of event" } }, "required": ["id", "object", "type", "data", "createdAt"], "title": "WebsetItemCreatedEvent", "type": "object" }, { "properties": { "id": { "description": "The unique identifier for the event", "type": "string" }, "object": { "const": "event", "default": "event", "description": "The type of object", "type": "string" }, "data": { "$ref": "#/components/schemas/WebsetItem" }, "createdAt": { "format": "date-time", "description": "The date and time the event was created", "type": "string" }, "type": { "type": "string", "const": "webset.item.enriched", "default": "webset.item.enriched", "description": "The type of event" } }, "required": ["id", "object", "type", "data", "createdAt"], "title": "WebsetItemEnrichedEvent", "type": "object" }, { "properties": { "id": { "description": "The unique identifier for the event", "type": "string" }, "object": { "const": "event", "default": "event", "description": "The type of object", "type": "string" }, "data": { "$ref": "#/components/schemas/WebsetSearch" }, "createdAt": { "format": "date-time", "description": "The date and time the event was created", "type": "string" }, "type": { "type": "string", "const": "webset.search.created", "default": "webset.search.created", "description": "The type of event" } }, "required": ["id", "object", "type", "data", "createdAt"], "title": "WebsetSearchCreatedEvent", "type": "object" }, { "properties": { "id": { "description": "The unique identifier for the event", "type": "string" }, "object": { "const": "event", "default": "event", "description": "The type of object", "type": "string" }, "data": { "$ref": "#/components/schemas/WebsetSearch" }, "createdAt": { "format": "date-time", "description": "The date and time the event was created", "type": "string" }, "type": { "type": "string", "const": "webset.search.updated", "default": "webset.search.updated", "description": "The type of event" } }, "required": ["id", "object", "type", "data", "createdAt"], "title": "WebsetSearchUpdatedEvent", "type": "object" }, { "properties": { "id": { "description": "The unique identifier for the event", "type": "string" }, "object": { "const": "event", "default": "event", "description": "The type of object", "type": "string" }, "data": { "$ref": "#/components/schemas/WebsetSearch" }, "createdAt": { "format": "date-time", "description": "The date and time the event was created", "type": "string" }, "type": { "type": "string", "const": "webset.search.canceled", "default": "webset.search.canceled", "description": "The type of event" } }, "required": ["id", "object", "type", "data", "createdAt"], "title": "WebsetSearchCanceledEvent", "type": "object" }, { "properties": { "id": { "description": "The unique identifier for the event", "type": "string" }, "object": { "const": "event", "default": "event", "description": "The type of object", "type": "string" }, "data": { "$ref": "#/components/schemas/WebsetSearch" }, "createdAt": { "format": "date-time", "description": "The date and time the event was created", "type": "string" }, "type": { "type": "string", "const": "webset.search.completed", "default": "webset.search.completed", "description": "The type of event" } }, "required": ["id", "object", "type", "data", "createdAt"], "title": "WebsetSearchCompletedEvent", "type": "object" }, { "properties": { "id": { "description": "The unique identifier for the event", "type": "string" }, "object": { "const": "event", "default": "event", "description": "The type of object", "type": "string" }, "data": { "$ref": "#/components/schemas/Import" }, "createdAt": { "format": "date-time", "description": "The date and time the event was created", "type": "string" }, "type": { "type": "string", "const": "import.created", "default": "import.created", "description": "The type of event" } }, "required": ["id", "object", "type", "data", "createdAt"], "title": "ImportCreatedEvent", "type": "object" }, { "properties": { "id": { "description": "The unique identifier for the event", "type": "string" }, "object": { "const": "event", "default": "event", "description": "The type of object", "type": "string" }, "data": { "$ref": "#/components/schemas/Import" }, "createdAt": { "format": "date-time", "description": "The date and time the event was created", "type": "string" }, "type": { "type": "string", "const": "import.completed", "default": "import.completed", "description": "The type of event" } }, "required": ["id", "object", "type", "data", "createdAt"], "title": "ImportCompletedEvent", "type": "object" }, { "properties": { "id": { "description": "The unique identifier for the event", "type": "string" }, "object": { "const": "event", "default": "event", "description": "The type of object", "type": "string" }, "data": { "$ref": "#/components/schemas/Monitor" }, "createdAt": { "format": "date-time", "description": "The date and time the event was created", "type": "string" }, "type": { "type": "string", "const": "monitor.created", "default": "monitor.created", "description": "The type of event" } }, "required": ["id", "object", "type", "data", "createdAt"], "title": "MonitorCreatedEvent", "type": "object" }, { "properties": { "id": { "description": "The unique identifier for the event", "type": "string" }, "object": { "const": "event", "default": "event", "description": "The type of object", "type": "string" }, "data": { "$ref": "#/components/schemas/Monitor" }, "createdAt": { "format": "date-time", "description": "The date and time the event was created", "type": "string" }, "type": { "type": "string", "const": "monitor.updated", "default": "monitor.updated", "description": "The type of event" } }, "required": ["id", "object", "type", "data", "createdAt"], "title": "MonitorUpdatedEvent", "type": "object" }, { "properties": { "id": { "description": "The unique identifier for the event", "type": "string" }, "object": { "const": "event", "default": "event", "description": "The type of object", "type": "string" }, "data": { "$ref": "#/components/schemas/Monitor" }, "createdAt": { "format": "date-time", "description": "The date and time the event was created", "type": "string" }, "type": { "type": "string", "const": "monitor.deleted", "default": "monitor.deleted", "description": "The type of event" } }, "required": ["id", "object", "type", "data", "createdAt"], "title": "MonitorDeletedEvent", "type": "object" }, { "properties": { "id": { "description": "The unique identifier for the event", "type": "string" }, "object": { "const": "event", "default": "event", "description": "The type of object", "type": "string" }, "data": { "$ref": "#/components/schemas/MonitorRun" }, "createdAt": { "format": "date-time", "description": "The date and time the event was created", "type": "string" }, "type": { "type": "string", "const": "monitor.run.created", "default": "monitor.run.created", "description": "The type of event" } }, "required": ["id", "object", "type", "data", "createdAt"], "title": "MonitorRunCreatedEvent", "type": "object" }, { "properties": { "id": { "description": "The unique identifier for the event", "type": "string" }, "object": { "const": "event", "default": "event", "description": "The type of object", "type": "string" }, "data": { "$ref": "#/components/schemas/MonitorRun" }, "createdAt": { "format": "date-time", "description": "The date and time the event was created", "type": "string" }, "type": { "type": "string", "const": "monitor.run.completed", "default": "monitor.run.completed", "description": "The type of event" } }, "required": ["id", "object", "type", "data", "createdAt"], "title": "MonitorRunCompletedEvent", "type": "object" } ] } }, "headers": { "XRequestId": { "description": "Unique identifier for the request. Matches the `requestId` field returned in response bodies that carry one.", "schema": { "type": "string" } }, "XExaQueued": { "description": "Whether the request waited in the customer rate-limit queue before being admitted.", "schema": { "type": "string", "enum": ["true", "false"] } }, "XExaQueueMs": { "description": "Total milliseconds the request waited in the customer rate-limit queue.", "schema": { "type": "string" } } }, "responses": { "BadRequestResponse": { "description": "The request body or query parameters failed validation.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "UnauthorizedResponse": { "description": "The API key is missing or invalid.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ForbiddenResponse": { "description": "The team is not permitted to use this endpoint (`TEAM_BLOCKED`), or the feature is not enabled for it (`FEATURE_DISABLED`).", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "TooManyRequestsResponse": { "description": "A rate limit for this API key, team, or network was exceeded.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InternalServerErrorResponse": { "description": "An unexpected error occurred while processing the request.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ServiceUnavailableResponse": { "description": "Exa is temporarily over capacity or unavailable. The request was not processed; retry with exponential backoff.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "PaymentRequiredResponse": { "description": "The team is out of credits or a spending budget has been exceeded.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFoundResponse": { "description": "The requested resource does not exist.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ConflictResponse": { "description": "The request conflicts with the current state of the resource.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": { "AcceptHeader": { "in": "header", "name": "Accept", "schema": { "description": "Set to `text/event-stream` to receive server-sent events.", "type": "string", "enum": ["application/json", "text/event-stream"] }, "description": "Set to `text/event-stream` to receive server-sent events." }, "ExaBetaHeader": { "in": "header", "name": "Exa-Beta", "schema": { "description": "Comma-separated beta feature tokens for opting into experimental features.", "type": "string" }, "description": "Comma-separated beta feature tokens for opting into experimental features." }, "LastEventId": { "in": "header", "name": "Last-Event-ID", "schema": { "description": "For SSE replay, return only events after this event ID.", "type": "string" }, "description": "For SSE replay, return only events after this event ID." }, "BatchesBetaHeader": { "in": "header", "name": "Exa-Beta", "schema": { "type": "string", "enum": ["batches-2026-06-06"], "description": "Required beta token for the Batch API." }, "required": true, "description": "Required beta token for the Batch API." } }, "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 ." } } } }