{ "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": { "example": { "requestId": "b5947044c4b78efa9552a7c89b306d95", "results": [ { "title": "A Comprehensive Overview of Large Language Models", "url": "https://arxiv.org/pdf/2307.06435.pdf", "publishedDate": "2023-11-16T01:36:32.547Z", "author": "Humza Naveed, University of Engineering and Technology (UET), Lahore, Pakistan", "id": "https://arxiv.org/abs/2307.06435", "image": "https://arxiv.org/pdf/2307.06435.pdf/page_1.png", "favicon": "https://arxiv.org/favicon.ico", "text": "Abstract Large Language Models (LLMs) have recently demonstrated remarkable capabilities...", "highlights": [ "Such requirements have limited their adoption..." ], "summary": "This overview paper on Large Language Models (LLMs) highlights key developments..." } ], "resolvedSearchType": "neural", "costDollars": { "total": 0.007, "search": { "neural": 0.007 } } }, "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. For API-key requests this is the standard error envelope (out of credits or a budget exceeded). On x402-priced endpoints, requests without an API key instead receive an x402 payment challenge with tag `X402_PAYMENT_REQUIRED`: the envelope extended with x402 payment metadata (`x402Version`, `resource`, `accepts`, and optional `extensions`) describing how to pay for the request.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "$ref": "#/components/schemas/X402PaymentChallenge" } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/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": { "example": { "requestId": "e492118ccdedcba5088bfc4357a8a125", "results": [ { "id": "https://arxiv.org/abs/2307.06435", "title": "A Comprehensive Overview of Large Language Models", "url": "https://arxiv.org/pdf/2307.06435.pdf", "publishedDate": "2023-11-16T01:36:32.547Z", "author": "Humza Naveed, University of Engineering and Technology (UET), Lahore, Pakistan", "text": "Abstract Large Language Models (LLMs) have recently demonstrated remarkable capabilities...", "highlights": [ "Such requirements have limited their adoption..." ], "summary": "This overview paper on Large Language Models (LLMs) highlights key developments..." } ], "statuses": [ { "id": "https://arxiv.org/abs/2307.06435", "status": "success", "source": "cached" } ], "costDollars": { "total": 0.003 } }, "schema": { "$ref": "#/components/schemas/ContentsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "402": { "description": "Payment required. For API-key requests this is the standard error envelope (out of credits or a budget exceeded). On x402-priced endpoints, requests without an API key instead receive an x402 payment challenge with tag `X402_PAYMENT_REQUIRED`: the envelope extended with x402 payment metadata (`x402Version`, `resource`, `accepts`, and optional `extensions`) describing how to pay for the request.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "$ref": "#/components/schemas/X402PaymentChallenge" } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/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": { "example": { "requestId": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6", "answer": "$350 billion.", "citations": [ { "id": "https://www.theguardian.com/science/2024/dec/11/spacex-valued-at-350bn-as-company-agrees-to-buy-shares-from-employees", "url": "https://www.theguardian.com/science/2024/dec/11/spacex-valued-at-350bn-as-company-agrees-to-buy-shares-from-employees", "title": "SpaceX valued at $350bn as company agrees to buy shares from ...", "author": "Dan Milmo", "publishedDate": "2024-12-11T00:00:00.000Z", "text": "SpaceX valued at $350bn as company agrees to buy shares from ..." } ], "costDollars": { "total": 0.005 } }, "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" }, "429": { "$ref": "#/components/responses/TooManyRequestsResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/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" }, "example": "true" }, "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" }, "429": { "$ref": "#/components/responses/TooManyRequestsResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/monitors": { "post": { "operationId": "createMonitor", "summary": "Create a Monitor", "description": "Creates a new Monitor to run recurring Exa searches on a schedule.\n\nMonitors automatically execute your search query on a recurring schedule and deliver results to your webhook endpoint with automatic deduplication:\n\n- **Date-based filtering** only fetches content since the last run\n\n- **Semantic deduplication** tracks previous outputs to surface only new developments\n\nThe response includes a `webhookSecret` that is only returned once at creation time. Store it securely for webhook signature verification.", "tags": [ "Monitors" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSearchMonitorParameters" } } } }, "responses": { "201": { "description": "The created monitor with webhook secret", "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" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } }, "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" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/monitors/batch": { "post": { "operationId": "batchMonitors", "summary": "Batch Action on Monitors", "description": "Perform a batch action on monitors matching the provided filters.\n\nSupported actions:\n- **delete**: Permanently remove matching monitors\n- **pause**: Pause matching monitors\n- **unpause**: Unpause matching monitors\n\nUse `dry_run: true` (the default) to preview which monitors would be affected before performing the action. Results are paginated via the `limit` parameter; loop until `has_more` is `false` to process all matching monitors.", "tags": [ "Monitors" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchMonitorsRequest" } } } }, "responses": { "200": { "description": "Batch action result", "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" }, "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" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } }, "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" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } }, "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" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/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" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/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" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/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" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/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" }, "examples": { "simple": { "summary": "Simple research run", "value": { "query": "What are the most important AI infrastructure funding rounds announced this week?" } }, "structuredOutput": { "summary": "Structured output", "value": { "query": "Find recent Series A or Series B AI infrastructure funding rounds.", "outputSchema": { "type": "object", "required": [ "companies" ], "properties": { "companies": { "type": "array", "maxItems": 10, "items": { "type": "object", "required": [ "name", "round", "amount", "sourceUrl" ], "properties": { "name": { "type": "string" }, "round": { "type": "string" }, "amount": { "type": "string" }, "sourceUrl": { "type": "string", "format": "uri" } } } } } } } }, "inputRows": { "summary": "Process input rows", "value": { "query": "For each company, find one current executive and cite a source.", "input": { "data": [ { "company": "Apple", "domain": "apple.com" }, { "company": "Microsoft", "domain": "microsoft.com" } ], "exclusion": [ { "company": "Apple", "person": "Tim Cook" } ] } } }, "contactFields": { "summary": "Contact fields in structured output", "value": { "query": "Find engineering leaders at AI infrastructure companies that raised a Series A or B in the last 6 months.", "effort": "auto", "outputSchema": { "type": "object", "required": [ "people" ], "properties": { "people": { "type": "array", "maxItems": 10, "items": { "type": "object", "required": [ "name", "linkedin_url" ], "properties": { "name": { "type": "string" }, "contact_email": { "type": "string", "format": "email" }, "linkedin_url": { "type": "string", "format": "uri" } } } } } } } }, "dataSources": { "summary": "Connect data sources", "value": { "query": "Find 10 fast-growing B2B SaaS companies and their estimated web traffic.", "dataSources": [ { "provider": "similarweb" } ], "outputSchema": { "type": "object", "required": [ "companies" ], "properties": { "companies": { "type": "array", "maxItems": 10, "items": { "type": "object", "required": [ "name", "domain", "monthlyVisits" ], "properties": { "name": { "type": "string" }, "domain": { "type": "string" }, "monthlyVisits": { "type": "number", "description": "from Similarweb" } } } } } } } } } } } }, "responses": { "200": { "description": "Agent run created", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRun" }, "examples": { "running": { "summary": "Run accepted", "value": { "id": "agent_run_01j7x9v0m2n4p6q8r0s2t4v6w8", "object": "agent_run", "status": "running", "stopReason": null, "createdAt": "2026-05-07T18:31:00.000Z", "completedAt": null, "request": { "query": "What are the most important AI infrastructure funding rounds announced this week?" }, "output": { "text": "", "structured": null, "grounding": [] }, "usage": { "agentComputeUnits": 0, "searches": 0, "emails": 0, "phoneNumbers": 0 }, "costDollars": { "total": 0, "agentCompute": 0, "search": 0, "emails": 0, "phoneNumbers": 0 } } } } }, "text/event-stream": { "schema": { "$ref": "#/components/schemas/AgentRunEvent" }, "examples": { "lifecycle": { "summary": "Run lifecycle events", "value": "id: 1\nevent: agent_run.created\ndata: {\"id\":\"agent_run_01j...\",\"status\":\"queued\",\"createdAt\":\"2026-05-07T21:21:52.051Z\"}\n\nid: 2\nevent: agent_run.started\ndata: {\"id\":\"agent_run_01j...\",\"status\":\"running\"}\n\nid: 3\nevent: agent_run.completed\ndata: {\"id\":\"agent_run_01j...\",\"object\":\"agent_run\",\"status\":\"completed\"}" } } } } }, "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" } } } }, "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" } } } } } }, "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" } } } }, "500": { "description": "Server error or run timeout.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentErrorResponse" } } } } } } }, "/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" } } } }, "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" } } } } } }, "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" } } } }, "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" } } } } } } }, "/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" } } } }, "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" } } } } } } }, "/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 `max` effort runs and requires the `Exa-Beta: agent-max-effort-2026-07-27` header. 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." }, { "$ref": "#/components/parameters/ExaBetaHeader" } ], "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" } } } }, "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" } } } } } } }, "/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" }, "examples": { "replay": { "summary": "Replayed run events", "value": "id: 2\nevent: agent_run.started\ndata: {\"id\":\"agent_run_01j...\",\"status\":\"running\"}\n\nid: 3\nevent: agent_run.completed\ndata: {\"id\":\"agent_run_01j...\",\"object\":\"agent_run\",\"status\":\"completed\"}\n" } } } } }, "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" } } } }, "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" } } } } } } }, "/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" }, "examples": { "searchBatch": { "summary": "Batch of search and agent-run requests", "value": { "requests": [ { "customId": "row-1", "method": "POST", "url": "/search", "body": { "query": "Latest AI infrastructure funding rounds" } }, { "customId": "row-2", "method": "POST", "url": "/agent/runs", "body": { "query": "Summarize this week's vector database launches" } } ], "metadata": { "project": "weekly-digest" } } } } } } }, "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "example": { "id": "batch_01j7x9v0m2n4p6q8r0s2t4v6w8", "object": "batch", "status": "in_progress", "requestCounts": { "total": 2, "completed": 0, "failed": 0 }, "createdAt": "2026-06-06T12:00:00.000Z", "expiresAt": "2026-06-13T12:00:00.000Z", "endedAt": null, "resultsUrl": null, "metadata": { "project": "weekly-digest" } }, "schema": { "$ref": "#/components/schemas/Batch" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "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": "Filter the listing to completed batches. `completed` is the only supported value; any other value returns a 400. Completed listings are ordered by expiry and use a distinct cursor, so keep sending `status=completed` on every cursor-paginated request." } }, { "$ref": "#/components/parameters/BatchesBetaHeader" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "example": { "object": "list", "data": [ { "id": "batch_01j7x9v0m2n4p6q8r0s2t4v6w8", "object": "batch", "status": "completed", "requestCounts": { "total": 2, "completed": 2, "failed": 0 }, "createdAt": "2026-06-06T12:00:00.000Z", "expiresAt": "2026-06-13T12:00:00.000Z", "endedAt": "2026-06-06T12:01:30.000Z", "resultsUrl": "https://exa-batch-results.s3.us-east-1.amazonaws.com/batch_01j7x9v0m2n4p6q8r0s2t4v6w8/results.jsonl?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=EXAMPLESIGNATURE", "metadata": { "project": "weekly-digest" } } ], "hasMore": false, "nextCursor": null }, "schema": { "$ref": "#/components/schemas/BatchList" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "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.", "example": "batch_01j7x9v0m2n4p6q8r0s2t4v6w8" }, "required": true, "description": "Batch ID." }, { "$ref": "#/components/parameters/BatchesBetaHeader" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "example": { "id": "batch_01j7x9v0m2n4p6q8r0s2t4v6w8", "object": "batch", "status": "completed", "requestCounts": { "total": 2, "completed": 2, "failed": 0 }, "createdAt": "2026-06-06T12:00:00.000Z", "expiresAt": "2026-06-13T12:00:00.000Z", "endedAt": "2026-06-06T12:01:30.000Z", "resultsUrl": "https://exa-batch-results.s3.us-east-1.amazonaws.com/batch_01j7x9v0m2n4p6q8r0s2t4v6w8/results.jsonl?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=EXAMPLESIGNATURE", "metadata": { "project": "weekly-digest" } }, "schema": { "$ref": "#/components/schemas/Batch" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "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.", "example": "batch_01j7x9v0m2n4p6q8r0s2t4v6w8" }, "required": true, "description": "Batch ID." }, { "$ref": "#/components/parameters/BatchesBetaHeader" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "example": { "id": "batch_01j7x9v0m2n4p6q8r0s2t4v6w8", "object": "batch.deleted", "deleted": true }, "schema": { "$ref": "#/components/schemas/DeletedBatch" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "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.", "example": "batch_01j7x9v0m2n4p6q8r0s2t4v6w8" }, "required": true, "description": "Batch ID." }, { "$ref": "#/components/parameters/BatchesBetaHeader" } ], "responses": { "200": { "description": "OK", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "example": { "id": "batch_01j7x9v0m2n4p6q8r0s2t4v6w8", "object": "batch", "status": "cancelling", "requestCounts": { "total": 2, "completed": 0, "failed": 0 }, "createdAt": "2026-06-06T12:00:00.000Z", "expiresAt": "2026-06-13T12:00:00.000Z", "endedAt": null, "resultsUrl": null, "metadata": { "project": "weekly-digest" } }, "schema": { "$ref": "#/components/schemas/Batch" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "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" ], "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": { "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.", "operationId": "websets-create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebsetParameters" } } } }, "responses": { "201": { "description": "Webset created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webset" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } }, "409": { "description": "Webset with this externalId already exists", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Create a Webset", "tags": [ "Websets" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] }, "get": { "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.", "operationId": "websets-list", "parameters": [ { "name": "cursor", "required": false, "in": "query", "description": "The cursor to paginate through the results", "schema": { "minLength": 1, "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "The number of Websets to return", "schema": { "minimum": 1, "maximum": 100, "default": 25, "type": "number" } }, { "name": "search", "required": false, "in": "query", "description": "Search term to filter Websets by ID, external ID, or title", "schema": { "minLength": 2, "maxLength": 50, "type": "string" } } ], "responses": { "200": { "description": "List of Websets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebsetsResponse" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "List all Websets", "tags": [ "Websets" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } }, "/v0/websets/{id}": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "get": { "operationId": "websets-get", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id or externalId of the Webset.", "schema": { "type": "string" } }, { "name": "expand", "required": false, "in": "query", "description": "Expand the response with the specified resources", "schema": { "type": "array", "items": { "type": "string", "enum": [ "items" ] } } } ], "responses": { "200": { "description": "Webset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetWebsetResponse" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } }, "404": { "description": "Webset not found", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Get a Webset", "tags": [ "Websets" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] }, "post": { "operationId": "websets-update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id or externalId of the Webset", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebsetRequest" } } } }, "responses": { "200": { "description": "Webset updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webset" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } }, "404": { "description": "Webset not found", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Update a Webset", "tags": [ "Websets" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] }, "delete": { "description": "Deletes a Webset.\n\nOnce deleted, the Webset and all its Items will no longer be available.", "operationId": "websets-delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id or externalId of the Webset", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webset deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webset" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } }, "404": { "description": "Webset not found", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Delete a Webset", "tags": [ "Websets" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } }, "/v0/websets/{id}/cancel": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "post": { "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`.", "operationId": "websets-cancel", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id or externalId of the Webset", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webset canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webset" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Cancel a running Webset", "tags": [ "Websets" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } }, "/v0/websets/preview": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "post": { "description": "Preview how a search query will be decomposed before creating a webset. This endpoint performs the same query analysis that happens during webset creation, allowing you to see the detected entity type, generated search criteria, and available enrichment columns in advance.\n\nUse this to help users understand how their search will be interpreted before committing to a full webset creation.", "operationId": "websets-preview", "parameters": [ { "name": "search", "required": false, "in": "path", "description": "Weather you want to search for a preview list of items or not", "schema": { "type": "boolean" } } ], "requestBody": { "required": true, "description": "Search parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewWebsetParameters" } } } }, "responses": { "200": { "description": "Preview of the webset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewWebsetResponse" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } }, "422": { "description": "Unable to detect entity or criteria from query", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Preview a webset", "tags": [ "Websets Preview" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } }, "/v0/websets/{webset}/items/{id}": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "get": { "description": "Returns a Webset Item.", "operationId": "websets-items-get", "parameters": [ { "name": "webset", "required": true, "in": "path", "description": "The id or externalId of the Webset", "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "description": "The id of the Webset item", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webset Item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsetItem" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Get an Item", "tags": [ "Items" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] }, "delete": { "description": "Deletes an Item from the Webset.\n\nThis will cancel any enrichment process for it.", "operationId": "websets-items-delete", "parameters": [ { "name": "webset", "required": true, "in": "path", "description": "The id or externalId of the Webset", "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "description": "The id of the Webset item", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webset Item deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsetItem" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Delete an Item", "tags": [ "Items" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } }, "/v0/websets/{webset}/items": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "get": { "description": "Returns a list of Webset Items.\n\nYou can paginate through the Items using the `cursor` parameter.", "operationId": "websets-items-list", "parameters": [ { "name": "webset", "required": true, "in": "path", "description": "The id or externalId of the Webset", "schema": { "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "description": "The cursor to paginate through the results", "schema": { "minLength": 1, "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "The number of results to return", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "sourceId", "required": false, "in": "query", "description": "The id of the source", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webset Items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebsetItemResponse" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "List all Items for a Webset", "tags": [ "Items" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } }, "/v0/websets/{webset}/enrichments": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "post": { "description": "Create an Enrichment for a Webset.", "operationId": "websets-enrichments-create", "parameters": [ { "name": "webset", "required": true, "in": "path", "description": "The id or externalId of the Webset", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEnrichmentParameters" } } } }, "responses": { "200": { "description": "Enrichment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsetEnrichment" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Create an Enrichment", "tags": [ "Enrichments" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } }, "/v0/websets/{webset}/enrichments/{id}": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "patch": { "description": "Update an Enrichment configuration for a Webset.", "operationId": "websets-enrichments-update", "parameters": [ { "name": "webset", "required": true, "in": "path", "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "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.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Update an Enrichment", "tags": [ "Enrichments" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] }, "get": { "operationId": "websets-enrichments-get", "parameters": [ { "name": "webset", "required": true, "in": "path", "description": "The id or externalId of the Webset", "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "description": "The id of the Enrichment", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Enrichment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsetEnrichment" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Get an Enrichment", "tags": [ "Enrichments" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] }, "delete": { "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.", "operationId": "websets-enrichments-delete", "parameters": [ { "name": "webset", "required": true, "in": "path", "description": "The id or externalId of the Webset", "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "description": "The id of the Enrichment", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Enrichment deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsetEnrichment" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Delete an Enrichment", "tags": [ "Enrichments" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } }, "/v0/websets/{webset}/enrichments/{id}/cancel": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "post": { "description": "All running enrichments will be canceled. You can not resume an Enrichment after it has been canceled.", "operationId": "websets-enrichments-cancel", "parameters": [ { "name": "webset", "required": true, "in": "path", "description": "The id or externalId of the Webset", "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "description": "The id of the Enrichment", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Enrichment cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsetEnrichment" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Cancel a running Enrichment", "tags": [ "Enrichments" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } }, "/v0/webhooks": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "post": { "operationId": "webhooks-create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookParameters" } } } }, "responses": { "200": { "description": "Webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Create a Webhook", "tags": [ "Webhooks" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] }, "get": { "operationId": "webhooks-list", "parameters": [ { "name": "cursor", "required": false, "in": "query", "description": "The cursor to paginate through the results", "schema": { "minLength": 1, "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "The number of results to return", "schema": { "minimum": 1, "maximum": 200, "default": 25, "type": "integer" } } ], "responses": { "200": { "description": "List of webhooks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebhooksResponse" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "List webhooks", "tags": [ "Webhooks" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } }, "/v0/webhooks/{id}": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "get": { "operationId": "webhooks-get", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the webhook", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } }, "404": { "description": "Webhook not found", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Get a Webhook", "tags": [ "Webhooks" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] }, "patch": { "operationId": "webhooks-update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the webhook", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookParameters" } } } }, "responses": { "200": { "description": "Webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } }, "404": { "description": "Webhook not found", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Update a Webhook", "tags": [ "Webhooks" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] }, "delete": { "operationId": "webhooks-delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the webhook", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } }, "404": { "description": "Webhook not found", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Delete a Webhook", "tags": [ "Webhooks" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } }, "/v0/webhooks/{id}/attempts": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "get": { "description": "List all attempts made by a Webhook ordered in descending order.", "operationId": "webhooks-attempts-list", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The ID of the webhook", "schema": { "type": "string" } }, { "name": "cursor", "required": false, "in": "query", "description": "The cursor to paginate through the results", "schema": { "minLength": 1, "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "The number of results to return", "schema": { "minimum": 1, "maximum": 200, "default": 25, "type": "integer" } }, { "name": "eventType", "required": false, "in": "query", "description": "The type of event to filter by", "schema": { "type": "string", "enum": [ "webset.created", "webset.deleted", "webset.paused", "webset.idle", "webset.search.created", "webset.search.canceled", "webset.search.completed", "webset.search.updated", "import.created", "import.completed", "webset.item.created", "webset.item.enriched", "monitor.created", "monitor.updated", "monitor.deleted", "monitor.run.created", "monitor.run.completed", "webset.export.created", "webset.export.completed" ] } }, { "name": "successful", "required": false, "in": "query", "description": "Filter attempts by their success status", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of webhook attempts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebhookAttemptsResponse" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "List webhook attempts", "tags": [ "Webhooks Attempts" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } }, "/v0/events": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "get": { "description": "List all events that have occurred in the system.\n\nYou can paginate through the results using the `cursor` parameter.", "operationId": "events-list", "parameters": [ { "name": "cursor", "required": false, "in": "query", "description": "The cursor to paginate through the results", "schema": { "minLength": 1, "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "The number of results to return", "schema": { "minimum": 1, "maximum": 200, "default": 25, "type": "integer" } }, { "name": "types", "required": false, "in": "query", "description": "The types of events to filter by", "schema": { "type": "array", "items": { "type": "string", "enum": [ "webset.created", "webset.deleted", "webset.paused", "webset.idle", "webset.search.created", "webset.search.canceled", "webset.search.completed", "webset.search.updated", "import.created", "import.completed", "webset.item.created", "webset.item.enriched", "monitor.created", "monitor.updated", "monitor.deleted", "monitor.run.created", "monitor.run.completed", "webset.export.created", "webset.export.completed" ] } } }, { "name": "createdBefore", "required": false, "in": "query", "description": "Filter events created before or at this timestamp (inclusive). Must be a valid ISO 8601 datetime string. All times are in UTC.", "schema": { "format": "date-time", "type": "string" } }, { "name": "createdAfter", "required": false, "in": "query", "description": "Filter events created after or at this timestamp (inclusive). Must be a valid ISO 8601 datetime string. All times are in UTC.", "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "description": "List of events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListEventsResponse" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "List all Events", "tags": [ "Events" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } }, "/v0/events/{id}": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "get": { "description": "Get a single Event by id.\n\nYou can subscribe to Events by creating a Webhook.", "operationId": "events-get", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the event", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } }, "404": { "description": "Event not found", "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Get an Event", "tags": [ "Events" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } }, "/v0/websets/{webset}/searches": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "post": { "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.", "operationId": "websets-searches-create", "parameters": [ { "name": "webset", "required": true, "in": "path", "description": "The id of the Webset", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebsetSearchParameters" } } } }, "responses": { "200": { "description": "Webset Search created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsetSearch" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Create a Search", "tags": [ "Searches" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } }, "/v0/websets/{webset}/searches/{id}": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "get": { "description": "Gets a Search by id", "operationId": "websets-searches-get", "parameters": [ { "name": "webset", "required": true, "in": "path", "description": "The id of the Webset", "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "description": "The id of the Search", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Search retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsetSearch" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Get a Search", "tags": [ "Searches" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } }, "/v0/websets/{webset}/searches/{id}/cancel": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "post": { "description": "Cancels a currently running Search.\n\nYou can cancel all searches at once by using the `websets/:webset/cancel` endpoint.", "operationId": "websets-searches-cancel", "parameters": [ { "name": "webset", "required": true, "in": "path", "description": "The id of the Webset", "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "description": "The id of the Search", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Search canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsetSearch" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Cancel a running Search", "tags": [ "Searches" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } }, "/v0/monitors": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "post": { "description": "Creates a new `Monitor` to continuously keep your Websets updated with fresh data.\n\nMonitors automatically run on your defined schedule to ensure your Websets stay current without manual intervention:\n\n- **Find new content**: Execute `search` operations to discover fresh items matching your criteria\n- **Update existing content**: Run `refresh` operations to update items contents and enrichments\n- **Automated scheduling**: Configure `cron` expressions and `timezone` for precise scheduling control", "operationId": "monitors-create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMonitorParameters" } } } }, "responses": { "201": { "description": "Monitor created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Monitor" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Create a Monitor", "tags": [ "Monitors" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] }, "get": { "description": "Lists all monitors for the Webset.", "operationId": "monitors-list", "parameters": [ { "name": "cursor", "required": false, "in": "query", "description": "The cursor to paginate through the results", "schema": { "minLength": 1, "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "The number of results to return", "schema": { "minimum": 1, "maximum": 200, "default": 25, "type": "integer" } }, { "name": "websetId", "required": false, "in": "query", "description": "The id of the Webset to list monitors for", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of monitors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMonitorsResponse" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "List Monitors", "tags": [ "Monitors" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } }, "/v0/monitors/{id}": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "get": { "description": "Gets a specific monitor.", "operationId": "monitors-get", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the Monitor", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Monitor details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Monitor" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Get Monitor", "tags": [ "Monitors" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] }, "patch": { "description": "Updates a monitor configuration.", "operationId": "monitors-update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the Monitor", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMonitor" } } } }, "responses": { "200": { "description": "Monitor updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Monitor" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Update Monitor", "tags": [ "Monitors" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] }, "delete": { "description": "Deletes a monitor.", "operationId": "monitors-delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the Monitor", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Monitor deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Monitor" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Delete Monitor", "tags": [ "Monitors" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } }, "/v0/monitors/{monitor}/runs": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "get": { "description": "Lists all runs for the Monitor.", "operationId": "monitors-runs-list", "parameters": [ { "name": "monitor", "required": true, "in": "path", "description": "The id of the Monitor to list runs for", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of monitor runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListMonitorRunsResponse" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "List Monitor Runs", "tags": [ "Monitors Runs" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } }, "/v0/monitors/{monitor}/runs/{id}": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "get": { "description": "Gets a specific monitor run.", "operationId": "monitors-runs-get", "parameters": [ { "name": "monitor", "required": true, "in": "path", "description": "The id of the Monitor to get the run for", "schema": { "type": "string" } }, { "name": "id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Monitor run details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorRun" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Get Monitor Run", "tags": [ "Monitors Runs" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } }, "/v0/imports": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "post": { "description": "Creates a new import to upload your data into Websets. Imports can be used to:\n\n- **Enrich**: Enhance your data with additional information using our AI-powered enrichment engine\n- **Search**: Query your data using Websets' agentic search with natural language filters\n- **Exclude**: Prevent duplicate or already known results from appearing in your searches\n\nOnce the import is created, you can upload your data to the returned `uploadUrl` until `uploadValidUntil` (by default 1 hour).", "operationId": "imports-create", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateImportParameters" } } } }, "responses": { "201": { "description": "Import created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateImportResponse" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Create an Import", "tags": [ "Imports" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] }, "get": { "description": "Lists all imports for the Webset.", "operationId": "imports-list", "parameters": [ { "name": "cursor", "required": false, "in": "query", "description": "The cursor to paginate through the results", "schema": { "minLength": 1, "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "The number of results to return", "schema": { "minimum": 1, "maximum": 200, "default": 25, "type": "integer" } } ], "responses": { "200": { "description": "List of imports", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListImportsResponse" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "List Imports", "tags": [ "Imports" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } }, "/v0/imports/{id}": { "servers": [ { "url": "https://api.exa.ai/websets" } ], "get": { "description": "Gets a specific import.", "operationId": "imports-get", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the Import", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Import details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Import" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Get Import", "tags": [ "Imports" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] }, "patch": { "description": "Updates a import configuration.", "operationId": "imports-update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the Import", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateImport" } } } }, "responses": { "200": { "description": "Import updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Import" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Update Import", "tags": [ "Imports" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] }, "delete": { "description": "Deletes a import.", "operationId": "imports-delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the Import", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Import deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Import" } } }, "headers": { "X-Request-Id": { "schema": { "type": "string" }, "description": "Unique identifier for the request.", "example": "req_N6SsgoiaOQOPqsYKKiw5", "required": true } } } }, "summary": "Delete Import", "tags": [ "Imports" ], "security": [ { "apiKey": [] }, { "bearer": [] } ] } } }, "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.", "example": [ "arxiv.org", "exa.ai/blog" ] }, { "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.", "example": [ "docs.python.org/3" ] }, { "type": "null" } ] }, "startCrawlDate": { "anyOf": [ { "type": "string", "description": "Deprecated and has no effect; ignored by the API. Must be specified in ISO 8601 format.", "example": "2023-01-01T00:00:00.000Z", "format": "date-time", "deprecated": true }, { "type": "null" } ] }, "endCrawlDate": { "anyOf": [ { "type": "string", "description": "Deprecated and has no effect; ignored by the API. Must be specified in ISO 8601 format.", "example": "2023-12-31T00:00:00.000Z", "format": "date-time", "deprecated": true }, { "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.", "example": "2023-01-01T00:00:00.000Z", "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.", "example": "2023-12-31T00:00:00.000Z", "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 sales (hello@exa.ai) to discuss higher limits.", "example": 10, "default": 10 }, { "type": "null" } ] }, "context": { "anyOf": [ { "description": "Deprecated: Use highlights or text instead. Returns page contents as a combined context string.", "deprecated": true, "oneOf": [ { "type": "boolean", "description": "Deprecated: Use highlights or text instead. Returns page contents as a combined context string.", "example": true, "deprecated": true }, { "type": "object", "properties": { "maxCharacters": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Deprecated. Maximum character limit for the context string. Maximum supported value is 10000.", "example": 10000 } }, "description": "Deprecated: Use highlights or text instead. Returns page contents as a combined context string.", "deprecated": true } ] }, { "type": "null" } ] }, "moderation": { "anyOf": [ { "type": "boolean", "description": "Enable content moderation to filter unsafe content from search results.", "example": true, "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.", "example": "Latest developments in LLM capabilities" }, "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.", "example": [ "LLM advancements", "large language model progress" ] }, { "type": "null" } ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "instant", "fast", "auto", "deep-lite", "deep", "deep-reasoning" ], "description": "The search mode to use. `auto` (default) is a balanced mode that optimizes for both quality and speed and is recommended for most applications. `fast` returns high-quality results with reduced latency, making it a good fit for user-facing search and interactive workflows. `instant` is optimized for minimum response time, trading some search depth for speed in real-time experiences such as chat, voice agents, and autocomplete. `deep-lite` performs lightweight research with synthesized results and a consistent 4-second latency, lower than full deep search. `deep` conducts comprehensive multi-step research with synthesis, while `deep-reasoning` adds stronger reasoning for complex analysis and decision-making tasks.", "example": "auto", "default": "auto" }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string", "enum": [ "company", "publication", "news", "personal site", "financial report", "people" ], "description": "A data category to focus on. Known categories include `company`, `publication`, `news`, `personal site`, `financial report`, and `people`. Other strings are accepted and used as category hints for search. The `people` and `company` categories have improved quality for finding people profiles and company pages. The `publication` category surfaces scholarly publications such as research papers, preprints, and journal articles, with structured metadata like authors, venue, and citations. Note: The `company` and `people` categories only support a limited set of filters. The following parameters are NOT supported for these categories: `startPublishedDate`, `endPublishedDate`, `excludeDomains`. Using unsupported parameters will result in a 400 error.", "example": "publication" }, { "type": "null" } ] }, "userLocation": { "anyOf": [ { "type": "string", "description": "The two-letter ISO country code of the user, e.g. US.", "example": "US" }, { "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.", "example": "hipaa" }, { "type": "null" } ] }, "outputSchema": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "description": { "type": "string" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "object" }, "description": { "type": "string" }, "properties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, "required": { "type": "array", "items": { "type": "string" } }, "additionalProperties": { "type": "boolean" } }, "required": [ "type" ], "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ], "description": "JSON schema for synthesized output. Supported root types are \"text\" and \"object\". When provided, the response includes an output object whose content matches this schema. Works with every search type and adds about 2 seconds of synthesis latency on top of the selected search type.", "type": "object" }, { "type": "null" } ] }, "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.", "example": "Prefer official sources and avoid duplicate results." }, { "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" } ] } }, "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": 10000, "description": "Maximum character limit for the full page text. Useful for controlling response size and API costs. Maximum supported value is 10000.", "example": 1000 }, { "type": "null" } ] }, "includeHtmlTags": { "anyOf": [ { "type": "boolean", "description": "If true, include lightweight HTML tags in returned text instead of plain markdown-style text. Use maxAgeHours: 0 when you need this applied to freshly fetched content.", "example": false, "default": false }, { "type": "null" } ] }, "verbosity": { "anyOf": [ { "type": "string", "enum": [ "compact", "standard", "full" ], "description": "Controls text rendering verbosity. compact focuses on main content, standard includes more surrounding page context, and full requests the most complete rendered text. Some pages may produce identical standard and full output. Use maxAgeHours: 0 when you need this applied to freshly fetched content.", "example": "standard", "default": "compact" }, { "type": "null" } ] }, "includeSections": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "header", "navigation", "banner", "body", "sidebar", "footer", "metadata" ] }, "description": "Best-effort. Only include content classified into these semantic page sections. Section classification may be unavailable or incomplete for some pages; validate output if strict filtering is required. Use maxAgeHours: 0 when you need this applied to freshly fetched content.", "example": [ "body", "header" ] }, { "type": "null" } ] }, "excludeSections": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "header", "navigation", "banner", "body", "sidebar", "footer", "metadata" ] }, "description": "Exclude content classified into these semantic page sections. Section classification is best-effort. Use maxAgeHours: 0 when you need this applied to freshly fetched content.", "example": [ "navigation", "footer", "sidebar" ] }, { "type": "null" } ] } }, "title": "Advanced text options", "description": "Advanced options for controlling text extraction. Use this when you need to limit text length or include HTML structure." } ] }, { "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.", "example": "Key advancements" }, { "type": "null" } ] }, "maxCharacters": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Maximum number of characters to return for highlights. Controls the total length of highlight text returned per URL. Maximum supported value is 10000.", "example": 2000 }, { "type": "null" } ] }, "numSentences": { "anyOf": [ { "type": "integer", "minimum": 1, "description": "Deprecated and will be removed in a future release. Currently mapped to a character budget of about 1333 characters per sentence. Pass highlights: true for default highlights, or { query } to guide selection with your own query.", "example": 1, "deprecated": true }, { "type": "null" } ] }, "highlightsPerUrl": { "anyOf": [ { "type": "integer", "minimum": 1, "description": "Deprecated and will be removed in a future release. Currently ignored. Pass highlights: true for default highlights, or { query } to guide selection with your own query.", "example": 1, "deprecated": true }, { "type": "null" } ] } }, "title": "Advanced highlights options", "description": "Advanced options for steering highlight extraction. Pass highlights: true for the highest-quality default; supply this object only when you need to guide selection with your own query." } ] }, { "type": "null" } ] }, "summary": { "anyOf": [ { "type": "object", "properties": { "query": { "anyOf": [ { "type": "string", "description": "Custom query for the LLM-generated summary.", "example": "Main developments" }, { "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.", "example": { "$schema": "http://json-schema.org/draft-07/schema#", "title": "Title", "type": "object", "properties": { "Property 1": { "type": "string", "description": "Description" }, "Property 2": { "type": "string", "enum": [ "option 1", "option 2", "option 3" ], "description": "Description" } }, "required": [ "Property 1" ] } }, { "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.", "example": 1, "default": 0 }, { "type": "null" } ] }, "imageLinks": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Number of images to return for each result.", "example": 1, "default": 0 }, { "type": "null" } ] }, "richImageLinks": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Number of rich image links to return for each result.", "default": 0 }, { "type": "null" } ] }, "richLinks": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Number of rich links to return for each result.", "default": 0 }, { "type": "null" } ] }, "codeBlocks": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Number of code blocks to return for each result.", "default": 0 }, { "type": "null" } ] } }, "description": "Extra parameters to pass." }, { "type": "null" } ] }, "context": { "anyOf": [ { "description": "Deprecated: Use highlights or text instead. Returns page contents as a combined context string.", "deprecated": true, "oneOf": [ { "type": "boolean", "description": "Deprecated: Use highlights or text instead. Returns page contents as a combined context string.", "example": true, "deprecated": true }, { "type": "object", "properties": { "maxCharacters": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Deprecated. Maximum character limit for the context string. Maximum supported value is 10000.", "example": 10000 } }, "description": "Deprecated: Use highlights or text instead. Returns page contents as a combined context string.", "deprecated": true } ] }, { "type": "null" } ] }, "livecrawl": { "anyOf": [ { "type": "string", "enum": [ "never", "always", "fallback", "preferred" ], "description": "Deprecated: Use maxAgeHours instead for content freshness control. livecrawl does not guarantee freshly fetched parser output and may be served according to server freshness policy. Do not send livecrawl and maxAgeHours together.", "example": "preferred", "deprecated": true }, { "type": "null" } ] }, "livecrawlTimeout": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 90000, "description": "The timeout for livecrawling in milliseconds.", "example": 1000, "default": 10000 }, { "type": "null" } ] }, "maxAgeHours": { "anyOf": [ { "type": "integer", "minimum": -1, "maximum": 720, "description": "Maximum age of cached content in hours. Positive values use cached content if it is less than this many hours old; 0 fetches fresh content and is the supported way to apply text rendering options to newly fetched pages; -1 always uses cache; omitted uses fallback fetching when cached content is unavailable. Maximum supported value is 720 hours.", "example": 24 }, { "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.", "example": 1, "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.", "example": "sources", "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "minItems": 0, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } } ] }, { "type": "null" } ] } } }, "ContentsRequest": { "allOf": [ { "type": "object", "properties": { "ids": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2048 }, "description": "Document IDs obtained from searches.", "example": [ "https://arxiv.org/pdf/2307.06435" ] }, "urls": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2048 }, "description": "URLs to crawl (backwards compatible with the `ids` parameter).", "example": [ "https://arxiv.org/pdf/2307.06435" ] }, "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.", "example": "hipaa" }, { "type": "null" } ] } }, "description": "Provide either `ids` or `urls`, but not both.", "oneOf": [ { "required": [ "ids" ] }, { "required": [ "urls" ] } ] }, { "$ref": "#/components/schemas/ContentsOptions" } ] }, "AnswerRequest": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "Natural-language question or instructions for the request.", "example": "What is the latest valuation of SpaceX?" }, "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 }, "outputSchema": { "type": "object", "properties": { "type": { "type": "string", "description": "The root schema type (typically \"object\").", "example": "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." } }, "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.", "example": [ "arxiv.org", "exa.ai/blog" ] }, { "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.", "example": [ "docs.python.org/3" ] }, { "type": "null" } ] }, "startCrawlDate": { "anyOf": [ { "type": "string", "description": "Deprecated and has no effect; ignored by the API. Must be specified in ISO 8601 format.", "example": "2023-01-01T00:00:00.000Z", "format": "date-time", "deprecated": true }, { "type": "null" } ] }, "endCrawlDate": { "anyOf": [ { "type": "string", "description": "Deprecated and has no effect; ignored by the API. Must be specified in ISO 8601 format.", "example": "2023-12-31T00:00:00.000Z", "format": "date-time", "deprecated": true }, { "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.", "example": "2023-01-01T00:00:00.000Z", "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.", "example": "2023-12-31T00:00:00.000Z", "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 sales (hello@exa.ai) to discuss higher limits.", "example": 10, "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.", "example": "https://arxiv.org/abs/2307.06435" }, "category": { "anyOf": [ { "type": "string", "enum": [ "company", "publication", "news", "personal site", "financial report", "people" ], "description": "A data category to focus on. Known categories include `company`, `publication`, `news`, `personal site`, `financial report`, and `people`. Other strings are accepted and used as category hints for search. The `people` and `company` categories have improved quality for finding people profiles and company pages. The `publication` category surfaces scholarly publications such as research papers, preprints, and journal articles, with structured metadata like authors, venue, and citations. Note: The `company` and `people` categories only support a limited set of filters. The following parameters are NOT supported for these categories: `startPublishedDate`, `endPublishedDate`, `excludeDomains`. Using unsupported parameters will result in a 400 error.", "example": "publication" }, { "type": "null" } ] }, "excludeSourceDomain": { "anyOf": [ { "type": "boolean", "description": "If true, results from the same domain as the source url are excluded.", "example": true }, { "type": "null" } ] } }, "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.", "example": { "slack_channel_id": "C123ABC", "slack_thread_id": "1745444400.123456", "user_id": "U123ABC" } }, "webhook": { "$ref": "#/components/schemas/SearchMonitorWebhook" } }, "required": [ "search", "webhook" ] }, "SearchMonitorSearch": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "The query string for the search.", "example": "Latest developments in LLM capabilities" }, "numResults": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of results to return. Limits vary by search type. The maximum public limit is 100 results. Contact sales (hello@exa.ai) to discuss higher limits.", "example": 10, "default": 10 }, "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": 10000, "description": "Maximum character limit for the full page text. Useful for controlling response size and API costs. Maximum supported value is 10000.", "example": 1000 }, { "type": "null" } ] }, "includeHtmlTags": { "anyOf": [ { "type": "boolean", "description": "If true, include lightweight HTML tags in returned text instead of plain markdown-style text. Use maxAgeHours: 0 when you need this applied to freshly fetched content.", "example": false, "default": false }, { "type": "null" } ] }, "verbosity": { "anyOf": [ { "type": "string", "enum": [ "compact", "standard", "full" ], "description": "Controls text rendering verbosity. compact focuses on main content, standard includes more surrounding page context, and full requests the most complete rendered text. Some pages may produce identical standard and full output. Use maxAgeHours: 0 when you need this applied to freshly fetched content.", "example": "standard", "default": "compact" }, { "type": "null" } ] }, "includeSections": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "header", "navigation", "banner", "body", "sidebar", "footer", "metadata" ] }, "description": "Best-effort. Only include content classified into these semantic page sections. Section classification may be unavailable or incomplete for some pages; validate output if strict filtering is required. Use maxAgeHours: 0 when you need this applied to freshly fetched content.", "example": [ "body", "header" ] }, { "type": "null" } ] }, "excludeSections": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "header", "navigation", "banner", "body", "sidebar", "footer", "metadata" ] }, "description": "Exclude content classified into these semantic page sections. Section classification is best-effort. Use maxAgeHours: 0 when you need this applied to freshly fetched content.", "example": [ "navigation", "footer", "sidebar" ] }, { "type": "null" } ] } }, "title": "Advanced text options", "description": "Advanced options for controlling text extraction. Use this when you need to limit text length or include HTML structure." } ] }, "highlights": { "description": "Text snippets the LLM identifies as most relevant from each page.", "oneOf": [ { "type": "boolean", "title": "Simple highlights retrieval", "description": "If true, returns highlights with default settings. If false, disables highlights.", "default": false }, { "type": "object", "properties": { "query": { "anyOf": [ { "type": "string", "description": "Custom query that guides which highlights the LLM picks.", "example": "Key advancements" }, { "type": "null" } ] }, "maxCharacters": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Maximum number of characters to return for highlights. Controls the total length of highlight text returned per URL. Maximum supported value is 10000.", "example": 2000 }, { "type": "null" } ] }, "numSentences": { "anyOf": [ { "type": "integer", "minimum": 1, "description": "Deprecated and will be removed in a future release. Currently mapped to a character budget of about 1333 characters per sentence. Pass highlights: true for default highlights, or { query } to guide selection with your own query.", "example": 1, "deprecated": true }, { "type": "null" } ] }, "highlightsPerUrl": { "anyOf": [ { "type": "integer", "minimum": 1, "description": "Deprecated and will be removed in a future release. Currently ignored. Pass highlights: true for default highlights, or { query } to guide selection with your own query.", "example": 1, "deprecated": true }, { "type": "null" } ] } }, "title": "Advanced highlights options", "description": "Advanced options for steering highlight extraction. Pass highlights: true for the highest-quality default; supply this object only when you need to guide selection with your own query." } ] }, "summary": { "description": "Return an LLM-generated summary. Pass `true` for defaults, or an object with `query` and `maxTokens`.", "oneOf": [ { "type": "boolean" }, { "type": "object", "properties": { "query": { "anyOf": [ { "type": "string", "description": "Custom query for the LLM-generated summary.", "example": "Main developments" }, { "type": "null" } ] }, "maxTokens": { "type": "integer", "minimum": 1, "description": "Maximum tokens for the generated summary." } } } ] }, "extras": { "type": "object", "properties": { "links": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Number of URLs to return from each webpage.", "example": 1, "default": 0 }, { "type": "null" } ] }, "imageLinks": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Number of images to return for each result.", "example": 1, "default": 0 }, { "type": "null" } ] }, "richImageLinks": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Number of rich image links to return for each result.", "default": 0 }, { "type": "null" } ] }, "richLinks": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Number of rich links to return for each result.", "default": 0 }, { "type": "null" } ] }, "codeBlocks": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Number of code blocks to return for each result.", "default": 0 }, { "type": "null" } ] } }, "description": "Extra parameters to pass." }, "context": { "description": "Deprecated: Use highlights or text instead. Returns page contents as a combined context string.", "deprecated": true, "oneOf": [ { "type": "boolean", "description": "Deprecated: Use highlights or text instead. Returns page contents as a combined context string.", "example": true, "deprecated": true }, { "type": "object", "properties": { "maxCharacters": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Deprecated. Maximum character limit for the context string. Maximum supported value is 10000.", "example": 10000 } }, "description": "Deprecated: Use highlights or text instead. Returns page contents as a combined context string.", "deprecated": true } ] }, "livecrawl": { "description": "Crawl strategy for fetching page content", "oneOf": [ { "type": "string", "enum": [ "never", "always", "fallback", "preferred" ] }, { "type": "string", "const": "auto" } ] }, "livecrawlTimeout": { "type": "integer", "exclusiveMinimum": 0, "maximum": 90000, "description": "The timeout for livecrawling in milliseconds.", "example": 1000, "default": 10000 }, "maxAgeHours": { "type": "integer", "minimum": -1, "maximum": 720, "description": "Maximum age of cached content in hours. Positive values use cached content if it is less than this many hours old; 0 fetches fresh content and is the supported way to apply text rendering options to newly fetched pages; -1 always uses cache; omitted uses fallback fetching when cached content is unavailable. Maximum supported value is 720 hours.", "example": 24 }, "filterEmptyResults": { "type": "boolean", "description": "Filter out results with no content" }, "subpages": { "type": "integer", "minimum": 0, "maximum": 100, "description": "The number of subpages to crawl. The actual number crawled may be limited by system constraints.", "example": 1, "default": 0 }, "subpageTarget": { "description": "Term to find specific subpages of search results. Can be a single string or an array of strings.", "example": "sources", "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "minItems": 0, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } } ] } }, "description": "Content extraction options applied to each search result. All fields are optional." }, "SearchMonitorTrigger": { "type": "object", "properties": { "type": { "type": "string", "const": "interval", "description": "The type of trigger. Currently only `interval` is supported.", "default": "interval" }, "period": { "type": "string", "description": "A duration string specifying how often the monitor runs (e.g., \"1h\", \"6h\", \"1d\", \"7d\"). Single-unit only. Minimum interval is 1 hour. The schedule is anchored to the monitor's creation time (e.g., a daily monitor created at 2:30 PM runs daily around 2:30 PM).", "example": "6h" } }, "required": [ "type", "period" ] }, "SearchMonitorOutputSchema": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "description": { "type": "string" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "object" }, "description": { "type": "string" }, "properties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, "required": { "type": "array", "items": { "type": "string" } }, "additionalProperties": { "type": "boolean" } }, "required": [ "type" ], "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ], "description": "JSON schema for synthesized output. Supported root types are \"text\" and \"object\". When provided, the response includes an output object whose content matches this schema. Works with every search type and adds about 2 seconds of synthesis latency on top of the selected search type.", "type": "object" }, { "type": "null" } ], "description": "Controls the format of the run output. Defaults to `{ \"type\": \"text\" }` if not specified. When `type` is `\"text\"`, the output is a plain text summary. When `type` is `\"object\"`, the output is structured JSON. If no `properties` are specified with `\"object\"` type, a schema is inferred automatically; otherwise the output adheres to the provided schema." }, "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.", "example": "Latest developments in LLM capabilities" }, "numResults": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of results to return. Limits vary by search type. The maximum public limit is 100 results. Contact sales (hello@exa.ai) to discuss higher limits.", "example": 10, "default": 10 }, "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.", "example": { "slack_channel_id": "C123ABC", "slack_thread_id": "1745444400.123456", "user_id": "U123ABC" } }, { "type": "null" } ], "description": "Update metadata. Set to null to remove. Echoed back in webhook deliveries so you can route updates to systems like Slack.", "example": { "slack_channel_id": "C123ABC", "slack_thread_id": "1745444400.123456", "user_id": "U123ABC" } }, "webhook": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "The HTTPS URL to receive webhook events. Must not point to localhost or private IP ranges." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "monitor.created", "monitor.updated", "monitor.deleted", "monitor.run.created", "monitor.run.completed" ] }, "description": "Which events to subscribe to. Defaults to all events if not specified." } }, "description": "Partial webhook params to merge. All fields are optional for updates." } } }, "CreateAgentRunRequest": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "Natural-language question or instructions for the request.", "example": "What are the most important AI infrastructure funding rounds announced this week?" }, "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.", "example": "Prefer official sources and avoid duplicate results." }, "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" } ] }, "effort": { "$ref": "#/components/schemas/AgentEffort" }, "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.", "example": { "slack_channel_id": "C123ABC", "slack_thread_id": "1745444400.123456", "user_id": "U123ABC" } }, "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" } }, "required": [ "query" ] }, "AgentEffort": { "type": "string", "enum": [ "minimal", "low", "medium", "high", "xhigh", "auto", "max" ], "description": "Cost and reasoning effort preference for the run. `auto` lets Exa choose the appropriate effort. `max` is the highest-effort public beta 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.", "example": "agent_run_01j7x9v0m2n4p6q8r0s2t4v6w8" }, "AgentDataSource": { "type": "object", "properties": { "provider": { "description": "Exa Connect data provider to enable for the run. All provider tools are available by default.", "example": "fiber", "$ref": "#/components/schemas/AgentDataSourceProvider" } }, "required": [ "provider" ] }, "AgentDataSourceProvider": { "type": "string", "enum": [ "fiber", "financial_datasets", "similarweb", "baselayer", "affiliate", "particle", "jinko" ], "description": "Identifier of an Exa Connect data provider." }, "AgentBudget": { "type": "object", "properties": { "maxCostDollars": { "type": "number", "description": "Maximum amount this run can spend in US dollars. Accepts $1–$100 and applies only to `auto` and `max`; when omitted, the default cap is $5 for `auto` and $20 for `max`.", "example": 10 } }, "description": "Optional per-run spending limit for the metered `auto` and `max` efforts. Runs that finish early may cost less than the 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.", "example": { "slack_channel_id": "C123ABC", "slack_thread_id": "1745444400.123456", "user_id": "U123ABC" } } }, "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.", "example": "row-1" }, "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. One of `/search` or `/agent/runs` in v1.", "example": "/search" }, "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" ] }, "SearchResponse": { "oneOf": [ { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for the request.", "example": "b5947044c4b78efa9552a7c89b306d95" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResultOutput" }, "description": "A list of search results containing title, URL, published date, and author." }, "resolvedSearchType": { "description": "Deprecated legacy field. Current production responses may return an empty string; clients should not branch on this value.", "example": "", "deprecated": true, "type": "string" }, "context": { "type": "string", "description": "Deprecated. Combined context string from search results. Use highlights or text instead.", "deprecated": true }, "costDollars": { "$ref": "#/components/schemas/CostDollarsOutput" }, "searchTime": { "type": "number", "description": "Server-side processing time in milliseconds, measured at the gateway. Covers retrieval but may exclude later phases such as structured output synthesis, so it can be lower than end-to-end request latency.", "example": 312.4 }, "output": { "$ref": "#/components/schemas/SearchSynthesisOutputOutput" } }, "required": [ "results", "output" ], "additionalProperties": false }, { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for the request.", "example": "b5947044c4b78efa9552a7c89b306d95" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResultOutput" }, "description": "A list of search results containing title, URL, published date, and author." }, "resolvedSearchType": { "description": "Deprecated legacy field. Current production responses may return an empty string; clients should not branch on this value.", "example": "", "deprecated": true, "type": "string" }, "context": { "type": "string", "description": "Deprecated. Combined context string from search results. Use highlights or text instead.", "deprecated": true }, "costDollars": { "$ref": "#/components/schemas/CostDollarsOutput" }, "searchTime": { "type": "number", "description": "Server-side processing time in milliseconds, measured at the gateway. Covers retrieval but may exclude later phases such as structured output synthesis, so it can be lower than end-to-end request latency.", "example": 312.4 } }, "required": [ "results" ], "additionalProperties": false } ] }, "ErrorResponse": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for the request.", "example": "b5947044c4b78efa9552a7c89b306d95" }, "error": { "type": "string", "description": "Human-readable message describing the error.", "example": "Invalid API key" }, "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.", "examples": [ "DEFAULT_ERROR", "INTERNAL_ERROR", "INVALID_API_KEY", "INVALID_REQUEST", "INVALID_REQUEST_BODY", "INVALID_REQUEST_QUERY", "INVALID_JSON_SCHEMA", "INVALID_NUM_RESULTS", "NUM_RESULTS_EXCEEDED", "NO_MORE_CREDITS", "API_KEY_BUDGET_EXCEEDED", "TEAM_BUDGET_EXCEEDED", "NO_CONTENT_FOUND", "PROHIBITED_CONTENT", "INSUFFICIENT_SCOPE", "UNABLE_TO_GENERATE_RESPONSE", "UNSUPPORTED_PUBLICATION_INCLUDE_FILTER", "SUBPAGES_LIMIT_EXCEEDED", "FEATURE_DISABLED", "INVALID_URLS", "FETCH_DOCUMENT_ERROR", "TEAM_BLOCKED", "NOT_FOUND", "RATE_LIMIT_EXCEEDED" ] } }, "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.", "example": "b5947044c4b78efa9552a7c89b306d95" }, "error": { "type": "string", "description": "Human-readable message describing the error.", "example": "Payment required to access this resource" }, "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.", "examples": [ "DEFAULT_ERROR", "INTERNAL_ERROR", "INVALID_API_KEY", "INVALID_REQUEST", "INVALID_REQUEST_BODY", "INVALID_REQUEST_QUERY", "INVALID_JSON_SCHEMA", "INVALID_NUM_RESULTS", "NUM_RESULTS_EXCEEDED", "NO_MORE_CREDITS", "API_KEY_BUDGET_EXCEEDED", "TEAM_BUDGET_EXCEEDED", "NO_CONTENT_FOUND", "PROHIBITED_CONTENT", "INSUFFICIENT_SCOPE", "UNABLE_TO_GENERATE_RESPONSE", "UNSUPPORTED_PUBLICATION_INCLUDE_FILTER", "SUBPAGES_LIMIT_EXCEEDED", "FEATURE_DISABLED", "INVALID_URLS", "FETCH_DOCUMENT_ERROR", "TEAM_BLOCKED", "NOT_FOUND", "RATE_LIMIT_EXCEEDED" ] }, "x402Version": { "type": "number", "description": "Version of the x402 protocol used to build this challenge.", "example": 2 }, "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.", "example": "b5947044c4b78efa9552a7c89b306d95" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResultOutput" } }, "context": { "type": "string", "description": "Deprecated. Combined context string from search results. Use highlights or text instead.", "deprecated": true }, "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.", "example": "https://example.com" }, "status": { "type": "string", "enum": [ "success", "error" ], "description": "Status of the content fetch operation.", "example": "success" }, "source": { "description": "Where the returned content was sourced from.", "type": "string", "enum": [ "cached", "crawled" ] }, "error": { "anyOf": [ { "type": "object", "properties": { "tag": { "description": "Specific error type.", "example": "CRAWL_NOT_FOUND", "type": "string" }, "httpStatusCode": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 599 }, { "type": "null" } ], "description": "The corresponding HTTP status code.", "example": 404 } }, "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, measured at the gateway. Covers retrieval but may exclude later phases such as structured output synthesis, so it can be lower than end-to-end request latency.", "example": 312.4 } }, "additionalProperties": false }, "AnswerResponse": { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for the request.", "example": "b5947044c4b78efa9552a7c89b306d95" }, "answer": { "description": "The generated answer based on search results. Returns a string by default, or a structured object matching the provided outputSchema.", "example": "$350 billion.", "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.", "example": "SpaceX valued at $350bn as company agrees to buy shares from ..." }, "url": { "type": "string", "description": "The URL of the search result.", "example": "https://www.theguardian.com/science/2024/dec/11/spacex-valued-at-350bn-as-company-agrees-to-buy-shares-from-employees", "format": "uri" }, "publishedDate": { "description": "An estimate of the creation date, from parsing HTML content. Format is YYYY-MM-DD.", "example": "2023-11-16T01:36:32.547Z", "format": "date-time", "type": "string" }, "author": { "description": "If available, the author of the content.", "example": "Humza Naveed", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "description": "The temporary ID for the document. Useful for the /contents endpoint.", "example": "https://arxiv.org/abs/2307.06435", "type": "string" }, "image": { "description": "The URL of an image associated with the search result, if available.", "example": "https://arxiv.org/pdf/2307.06435.pdf/page_1.png", "format": "uri", "type": "string" }, "favicon": { "description": "The URL of the favicon for the search result's domain.", "example": "https://arxiv.org/favicon.ico", "format": "uri", "type": "string" }, "text": { "description": "The full text content of each source. Only present when text contents are requested.", "example": "SpaceX valued at $350bn as company agrees to buy shares from ...", "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.", "example": "b5947044c4b78efa9552a7c89b306d95" }, "context": { "type": "string", "description": "Deprecated. Combined context string from search results. Use highlights or text instead.", "deprecated": true }, "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, measured at the gateway. Covers retrieval but may exclude later phases such as structured output synthesis, so it can be lower than end-to-end request latency.", "example": 312.4 } }, "additionalProperties": false }, "FindSimilarResult": { "type": "object", "properties": { "title": { "type": "string", "description": "The title of the search result.", "example": "A Comprehensive Overview of Large Language Models" }, "url": { "type": "string", "description": "The URL of the search result.", "example": "https://arxiv.org/pdf/2307.06435.pdf", "format": "uri" }, "publishedDate": { "description": "An estimate of the creation date, from parsing HTML content. Format is YYYY-MM-DD.", "example": "2023-11-16T01:36:32.547Z", "format": "date-time", "type": "string" }, "author": { "description": "If available, the author of the content.", "example": "Humza Naveed", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "description": "The temporary ID for the document. Useful for the /contents endpoint.", "example": "https://arxiv.org/abs/2307.06435", "type": "string" }, "image": { "description": "The URL of an image associated with the search result, if available.", "example": "https://arxiv.org/pdf/2307.06435.pdf/page_1.png", "format": "uri", "type": "string" }, "favicon": { "description": "The URL of the favicon for the search result's domain.", "example": "https://arxiv.org/favicon.ico", "format": "uri", "type": "string" }, "text": { "description": "The full content text of the search result.", "example": "Abstract Large Language Models (LLMs) have recently demonstrated remarkable capabilities...", "type": "string" }, "highlights": { "description": "Array of highlights extracted from the search result content.", "example": [ "Such requirements have limited their adoption..." ], "type": "array", "items": { "type": "string" } }, "highlightScores": { "description": "Array of cosine similarity scores for each highlighted snippet.", "example": [ 0.4600165784358978 ], "type": "array", "items": { "type": "number", "format": "float" } }, "summary": { "description": "Summary of the webpage.", "example": "This overview paper on Large Language Models (LLMs) highlights key developments...", "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.", "example": "A Comprehensive Overview of Large Language Models" }, "url": { "type": "string", "description": "The URL of the search result.", "example": "https://arxiv.org/pdf/2307.06435.pdf", "format": "uri" }, "publishedDate": { "description": "An estimate of the creation date, from parsing HTML content. Format is YYYY-MM-DD.", "example": "2023-11-16T01:36:32.547Z", "format": "date-time", "type": "string" }, "author": { "description": "If available, the author of the content.", "example": "Humza Naveed", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "description": "The temporary ID for the document. Useful for the /contents endpoint.", "example": "https://arxiv.org/abs/2307.06435", "type": "string" }, "image": { "description": "The URL of an image associated with the search result, if available.", "example": "https://arxiv.org/pdf/2307.06435.pdf/page_1.png", "format": "uri", "type": "string" }, "favicon": { "description": "The URL of the favicon for the search result's domain.", "example": "https://arxiv.org/favicon.ico", "format": "uri", "type": "string" } }, "required": [ "title", "url" ], "additionalProperties": false } }, "entities": { "description": "Structured entity data for company, person, or publication search results. Returned for supported entity-backed categories.", "type": "array", "items": { "oneOf": [ { "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 }, { "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 }, { "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 } ], "type": "object" } }, "extras": { "description": "Results from extras.", "example": { "links": [] }, "type": "object", "properties": { "links": { "description": "Array of links from the search result.", "example": [], "type": "array", "items": { "type": "string" } } }, "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.", "example": 0.82, "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.", "example": { "slack_channel_id": "C123ABC", "slack_thread_id": "1745444400.123456", "user_id": "U123ABC" } }, { "type": "null" } ], "description": "Optional key-value metadata for your own tracking. Echoed back in webhook deliveries so you can route updates to systems like Slack.", "example": { "slack_channel_id": "C123ABC", "slack_thread_id": "1745444400.123456", "user_id": "U123ABC" } }, "webhook": { "$ref": "#/components/schemas/SearchMonitorWebhookOutput" }, "nextRunAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the next scheduled run will occur. Null if no trigger is set.", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the monitor was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the monitor was last updated" }, "webhookSecret": { "type": "string", "description": "The secret used to verify webhook signatures. This is only returned once at creation time. Store it securely." } }, "required": [ "id", "name", "status", "search", "trigger", "outputSchema", "metadata", "webhook", "nextRunAt", "createdAt", "updatedAt", "webhookSecret" ], "additionalProperties": false }, "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.", "example": { "slack_channel_id": "C123ABC", "slack_thread_id": "1745444400.123456", "user_id": "U123ABC" } }, { "type": "null" } ], "description": "Optional key-value metadata for your own tracking. Echoed back in webhook deliveries so you can route updates to systems like Slack.", "example": { "slack_channel_id": "C123ABC", "slack_thread_id": "1745444400.123456", "user_id": "U123ABC" } }, "webhook": { "$ref": "#/components/schemas/SearchMonitorWebhookOutput" }, "nextRunAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the next scheduled run will occur. Null if no trigger is set.", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the monitor was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the monitor was last updated" } }, "required": [ "id", "name", "status", "search", "trigger", "outputSchema", "metadata", "webhook", "nextRunAt", "createdAt", "updatedAt" ], "additionalProperties": false }, "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." }, "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" } ] }, "output": { "$ref": "#/components/schemas/AgentRunOutput" }, "usage": { "$ref": "#/components/schemas/AgentUsage" }, "costDollars": { "$ref": "#/components/schemas/AgentCostDollars" } }, "required": [ "id", "object", "status", "stopReason", "createdAt", "completedAt", "request", "output", "usage", "costDollars" ], "additionalProperties": false }, "AgentRunStatus": { "type": "string", "enum": [ "queued", "running", "completed", "failed", "cancelled" ] }, "AgentStopReason": { "type": "string", "enum": [ "schema_satisfied", "budget_reached", "stopped", "error", "cancelled" ] }, "AgentRunRequest": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "Natural-language question or instructions for the request.", "example": "What are the most important AI infrastructure funding rounds announced this week?" }, "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.", "example": "Prefer official sources and avoid duplicate results." }, "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" } ] }, "effort": { "$ref": "#/components/schemas/AgentEffort" }, "previousRunId": { "$ref": "#/components/schemas/AgentRunId" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Caller-provided key-value metadata for your own tracking.", "example": { "slack_channel_id": "C123ABC", "slack_thread_id": "1745444400.123456", "user_id": "U123ABC" } }, "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." }, "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.", "example": "structured.companies[0].sourceUrl" }, "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": "integer", "minimum": 0 }, "emails": { "type": "integer", "minimum": 0 }, "phoneNumbers": { "type": "integer", "minimum": 0 }, "dataSources": { "$ref": "#/components/schemas/AgentDataSourceUsage" } }, "required": [ "agentComputeUnits", "searches", "emails", "phoneNumbers" ], "additionalProperties": false }, "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." }, "AgentErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/AgentError" } }, "required": [ "error" ], "additionalProperties": false }, "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" } }, "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.", "example": "batch_01j7x9v0m2n4p6q8r0s2t4v6w8" }, "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 presigned download URL for the batch results file (JSONL), or `null` until the batch completes. This is a direct object-store download link, not an API route; fetch it as-is and re-fetch the batch to mint a fresh URL once it expires." }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "Caller-provided key-value metadata for your own tracking.", "example": { "slack_channel_id": "C123ABC", "slack_thread_id": "1745444400.123456", "user_id": "U123ABC" } } }, "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": [ { "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": "OpenAI-compatible streamed completion choices with internal provider fields removed." } }, "required": [ "choices" ], "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, { "type": "object", "properties": { "citations": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "The title of the search result.", "example": "SpaceX valued at $350bn as company agrees to buy shares from ..." }, "url": { "type": "string", "description": "The URL of the search result.", "example": "https://www.theguardian.com/science/2024/dec/11/spacex-valued-at-350bn-as-company-agrees-to-buy-shares-from-employees", "format": "uri" }, "publishedDate": { "description": "An estimate of the creation date, from parsing HTML content. Format is YYYY-MM-DD.", "example": "2023-11-16T01:36:32.547Z", "format": "date-time", "type": "string" }, "author": { "description": "If available, the author of the content.", "example": "Humza Naveed", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "description": "The temporary ID for the document. Useful for the /contents endpoint.", "example": "https://arxiv.org/abs/2307.06435", "type": "string" }, "image": { "description": "The URL of an image associated with the search result, if available.", "example": "https://arxiv.org/pdf/2307.06435.pdf/page_1.png", "format": "uri", "type": "string" }, "favicon": { "description": "The URL of the favicon for the search result's domain.", "example": "https://arxiv.org/favicon.ico", "format": "uri", "type": "string" }, "text": { "description": "The full text content of each source. Only present when text contents are requested.", "example": "SpaceX valued at $350bn as company agrees to buy shares from ...", "type": "string" } }, "required": [ "title", "url" ], "additionalProperties": false }, "description": "Search results cited by the final streamed answer." } }, "required": [ "citations" ], "additionalProperties": false }, { "type": "object", "properties": { "costDollars": { "$ref": "#/components/schemas/CostDollarsOutput" }, "requestId": { "type": "string", "description": "Unique identifier for the request.", "example": "b5947044c4b78efa9552a7c89b306d95" } }, "required": [ "costDollars" ], "additionalProperties": false }, { "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.", "example": "b5947044c4b78efa9552a7c89b306d95" } }, "required": [ "error" ], "additionalProperties": false } }, "required": [ "tag", "payload" ], "additionalProperties": false } ] }, "SearchStreamChunk": { "oneOf": [ { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for the request.", "example": "b5947044c4b78efa9552a7c89b306d95" }, "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 }, { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for the request.", "example": "b5947044c4b78efa9552a7c89b306d95" }, "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 }, { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for the request.", "example": "b5947044c4b78efa9552a7c89b306d95" }, "type": { "type": "string", "const": "results" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResultOutput" } } }, "required": [ "type", "results" ], "additionalProperties": false }, { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for the request.", "example": "b5947044c4b78efa9552a7c89b306d95" }, "type": { "type": "string", "const": "stream-reset" }, "streamReset": { "type": "boolean", "const": true } }, "required": [ "type", "streamReset" ], "additionalProperties": false }, { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for the request.", "example": "b5947044c4b78efa9552a7c89b306d95" }, "type": { "type": "string", "const": "done" }, "output": { "anyOf": [ { "$ref": "#/components/schemas/SearchSynthesisOutputOutput" }, { "type": "null" } ] }, "searchTime": { "type": "number", "description": "Server-side processing time in milliseconds, measured at the gateway. Covers retrieval but may exclude later phases such as structured output synthesis, so it can be lower than end-to-end request latency.", "example": 312.4 }, "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 }, { "type": "object", "properties": { "requestId": { "type": "string", "description": "Unique identifier for the request.", "example": "b5947044c4b78efa9552a7c89b306d95" }, "type": { "type": "string", "const": "error" }, "error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "additionalProperties": false } }, "required": [ "type", "error" ], "additionalProperties": false } ], "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" }, "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 }, "SearchResultOutput": { "type": "object", "properties": { "title": { "type": "string", "description": "The title of the search result.", "example": "A Comprehensive Overview of Large Language Models" }, "url": { "type": "string", "description": "The URL of the search result.", "example": "https://arxiv.org/pdf/2307.06435.pdf", "format": "uri" }, "publishedDate": { "description": "An estimate of the creation date, from parsing HTML content. Format is YYYY-MM-DD.", "example": "2023-11-16T01:36:32.547Z", "format": "date-time", "type": "string" }, "author": { "description": "If available, the author of the content.", "example": "Humza Naveed", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "description": "The temporary ID for the document. Useful for the /contents endpoint.", "example": "https://arxiv.org/abs/2307.06435", "type": "string" }, "image": { "description": "The URL of an image associated with the search result, if available.", "example": "https://arxiv.org/pdf/2307.06435.pdf/page_1.png", "format": "uri", "type": "string" }, "favicon": { "description": "The URL of the favicon for the search result's domain.", "example": "https://arxiv.org/favicon.ico", "format": "uri", "type": "string" }, "text": { "description": "The full content text of the search result.", "example": "Abstract Large Language Models (LLMs) have recently demonstrated remarkable capabilities...", "type": "string" }, "highlights": { "description": "Array of highlights extracted from the search result content.", "example": [ "Such requirements have limited their adoption..." ], "type": "array", "items": { "type": "string" } }, "highlightScores": { "description": "Array of cosine similarity scores for each highlighted snippet.", "example": [ 0.4600165784358978 ], "type": "array", "items": { "type": "number", "format": "float" } }, "summary": { "description": "Summary of the webpage.", "example": "This overview paper on Large Language Models (LLMs) highlights key developments...", "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.", "example": "A Comprehensive Overview of Large Language Models" }, "url": { "type": "string", "description": "The URL of the search result.", "example": "https://arxiv.org/pdf/2307.06435.pdf", "format": "uri" }, "publishedDate": { "description": "An estimate of the creation date, from parsing HTML content. Format is YYYY-MM-DD.", "example": "2023-11-16T01:36:32.547Z", "format": "date-time", "type": "string" }, "author": { "description": "If available, the author of the content.", "example": "Humza Naveed", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "description": "The temporary ID for the document. Useful for the /contents endpoint.", "example": "https://arxiv.org/abs/2307.06435", "type": "string" }, "image": { "description": "The URL of an image associated with the search result, if available.", "example": "https://arxiv.org/pdf/2307.06435.pdf/page_1.png", "format": "uri", "type": "string" }, "favicon": { "description": "The URL of the favicon for the search result's domain.", "example": "https://arxiv.org/favicon.ico", "format": "uri", "type": "string" } }, "required": [ "title", "url" ], "additionalProperties": false } }, "entities": { "description": "Structured entity data for company, person, or publication search results. Returned for supported entity-backed categories.", "type": "array", "items": { "oneOf": [ { "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 }, { "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 }, { "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 } ], "type": "object" } }, "extras": { "description": "Results from extras.", "example": { "links": [] }, "type": "object", "properties": { "links": { "description": "Array of links from the search result.", "example": [], "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "required": [ "title", "url" ], "additionalProperties": false }, "CostDollarsOutput": { "type": "object", "properties": { "total": { "description": "Estimated total dollar cost for the completed request. This response value is not an invoice record.", "example": 0.007, "format": "float", "type": "number" }, "search": { "description": "Endpoint-dependent estimated search cost breakdown by retrieval mode. Instant, fast, and auto search responses may include neural search cost. Deep search modes may be reflected only in total.", "type": "object", "properties": { "neural": { "description": "Cost of neural search operations.", "example": 0.007, "format": "float", "type": "number" }, "keyword": { "description": "Cost of keyword search operations.", "example": 0.0025, "format": "float", "type": "number" } }, "additionalProperties": false }, "summary": { "description": "Cost of synthesized summary generation for search requests.", "example": 0.005, "format": "float", "type": "number" }, "contents": { "description": "Estimated cost breakdown for standalone content retrieval (text, highlights, and summaries billed outside the bundled search price).", "type": "object", "properties": { "text": { "description": "Cost of text extraction.", "example": 0.001, "format": "float", "type": "number" }, "highlights": { "description": "Cost of highlight extraction.", "example": 0.001, "format": "float", "type": "number" }, "summary": { "description": "Cost of per-result summary generation.", "example": 0.001, "format": "float", "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false, "description": "Endpoint-dependent estimated dollar cost breakdown for the completed request. Billing is computed from usage counters rather than this response object." }, "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." }, "SearchMonitorSearchOutput": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "The query string for the search.", "example": "Latest developments in LLM capabilities" }, "numResults": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of results to return. Limits vary by search type. The maximum public limit is 100 results. Contact sales (hello@exa.ai) to discuss higher limits.", "example": 10, "default": 10 }, "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": 10000, "description": "Maximum character limit for the full page text. Useful for controlling response size and API costs. Maximum supported value is 10000.", "example": 1000 }, { "type": "null" } ] }, "includeHtmlTags": { "anyOf": [ { "type": "boolean", "description": "If true, include lightweight HTML tags in returned text instead of plain markdown-style text. Use maxAgeHours: 0 when you need this applied to freshly fetched content.", "example": false, "default": false }, { "type": "null" } ] }, "verbosity": { "anyOf": [ { "type": "string", "enum": [ "compact", "standard", "full" ], "description": "Controls text rendering verbosity. compact focuses on main content, standard includes more surrounding page context, and full requests the most complete rendered text. Some pages may produce identical standard and full output. Use maxAgeHours: 0 when you need this applied to freshly fetched content.", "example": "standard", "default": "compact" }, { "type": "null" } ] }, "includeSections": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "header", "navigation", "banner", "body", "sidebar", "footer", "metadata" ] }, "description": "Best-effort. Only include content classified into these semantic page sections. Section classification may be unavailable or incomplete for some pages; validate output if strict filtering is required. Use maxAgeHours: 0 when you need this applied to freshly fetched content.", "example": [ "body", "header" ] }, { "type": "null" } ] }, "excludeSections": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "header", "navigation", "banner", "body", "sidebar", "footer", "metadata" ] }, "description": "Exclude content classified into these semantic page sections. Section classification is best-effort. Use maxAgeHours: 0 when you need this applied to freshly fetched content.", "example": [ "navigation", "footer", "sidebar" ] }, { "type": "null" } ] } }, "additionalProperties": false, "title": "Advanced text options", "description": "Advanced options for controlling text extraction. Use this when you need to limit text length or include HTML structure." } ] }, "highlights": { "description": "Text snippets the LLM identifies as most relevant from each page.", "oneOf": [ { "type": "boolean", "title": "Simple highlights retrieval", "description": "If true, returns highlights with default settings. If false, disables highlights.", "default": false }, { "type": "object", "properties": { "query": { "anyOf": [ { "type": "string", "description": "Custom query that guides which highlights the LLM picks.", "example": "Key advancements" }, { "type": "null" } ] }, "maxCharacters": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Maximum number of characters to return for highlights. Controls the total length of highlight text returned per URL. Maximum supported value is 10000.", "example": 2000 }, { "type": "null" } ] }, "numSentences": { "anyOf": [ { "type": "integer", "minimum": 1, "description": "Deprecated and will be removed in a future release. Currently mapped to a character budget of about 1333 characters per sentence. Pass highlights: true for default highlights, or { query } to guide selection with your own query.", "example": 1, "deprecated": true }, { "type": "null" } ] }, "highlightsPerUrl": { "anyOf": [ { "type": "integer", "minimum": 1, "description": "Deprecated and will be removed in a future release. Currently ignored. Pass highlights: true for default highlights, or { query } to guide selection with your own query.", "example": 1, "deprecated": true }, { "type": "null" } ] } }, "additionalProperties": false, "title": "Advanced highlights options", "description": "Advanced options for steering highlight extraction. Pass highlights: true for the highest-quality default; supply this object only when you need to guide selection with your own query." } ] }, "summary": { "description": "Return an LLM-generated summary. Pass `true` for defaults, or an object with `query` and `maxTokens`.", "oneOf": [ { "type": "boolean" }, { "type": "object", "properties": { "query": { "anyOf": [ { "type": "string", "description": "Custom query for the LLM-generated summary.", "example": "Main developments" }, { "type": "null" } ] }, "maxTokens": { "type": "integer", "minimum": 1, "description": "Maximum tokens for the generated summary." } }, "additionalProperties": false } ] }, "extras": { "type": "object", "properties": { "links": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Number of URLs to return from each webpage.", "example": 1, "default": 0 }, { "type": "null" } ] }, "imageLinks": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Number of images to return for each result.", "example": 1, "default": 0 }, { "type": "null" } ] }, "richImageLinks": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Number of rich image links to return for each result.", "default": 0 }, { "type": "null" } ] }, "richLinks": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Number of rich links to return for each result.", "default": 0 }, { "type": "null" } ] }, "codeBlocks": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000, "description": "Number of code blocks to return for each result.", "default": 0 }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Extra parameters to pass." }, "context": { "description": "Deprecated: Use highlights or text instead. Returns page contents as a combined context string.", "deprecated": true, "oneOf": [ { "type": "boolean", "description": "Deprecated: Use highlights or text instead. Returns page contents as a combined context string.", "example": true, "deprecated": true }, { "type": "object", "properties": { "maxCharacters": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Deprecated. Maximum character limit for the context string. Maximum supported value is 10000.", "example": 10000 } }, "additionalProperties": false, "description": "Deprecated: Use highlights or text instead. Returns page contents as a combined context string.", "deprecated": true } ] }, "livecrawl": { "description": "Crawl strategy for fetching page content", "oneOf": [ { "type": "string", "enum": [ "never", "always", "fallback", "preferred" ] }, { "type": "string", "const": "auto" } ] }, "livecrawlTimeout": { "type": "integer", "exclusiveMinimum": 0, "maximum": 90000, "description": "The timeout for livecrawling in milliseconds.", "example": 1000, "default": 10000 }, "maxAgeHours": { "type": "integer", "minimum": -1, "maximum": 720, "description": "Maximum age of cached content in hours. Positive values use cached content if it is less than this many hours old; 0 fetches fresh content and is the supported way to apply text rendering options to newly fetched pages; -1 always uses cache; omitted uses fallback fetching when cached content is unavailable. Maximum supported value is 720 hours.", "example": 24 }, "filterEmptyResults": { "type": "boolean", "description": "Filter out results with no content" }, "subpages": { "type": "integer", "minimum": 0, "maximum": 100, "description": "The number of subpages to crawl. The actual number crawled may be limited by system constraints.", "example": 1, "default": 0 }, "subpageTarget": { "description": "Term to find specific subpages of search results. Can be a single string or an array of strings.", "example": "sources", "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "minItems": 0, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } } ] } }, "additionalProperties": false, "description": "Content extraction options applied to each search result. All fields are optional." }, "SearchMonitorTriggerOutput": { "type": "object", "properties": { "type": { "type": "string", "const": "interval", "description": "The type of trigger. Currently only `interval` is supported.", "default": "interval" }, "period": { "type": "string", "description": "A duration string specifying how often the monitor runs (e.g., \"1h\", \"6h\", \"1d\", \"7d\"). Single-unit only. Minimum interval is 1 hour. The schedule is anchored to the monitor's creation time (e.g., a daily monitor created at 2:30 PM runs daily around 2:30 PM).", "example": "6h" } }, "required": [ "type", "period" ], "additionalProperties": false }, "SearchMonitorOutputSchemaOutput": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "description": { "type": "string" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "object" }, "description": { "type": "string" }, "properties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } }, "required": { "type": "array", "items": { "type": "string" } }, "additionalProperties": { "type": "boolean" } }, "required": [ "type" ], "additionalProperties": { "$ref": "#/components/schemas/JsonValue" } } ], "description": "JSON schema for synthesized output. Supported root types are \"text\" and \"object\". When provided, the response includes an output object whose content matches this schema. Works with every search type and adds about 2 seconds of synthesis latency on top of the selected search type.", "type": "object" }, { "type": "null" } ], "description": "Controls the format of the run output. Defaults to `{ \"type\": \"text\" }` if not specified. When `type` is `\"text\"`, the output is a plain text summary. When `type` is `\"object\"`, the output is structured JSON. If no `properties` are specified with `\"object\"` type, a schema is inferred automatically; otherwise the output adheres to the provided schema." }, "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.", "example": "fiber", "$ref": "#/components/schemas/AgentDataSourceProvider" } }, "required": [ "provider" ], "additionalProperties": false }, "AgentBudgetOutput": { "type": "object", "properties": { "maxCostDollars": { "type": "number", "description": "Maximum amount this run can spend in US dollars. Accepts $1–$100 and applies only to `auto` and `max`; when omitted, the default cap is $5 for `auto` and $20 for `max`.", "example": 10 } }, "additionalProperties": false, "description": "Optional per-run spending limit for the metered `auto` and `max` efforts. Runs that finish early may cost less than the limit." }, "CompanyEntity": { "type": [ "object" ], "properties": { "type": { "type": "string", "const": "company", "default": "company" } }, "required": [ "type" ], "title": "Company" }, "PersonEntity": { "type": [ "object" ], "properties": { "type": { "type": "string", "const": "person", "default": "person" } }, "required": [ "type" ], "title": "Person" }, "ArticleEntity": { "type": [ "object" ], "properties": { "type": { "type": "string", "const": "article", "default": "article" } }, "required": [ "type" ], "title": "Article" }, "ResearchPaperEntity": { "type": [ "object" ], "properties": { "type": { "type": "string", "const": "research_paper", "default": "research_paper" } }, "required": [ "type" ], "title": "Research Paper" }, "CustomEntity": { "type": [ "object" ], "properties": { "type": { "type": "string", "const": "custom", "default": "custom" }, "description": { "type": [ "string" ], "minLength": 2, "maxLength": 200 } }, "required": [ "type", "description" ], "title": "Custom" }, "Entity": { "oneOf": [ { "type": [ "object" ], "$ref": "#/components/schemas/CompanyEntity" }, { "type": [ "object" ], "$ref": "#/components/schemas/PersonEntity" }, { "type": [ "object" ], "$ref": "#/components/schemas/ArticleEntity" }, { "type": [ "object" ], "$ref": "#/components/schemas/ResearchPaperEntity" }, { "type": [ "object" ], "$ref": "#/components/schemas/CustomEntity" } ] }, "CreateCriterionParameters": { "type": [ "object" ], "properties": { "description": { "type": [ "string" ], "minLength": 1, "maxLength": 1000, "description": "The description of the criterion" } }, "required": [ "description" ] }, "CreateEnrichmentParameters": { "type": [ "object" ], "properties": { "description": { "type": [ "string" ], "minLength": 1, "maxLength": 5000, "description": "Provide a description of the enrichment task you want to perform to each Webset Item." }, "format": { "type": [ "string" ], "enum": [ "text", "date", "number", "options", "email", "phone", "url" ], "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." }, "options": { "type": [ "array" ], "items": { "type": [ "object" ], "properties": { "label": { "type": [ "string" ], "description": "The label of the option" } }, "required": [ "label" ] }, "minItems": 1, "maxItems": 150, "description": "When the format is options, the different options for the enrichment agent to choose from." }, "metadata": { "description": "Set of key-value pairs you want to associate with this object.", "type": [ "object" ], "additionalProperties": { "type": [ "string" ], "maxLength": 1000 } } }, "required": [ "description" ] }, "CreateWebsetParameters": { "type": [ "object" ], "properties": { "title": { "type": "string", "minLength": 1, "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": { "type": [ "object" ], "properties": { "query": { "type": [ "string" ], "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" ] }, "count": { "default": 10, "type": [ "number" ], "minimum": 1, "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." }, "entity": { "$ref": "#/components/schemas/Entity", "description": "Entity the Webset will return results for.\n\nIt is not required to provide it, we automatically detect the entity from all the information provided in the query. Only use this when you need more fine control." }, "criteria": { "type": [ "array" ], "items": { "type": [ "object" ], "$ref": "#/components/schemas/CreateCriterionParameters", "title": "CreateCriterionParameters" }, "minItems": 1, "maxItems": 5, "description": "Criteria every item is evaluated against.\n\nIt's not required to provide your own criteria, we automatically detect the criteria from all the information provided in the query. Only use this when you need more fine control." }, "maxPeoplePerCompany": { "type": [ "integer" ], "minimum": 1, "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." }, "recall": { "type": [ "boolean" ], "description": "Whether to provide an estimate of how many total relevant results could exist for this search.\nResult of the analysis will be available in the `recall` field within the search request." }, "exclude": { "type": [ "array" ], "items": { "type": [ "object" ], "properties": { "source": { "type": [ "string" ], "enum": [ "import", "webset" ] }, "id": { "type": [ "string" ], "minLength": 1, "description": "The ID of the source to exclude." } }, "required": [ "source", "id" ] }, "description": "Sources (existing imports or websets) to exclude from search results. Any results found within these sources will be omitted to prevent finding them during search." }, "scope": { "type": [ "array" ], "items": { "type": [ "object" ], "properties": { "source": { "type": [ "string" ], "enum": [ "import", "webset" ] }, "id": { "type": [ "string" ], "minLength": 1, "description": "The ID of the source to search." }, "relationship": { "type": [ "object" ], "properties": { "definition": { "type": [ "string" ], "description": "What the relationship of the entities you hope to find is relative to the entities contained in the provided source." }, "limit": { "type": [ "number" ], "minimum": 1, "maximum": 10 } }, "required": [ "definition", "limit" ] } }, "required": [ "source", "id" ] }, "description": "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." } }, "required": [ "query" ], "description": "Create initial search for the Webset." }, "import": { "type": [ "array" ], "items": { "type": [ "object" ], "properties": { "source": { "type": [ "string" ], "enum": [ "import", "webset" ] }, "id": { "type": [ "string" ], "minLength": 1, "description": "The ID of the source to import." }, "evaluate": { "type": [ "boolean" ], "description": "When true, items from this import will be evaluated against the search criteria. Requires a search to be provided." } }, "required": [ "source", "id" ] }, "description": "Import data from existing Websets and Imports into this Webset." }, "enrichments": { "type": [ "array" ], "items": { "type": [ "object" ], "$ref": "#/components/schemas/CreateEnrichmentParameters", "title": "CreateEnrichmentParameters" }, "description": "Add enrichments to extract additional data from found items.\n\nEnrichments automatically search for and extract specific information (like contact details, funding data, employee counts, etc.) from each item added to your Webset." }, "exclude": { "type": [ "array" ], "items": { "type": [ "object" ], "properties": { "source": { "type": [ "string" ], "enum": [ "import", "webset" ] }, "id": { "type": [ "string" ], "minLength": 1, "description": "The ID of the source to exclude." } }, "required": [ "source", "id" ] }, "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." }, "externalId": { "type": [ "string" ], "maxLength": 300, "description": "The external identifier for the webset.\n\nYou can use this to reference the Webset by your own internal identifiers." }, "metadata": { "description": "Set of key-value pairs you want to associate with this object.", "type": [ "object" ], "additionalProperties": { "type": [ "string" ], "maxLength": 1000 } } }, "examples": [ { "search": { "query": "Marketing agencies based in the US, that focus on consumer products.", "count": 10 } } ] }, "WebsetSearch": { "type": [ "object" ], "properties": { "id": { "type": [ "string" ], "description": "The unique identifier for the search" }, "object": { "type": "string", "const": "webset_search", "default": "webset_search" }, "status": { "type": [ "string" ], "enum": [ "created", "pending", "running", "completed", "canceled" ], "description": "The status of the search", "title": "WebsetSearchStatus" }, "websetId": { "type": [ "string" ], "description": "The unique identifier for the Webset this search belongs to" }, "query": { "description": "The query used to create the search.", "type": [ "string" ], "minLength": 1, "maxLength": 5000 }, "entity": { "$ref": "#/components/schemas/Entity", "description": "The entity the search will return results for.\n\nWhen no entity is provided during creation, we will automatically select the best entity based on the query.", "nullable": true }, "criteria": { "type": [ "array" ], "items": { "type": [ "object" ], "properties": { "description": { "description": "The description of the criterion", "type": [ "string" ], "minLength": 1, "maxLength": 1000 }, "successRate": { "type": [ "number" ], "minimum": 0, "maximum": 100, "description": "Value between 0 and 100 representing the percentage of results that meet the criterion." } }, "required": [ "description", "successRate" ] }, "description": "The criteria the search will use to evaluate the results. If not provided, we will automatically generate them for you." }, "count": { "type": [ "number" ], "minimum": 1, "description": "The number of results the search will attempt to find. The actual number of results may be less than this number depending on the search complexity." }, "maxPeoplePerCompany": { "type": "integer", "minimum": 1, "description": "The soft cap requested for matching people from the same current employer company, or null when no cap was requested.", "nullable": true }, "behavior": { "default": "override", "type": [ "string" ], "$ref": "#/components/schemas/WebsetSearchBehavior", "description": "The behavior of the search when it is added to a Webset.\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." }, "exclude": { "type": [ "array" ], "items": { "type": [ "object" ], "properties": { "source": { "type": [ "string" ], "enum": [ "import", "webset" ] }, "id": { "type": [ "string" ] } }, "required": [ "source", "id" ] }, "description": "Sources (existing imports or websets) used to omit certain results to be found during the search." }, "scope": { "type": [ "array" ], "items": { "type": [ "object" ], "properties": { "source": { "type": [ "string" ], "enum": [ "import", "webset" ] }, "id": { "type": [ "string" ] }, "relationship": { "type": [ "object" ], "properties": { "definition": { "type": [ "string" ], "description": "What the relationship of the entities you hope to find is relative to the entities contained in the provided source." }, "limit": { "type": [ "number" ], "minimum": 1, "maximum": 10 } }, "required": [ "definition", "limit" ] } }, "required": [ "source", "id" ] }, "description": "The scope of the search. By default, there is no scope - thus searching the web.\n\nIf provided during creation, the search will only be performed on the sources provided." }, "progress": { "type": [ "object" ], "properties": { "found": { "type": [ "number" ], "description": "The number of results found so far" }, "analyzed": { "type": [ "number" ], "description": "The number of results analyzed so far" }, "completion": { "type": [ "number" ], "minimum": 0, "maximum": 100, "description": "The completion percentage of the search" }, "timeLeft": { "type": "number", "description": "The estimated time remaining in seconds, null if unknown", "nullable": true } }, "required": [ "found", "analyzed", "completion", "timeLeft" ], "description": "The progress of the search" }, "recall": { "type": "object", "properties": { "expected": { "type": [ "object" ], "properties": { "total": { "type": [ "number" ], "description": "The estimated total number of potential matches" }, "confidence": { "type": [ "string" ], "enum": [ "high", "medium", "low" ], "description": "The confidence in the estimate" }, "bounds": { "type": [ "object" ], "properties": { "min": { "type": [ "number" ], "description": "The minimum estimated total number of potential matches" }, "max": { "type": [ "number" ], "description": "The maximum estimated total number of potential matches" } }, "required": [ "min", "max" ] } }, "required": [ "total", "confidence", "bounds" ] }, "reasoning": { "type": [ "string" ], "description": "The reasoning for the estimate" } }, "required": [ "expected", "reasoning" ], "description": "Recall metrics for the search, null if not yet computed or requested.", "nullable": true }, "metadata": { "default": {}, "description": "Set of key-value pairs you want to associate with this object.", "type": [ "object" ], "additionalProperties": { "type": [ "string" ], "maxLength": 1000 } }, "canceledAt": { "type": "string", "format": "date-time", "description": "The date and time the search was canceled", "nullable": true }, "canceledReason": { "type": "string", "$ref": "#/components/schemas/WebsetSearchCanceledReason", "description": "The reason the search was canceled", "nullable": true }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the search was created" }, "updatedAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the search was updated" } }, "required": [ "id", "object", "websetId", "status", "query", "entity", "criteria", "count", "maxPeoplePerCompany", "exclude", "scope", "progress", "recall", "canceledAt", "canceledReason", "createdAt", "updatedAt" ] }, "Import": { "type": [ "object" ], "properties": { "id": { "type": [ "string" ], "description": "The unique identifier for the Import" }, "object": { "type": [ "string" ], "enum": [ "import" ], "description": "The type of object" }, "status": { "type": [ "string" ], "enum": [ "pending", "processing", "completed", "failed", "canceled" ], "description": "The status of the Import" }, "format": { "type": [ "string" ], "enum": [ "csv", "webset" ], "description": "The format of the import." }, "entity": { "$ref": "#/components/schemas/Entity", "description": "The type of entity the import contains.", "nullable": true }, "title": { "type": [ "string" ], "description": "The title of the import" }, "count": { "type": [ "number" ], "description": "The number of entities in the import" }, "metadata": { "description": "Set of key-value pairs you want to associate with this object.", "type": [ "object" ], "additionalProperties": { "type": [ "string" ], "maxLength": 1000 } }, "failedReason": { "type": "string", "enum": [ "invalid_format", "invalid_file_content", "missing_identifier" ], "description": "The reason the import failed", "nullable": true }, "failedAt": { "type": "string", "format": "date-time", "description": "When the import failed", "nullable": true }, "failedMessage": { "type": "string", "description": "A human readable message of the import failure", "nullable": true }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "When the import was created" }, "updatedAt": { "type": [ "string" ], "format": "date-time", "description": "When the import was last updated" } }, "required": [ "id", "object", "status", "format", "entity", "title", "count", "metadata", "failedReason", "failedAt", "failedMessage", "createdAt", "updatedAt" ] }, "WebsetEnrichment": { "type": [ "object" ], "properties": { "id": { "type": [ "string" ], "description": "The unique identifier for the enrichment" }, "object": { "type": "string", "const": "webset_enrichment", "default": "webset_enrichment" }, "status": { "type": [ "string" ], "enum": [ "pending", "canceled", "completed" ], "description": "The status of the enrichment", "title": "WebsetEnrichmentStatus" }, "websetId": { "type": [ "string" ], "description": "The unique identifier for the Webset this enrichment belongs to." }, "title": { "type": "string", "description": "The title of the enrichment.\n\nThis will be automatically generated based on the description and format.", "nullable": true }, "description": { "type": [ "string" ], "description": "The description of the enrichment task provided during the creation of the enrichment." }, "format": { "type": "string", "$ref": "#/components/schemas/WebsetEnrichmentFormat", "description": "The format of the enrichment response.", "nullable": true }, "options": { "type": "array", "items": { "type": [ "object" ], "properties": { "label": { "type": [ "string" ], "description": "The label of the option" } }, "required": [ "label" ] }, "description": "When the format is options, the different options for the enrichment agent to choose from.", "title": "WebsetEnrichmentOptions", "nullable": true }, "instructions": { "type": "string", "description": "The instructions for the enrichment Agent.\n\nThis will be automatically generated based on the description and format.", "nullable": true }, "metadata": { "default": {}, "description": "The metadata of the enrichment", "type": [ "object" ], "additionalProperties": { "type": [ "string" ], "maxLength": 1000 } }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the enrichment was created" }, "updatedAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the enrichment was updated" } }, "required": [ "id", "object", "status", "websetId", "title", "description", "format", "options", "instructions", "createdAt", "updatedAt" ] }, "MonitorRun": { "type": [ "object" ], "properties": { "id": { "type": [ "string" ], "description": "The unique identifier for the Monitor Run" }, "object": { "type": [ "string" ], "enum": [ "monitor_run" ], "description": "The type of object" }, "status": { "type": [ "string" ], "enum": [ "created", "running", "completed", "canceled", "failed" ], "description": "The status of the Monitor Run" }, "monitorId": { "type": [ "string" ], "description": "The monitor that the run is associated with" }, "type": { "type": [ "string" ], "enum": [ "search", "refresh" ], "description": "The type of the Monitor Run" }, "completedAt": { "type": "string", "format": "date-time", "description": "When the run completed", "nullable": true }, "failedAt": { "type": "string", "format": "date-time", "description": "When the run failed", "nullable": true }, "failedReason": { "type": "string", "description": "The reason the run failed", "nullable": true }, "canceledAt": { "type": "string", "format": "date-time", "description": "When the run was canceled", "nullable": true }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "When the run was created" }, "updatedAt": { "type": [ "string" ], "format": "date-time", "description": "When the run was last updated" } }, "required": [ "id", "object", "monitorId", "status", "type", "completedAt", "failedAt", "failedReason", "canceledAt", "createdAt", "updatedAt" ] }, "Monitor": { "type": [ "object" ], "properties": { "id": { "type": [ "string" ], "description": "The unique identifier for the Monitor" }, "object": { "type": [ "string" ], "enum": [ "monitor" ], "description": "The type of object" }, "status": { "type": [ "string" ], "enum": [ "enabled", "disabled" ], "description": "The status of the Monitor" }, "websetId": { "type": [ "string" ], "description": "The id of the Webset the Monitor belongs to" }, "cadence": { "type": [ "object" ], "properties": { "cron": { "description": "Cron expression for monitor cadence (must be a valid Unix cron with 5 fields). The schedule must trigger at most once per day.", "type": [ "string" ] }, "timezone": { "description": "IANA timezone (e.g., \"America/New_York\")", "default": "Etc/UTC", "type": [ "string" ] } }, "required": [ "cron" ], "description": "How often the monitor will run" }, "behavior": { "type": [ "object" ], "properties": { "type": { "type": "string", "const": "search", "default": "search" }, "config": { "type": [ "object" ], "properties": { "query": { "type": [ "string" ], "minLength": 2, "maxLength": 10000, "description": "The query to search for. By default, the query from the last search is used." }, "criteria": { "type": [ "array" ], "items": { "type": [ "object" ], "properties": { "description": { "type": [ "string" ], "minLength": 2, "maxLength": 1000 } }, "required": [ "description" ] }, "maxItems": 5, "description": "The criteria to search for. By default, the criteria from the last search is used." }, "entity": { "$ref": "#/components/schemas/Entity", "title": "Entity", "description": "The entity to search for. By default, the entity from the last search/import is used." }, "count": { "type": [ "number" ], "exclusiveMinimum": 0, "description": "The maximum number of results to find" }, "behavior": { "default": "append", "type": [ "string" ], "enum": [ "override", "append" ], "description": "The behaviour of the Search when it is added to a Webset." } }, "required": [ "count" ], "description": "Specify the search parameters for the Monitor.\n\nBy default, the search parameters (query, entity and criteria) from the last search are used when no parameters are provided." } }, "required": [ "type", "config" ], "description": "Behavior to perform when monitor runs" }, "lastRun": { "type": "object", "$ref": "#/components/schemas/MonitorRun", "title": "MonitorRun", "description": "The last run of the monitor", "nullable": true }, "nextRunAt": { "type": "string", "format": "date-time", "description": "Date and time when the next run will occur in", "nullable": true }, "metadata": { "description": "Set of key-value pairs you want to associate with this object.", "type": [ "object" ], "additionalProperties": { "type": [ "string" ], "maxLength": 1000 } }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "When the monitor was created" }, "updatedAt": { "type": [ "string" ], "format": "date-time", "description": "When the monitor was last updated" } }, "required": [ "id", "object", "status", "websetId", "cadence", "behavior", "lastRun", "nextRunAt", "metadata", "createdAt", "updatedAt" ] }, "Webset": { "type": [ "object" ], "properties": { "id": { "type": [ "string" ], "description": "The unique identifier for the webset" }, "object": { "type": "string", "const": "webset", "default": "webset" }, "status": { "type": [ "string" ], "enum": [ "idle", "pending", "running", "paused" ], "description": "The status of the webset", "title": "WebsetStatus" }, "externalId": { "type": "string", "description": "The external identifier for the webset", "nullable": true }, "title": { "type": "string", "description": "The title of the webset", "nullable": true }, "searches": { "type": [ "array" ], "items": { "type": [ "object" ], "$ref": "#/components/schemas/WebsetSearch" }, "description": "The searches that have been performed on the webset." }, "imports": { "type": [ "array" ], "items": { "type": [ "object" ], "$ref": "#/components/schemas/Import" }, "description": "Imports that have been performed on the webset." }, "enrichments": { "type": [ "array" ], "items": { "type": [ "object" ], "$ref": "#/components/schemas/WebsetEnrichment" }, "description": "The Enrichments to apply to the Webset Items." }, "monitors": { "type": [ "array" ], "items": { "type": [ "object" ], "$ref": "#/components/schemas/Monitor" }, "description": "The Monitors for the Webset." }, "excludes": { "type": [ "array" ], "items": { "type": [ "object" ], "properties": { "source": { "type": [ "string" ], "enum": [ "import", "webset" ] }, "id": { "type": [ "string" ] } }, "required": [ "source", "id" ] }, "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." }, "metadata": { "default": {}, "description": "Set of key-value pairs you want to associate with this object.", "type": [ "object" ], "additionalProperties": { "type": [ "string" ], "maxLength": 1000 } }, "dashboardUrl": { "type": [ "string" ], "format": "uri", "description": "The URL to view the webset in the Exa dashboard" }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the webset was created" }, "updatedAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the webset was updated" } }, "required": [ "id", "object", "status", "externalId", "title", "searches", "imports", "enrichments", "monitors", "dashboardUrl", "createdAt", "updatedAt" ] }, "WebsetItemPersonProperties": { "type": [ "object" ], "properties": { "type": { "type": "string", "const": "person", "default": "person" }, "url": { "type": [ "string" ], "format": "uri", "description": "The URL of the person profile" }, "description": { "type": [ "string" ], "description": "Short description of the relevance of the person" }, "person": { "type": [ "object" ], "properties": { "name": { "type": [ "string" ], "description": "The name of the person" }, "location": { "type": "string", "description": "The location of the person", "nullable": true }, "position": { "type": "string", "description": "The current work position of the person", "nullable": true }, "company": { "type": "object", "properties": { "name": { "type": [ "string" ], "description": "The name of the company" }, "location": { "type": "string", "description": "The location the person is working at the company", "nullable": true } }, "required": [ "name", "location" ], "title": "WebsetItemPersonCompanyPropertiesFields", "nullable": true }, "pictureUrl": { "type": "string", "format": "uri", "description": "The image URL of the person", "nullable": true }, "workHistory": { "type": [ "array" ], "items": { "type": [ "object" ], "properties": { "title": { "type": "string", "description": "Job title or position", "nullable": true }, "location": { "type": "string", "description": "Work location", "nullable": true }, "dates": { "type": "object", "properties": { "from": { "type": "string", "description": "Start date", "nullable": true }, "to": { "type": "string", "description": "End date", "nullable": true } }, "required": [ "from", "to" ], "title": "WebsetItemPersonDateRange", "description": "Employment dates", "nullable": true }, "company": { "type": "object", "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" ], "title": "WebsetItemPersonWorkHistoryCompanyRef", "nullable": true } }, "required": [ "title", "location", "dates", "company" ], "title": "WebsetItemPersonWorkHistoryEntry" }, "description": "The work history of the person" }, "educationHistory": { "type": [ "array" ], "items": { "type": [ "object" ], "properties": { "degree": { "type": "string", "description": "Degree obtained", "nullable": true }, "dates": { "type": "object", "properties": { "from": { "type": "string", "description": "Start date", "nullable": true }, "to": { "type": "string", "description": "End date", "nullable": true } }, "required": [ "from", "to" ], "title": "WebsetItemPersonDateRange", "description": "Education dates", "nullable": true }, "institution": { "type": "object", "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" ], "title": "WebsetItemPersonEducationInstitutionRef", "nullable": true } }, "required": [ "degree", "dates", "institution" ], "title": "WebsetItemPersonEducationHistoryEntry" }, "description": "The education history of the person" } }, "required": [ "name", "location", "position", "company", "pictureUrl", "workHistory", "educationHistory" ], "title": "WebsetItemPersonPropertiesFields" } }, "required": [ "type", "url", "description", "person" ] }, "WebsetItemCompanyProperties": { "type": [ "object" ], "properties": { "type": { "type": "string", "const": "company", "default": "company" }, "url": { "type": [ "string" ], "format": "uri", "description": "The URL of the company website" }, "description": { "type": [ "string" ], "description": "Short description of the relevance of the company" }, "content": { "type": "string", "description": "The text content of the company website", "nullable": true }, "company": { "type": [ "object" ], "properties": { "name": { "type": [ "string" ], "description": "The name of the company" }, "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": { "type": "string", "format": "uri", "description": "The logo URL of the company", "nullable": true }, "foundedYear": { "type": "number", "description": "The year the company was founded", "nullable": true }, "headquarters": { "type": "object", "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" ], "title": "WebsetItemCompanyHeadquarters", "description": "The structured headquarters address of the company", "nullable": true }, "financials": { "type": "object", "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": { "type": "object", "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" ], "title": "WebsetItemCompanyFundingRound", "description": "The latest funding round", "nullable": true } }, "required": [ "revenueAnnual", "fundingTotal", "fundingLatestRound" ], "title": "WebsetItemCompanyFinancials", "description": "Financial information about the company", "nullable": true }, "webTraffic": { "type": "object", "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" ], "title": "WebsetItemCompanyWebTraffic", "description": "Web traffic metrics for the company", "nullable": true } }, "required": [ "name", "location", "employees", "industry", "about", "logoUrl", "foundedYear", "headquarters", "financials", "webTraffic" ], "title": "WebsetItemCompanyPropertiesFields" } }, "required": [ "type", "url", "description", "content", "company" ] }, "WebsetItemArticleProperties": { "type": [ "object" ], "properties": { "type": { "type": "string", "const": "article", "default": "article" }, "url": { "type": [ "string" ], "format": "uri", "description": "The URL of the article" }, "description": { "type": [ "string" ], "description": "Short description of the relevance of the article" }, "content": { "type": "string", "description": "The text content for the article", "nullable": true }, "article": { "type": [ "object" ], "properties": { "title": { "type": "string", "description": "The title of the article", "nullable": true }, "author": { "type": "string", "description": "The author(s) of the article", "nullable": true }, "publishedAt": { "type": "string", "description": "The date and time the article was published", "nullable": true } }, "required": [ "title", "author", "publishedAt" ], "title": "WebsetItemArticlePropertiesFields" } }, "required": [ "type", "url", "description", "content", "article" ] }, "WebsetItemResearchPaperProperties": { "type": [ "object" ], "properties": { "type": { "type": "string", "const": "research_paper", "default": "research_paper" }, "url": { "type": [ "string" ], "format": "uri", "description": "The URL of the research paper" }, "description": { "type": [ "string" ], "description": "Short description of the relevance of the research paper" }, "content": { "type": "string", "description": "The text content of the research paper", "nullable": true }, "researchPaper": { "type": [ "object" ], "properties": { "title": { "type": "string", "description": "The title of the research paper", "nullable": true }, "author": { "type": "string", "description": "The author(s) of the research paper", "nullable": true }, "publishedAt": { "type": "string", "description": "The date and time the research paper was published", "nullable": true } }, "required": [ "title", "author", "publishedAt" ], "title": "WebsetItemResearchPaperPropertiesFields" } }, "required": [ "type", "url", "description", "content", "researchPaper" ] }, "WebsetItemCustomProperties": { "type": [ "object" ], "properties": { "type": { "type": "string", "const": "custom", "default": "custom" }, "url": { "type": [ "string" ], "format": "uri", "description": "The URL of the Item" }, "description": { "type": [ "string" ], "description": "Short description of the Item" }, "content": { "type": "string", "description": "The text content of the Item", "nullable": true }, "custom": { "type": [ "object" ], "properties": { "title": { "type": "string", "description": "The title of the website", "nullable": true }, "author": { "type": "string", "description": "The author(s) of the website", "nullable": true }, "publishedAt": { "type": "string", "description": "The date and time the website was published", "nullable": true } }, "required": [ "title", "author", "publishedAt" ], "title": "WebsetItemCustomPropertiesFields" } }, "required": [ "type", "url", "description", "content", "custom" ] }, "WebsetItemEvaluation": { "type": [ "object" ], "properties": { "criterion": { "type": [ "string" ], "description": "The description of the criterion" }, "reasoning": { "type": [ "string" ], "description": "The reasoning for the result of the evaluation" }, "satisfied": { "type": [ "string" ], "enum": [ "yes", "no", "unclear" ], "description": "The satisfaction of the criterion" }, "references": { "default": [], "type": [ "array" ], "items": { "type": [ "object" ], "properties": { "title": { "type": "string", "description": "The title of the reference", "nullable": true }, "snippet": { "type": "string", "description": "The relevant snippet of the reference content", "nullable": true }, "url": { "type": [ "string" ], "format": "uri", "description": "The URL of the reference" } }, "required": [ "title", "snippet", "url" ] }, "description": "The references used to generate the result." } }, "required": [ "criterion", "reasoning", "satisfied" ] }, "EnrichmentResult": { "type": [ "object" ], "properties": { "object": { "type": "string", "const": "enrichment_result", "default": "enrichment_result" }, "status": { "type": [ "string" ], "enum": [ "pending", "completed", "canceled" ], "description": "The status of the enrichment result." }, "format": { "type": [ "string" ], "$ref": "#/components/schemas/WebsetEnrichmentFormat" }, "result": { "type": "array", "items": { "type": [ "string" ] }, "description": "The result of the enrichment.", "nullable": true }, "reasoning": { "type": "string", "description": "The reasoning for the result when an Agent is used.", "nullable": true }, "references": { "type": [ "array" ], "items": { "type": [ "object" ], "properties": { "title": { "type": "string", "description": "The title of the reference", "nullable": true }, "snippet": { "type": "string", "description": "The relevant snippet of the reference content", "nullable": true }, "url": { "type": [ "string" ], "format": "uri", "description": "The URL of the reference" } }, "required": [ "title", "snippet", "url" ] }, "description": "The references used to generate the result." }, "enrichmentId": { "type": [ "string" ], "description": "The id of the Enrichment that generated the result" } }, "required": [ "object", "status", "format", "result", "reasoning", "references", "enrichmentId" ] }, "WebsetItem": { "type": [ "object" ], "properties": { "id": { "type": [ "string" ], "description": "The unique identifier for the Webset Item" }, "object": { "type": "string", "const": "webset_item", "default": "webset_item" }, "source": { "type": [ "string" ], "enum": [ "search", "import" ], "description": "The source of the Item" }, "sourceId": { "type": [ "string" ], "description": "The unique identifier for the source" }, "sourceEntityId": { "type": [ "string" ], "description": "The original identifier used to resolve this item (e.g., email, name, or URL). Only relevant when the source is import." }, "scopeId": { "type": [ "string" ], "description": "The import that sourced this item, when the item came from a scoped search with evaluate enabled on the import." }, "websetId": { "type": [ "string" ], "description": "The unique identifier for the Webset this Item belongs to." }, "properties": { "oneOf": [ { "type": [ "object" ], "$ref": "#/components/schemas/WebsetItemPersonProperties", "title": "Person" }, { "type": [ "object" ], "$ref": "#/components/schemas/WebsetItemCompanyProperties", "title": "Company" }, { "type": [ "object" ], "$ref": "#/components/schemas/WebsetItemArticleProperties", "title": "Article" }, { "type": [ "object" ], "$ref": "#/components/schemas/WebsetItemResearchPaperProperties", "title": "Research Paper" }, { "type": [ "object" ], "$ref": "#/components/schemas/WebsetItemCustomProperties", "title": "Custom" } ], "description": "The properties of the Item" }, "evaluations": { "type": [ "array" ], "items": { "type": [ "object" ], "$ref": "#/components/schemas/WebsetItemEvaluation" }, "description": "The criteria evaluations of the item" }, "enrichments": { "type": "array", "items": { "type": [ "object" ], "$ref": "#/components/schemas/EnrichmentResult" }, "description": "The enrichments results of the Webset item", "nullable": true }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the item was created" }, "updatedAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the item was last updated" } }, "required": [ "id", "object", "source", "sourceId", "websetId", "properties", "evaluations", "enrichments", "createdAt", "updatedAt" ] }, "GetWebsetResponse": { "allOf": [ { "type": [ "object" ], "$ref": "#/components/schemas/Webset" }, { "type": [ "object" ], "properties": { "items": { "type": [ "array" ], "items": { "type": [ "object" ], "$ref": "#/components/schemas/WebsetItem" }, "description": "When expand query parameter contains `items`, this will contain the items in the webset" } } } ] }, "UpdateWebsetRequest": { "type": [ "object" ], "properties": { "metadata": { "description": "Set of key-value pairs you want to associate with this object.", "type": "object", "additionalProperties": { "type": [ "string" ], "maxLength": 1000 }, "nullable": true }, "title": { "type": [ "string" ], "minLength": 1, "description": "Optional name that appears anywhere the Webset is displayed.", "examples": [ "Leading climate tech startups" ] } } }, "ListWebsetsResponse": { "type": [ "object" ], "properties": { "data": { "type": [ "array" ], "items": { "type": [ "object" ], "$ref": "#/components/schemas/Webset" }, "description": "The list of websets" }, "hasMore": { "type": [ "boolean" ], "description": "Whether there are more results to paginate through" }, "nextCursor": { "type": "string", "description": "The cursor to paginate through the next set of results", "nullable": true } }, "required": [ "data", "hasMore", "nextCursor" ] }, "PreviewWebsetParameters": { "type": [ "object" ], "properties": { "search": { "type": [ "object" ], "properties": { "query": { "type": [ "string" ], "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" ] }, "entity": { "$ref": "#/components/schemas/Entity", "description": "Entity used to inform the decomposition.\n\nIt is not required to provide it, we automatically detect the entity from all the information provided in the query. Only use this when you need more fine control." }, "count": { "default": 10, "type": [ "number" ], "minimum": 1, "maximum": 10, "description": "When query parameter search=true, the number of preview items to return." } }, "required": [ "query" ] } }, "required": [ "search" ] }, "WebsetItemPreview": { "type": [ "object" ], "properties": { "id": { "type": [ "string" ], "description": "The unique identifier for the preview item" }, "properties": { "oneOf": [ { "type": [ "object" ], "$ref": "#/components/schemas/WebsetItemPersonProperties", "title": "Person" }, { "type": [ "object" ], "$ref": "#/components/schemas/WebsetItemCompanyProperties", "title": "Company" }, { "type": [ "object" ], "$ref": "#/components/schemas/WebsetItemArticleProperties", "title": "Article" }, { "type": [ "object" ], "$ref": "#/components/schemas/WebsetItemResearchPaperProperties", "title": "Research Paper" }, { "type": [ "object" ], "$ref": "#/components/schemas/WebsetItemCustomProperties", "title": "Custom" } ], "description": "The properties of the preview item" }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the preview was created" } }, "required": [ "id", "properties", "createdAt" ] }, "PreviewWebsetResponse": { "type": [ "object" ], "properties": { "search": { "type": [ "object" ], "properties": { "entity": { "oneOf": [ { "type": [ "object" ], "$ref": "#/components/schemas/CompanyEntity" }, { "type": [ "object" ], "$ref": "#/components/schemas/PersonEntity" }, { "type": [ "object" ], "$ref": "#/components/schemas/ArticleEntity" }, { "type": [ "object" ], "$ref": "#/components/schemas/ResearchPaperEntity" }, { "type": [ "object" ], "$ref": "#/components/schemas/CustomEntity" } ], "description": "Detected entity from the query." }, "criteria": { "type": [ "array" ], "items": { "type": [ "object" ], "properties": { "description": { "type": [ "string" ] } }, "required": [ "description" ] }, "description": "Detected criteria from the query." } }, "required": [ "entity", "criteria" ] }, "enrichments": { "type": [ "array" ], "items": { "type": [ "object" ], "properties": { "description": { "type": [ "string" ], "description": "Description of the enrichment." }, "format": { "type": [ "string" ], "enum": [ "text", "date", "number", "options", "email", "phone", "url" ], "description": "Format of the enrichment." }, "options": { "type": [ "array" ], "items": { "type": [ "object" ], "properties": { "label": { "type": [ "string" ], "description": "Label of the option." } }, "required": [ "label" ] }, "description": "When format is options, the options detected from the query." } }, "required": [ "description", "format" ] }, "description": "Detected enrichments from the query." }, "items": { "type": [ "array" ], "items": { "type": [ "object" ], "$ref": "#/components/schemas/WebsetItemPreview" }, "description": "Preview items matching the search criteria." } }, "required": [ "search", "enrichments", "items" ] }, "ListWebsetItemResponse": { "type": [ "object" ], "properties": { "data": { "type": [ "array" ], "items": { "type": [ "object" ], "$ref": "#/components/schemas/WebsetItem" }, "description": "The list of webset items" }, "hasMore": { "type": [ "boolean" ], "description": "Whether there are more Items to paginate through" }, "nextCursor": { "type": "string", "description": "The cursor to paginate through the next set of Items", "nullable": true } }, "required": [ "data", "hasMore", "nextCursor" ] }, "UpdateEnrichmentParameters": { "type": [ "object" ], "properties": { "description": { "type": [ "string" ], "minLength": 1, "maxLength": 5000, "description": "Provide a description of the enrichment task you want to perform to each Webset Item." }, "format": { "type": [ "string" ], "enum": [ "text", "date", "number", "options", "email", "phone", "url" ], "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." }, "options": { "type": [ "array" ], "items": { "type": [ "object" ], "properties": { "label": { "type": [ "string" ], "description": "The label of the option" } }, "required": [ "label" ] }, "minItems": 1, "maxItems": 150, "description": "When the format is options, the different options for the enrichment agent to choose from." }, "metadata": { "description": "Set of key-value pairs you want to associate with this object.", "type": "object", "additionalProperties": { "type": [ "string" ], "maxLength": 1000 }, "nullable": true } } }, "CreateWebhookParameters": { "type": [ "object" ], "properties": { "events": { "type": [ "array" ], "items": { "type": [ "string" ], "$ref": "#/components/schemas/EventType" }, "minItems": 1, "maxItems": 19, "description": "The events to trigger the webhook" }, "url": { "type": [ "string" ], "format": "uri", "description": "The URL to send the webhook to" }, "metadata": { "description": "Set of key-value pairs you want to associate with this object.", "type": [ "object" ], "additionalProperties": { "type": [ "string" ], "maxLength": 1000 } } }, "required": [ "events", "url" ] }, "Webhook": { "type": [ "object" ], "properties": { "id": { "type": [ "string" ], "description": "The unique identifier for the webhook" }, "object": { "type": "string", "const": "webhook", "default": "webhook" }, "status": { "type": [ "string" ], "enum": [ "active", "inactive" ], "description": "The status of the webhook", "title": "WebhookStatus" }, "events": { "type": [ "array" ], "items": { "type": [ "string" ], "$ref": "#/components/schemas/EventType" }, "minItems": 1, "description": "The events to trigger the webhook" }, "url": { "type": [ "string" ], "format": "uri", "description": "The URL to send the webhook to" }, "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", "type": [ "object" ], "additionalProperties": { "type": [ "string" ], "maxLength": 1000 } }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the webhook was created" }, "updatedAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the webhook was last updated" } }, "required": [ "id", "object", "status", "events", "url", "secret", "createdAt", "updatedAt" ] }, "UpdateWebhookParameters": { "type": [ "object" ], "properties": { "events": { "type": [ "array" ], "items": { "type": [ "string" ], "$ref": "#/components/schemas/EventType" }, "minItems": 1, "maxItems": 19, "description": "The events to trigger the webhook" }, "url": { "type": [ "string" ], "format": "uri", "description": "The URL to send the webhook to" }, "metadata": { "description": "Set of key-value pairs you want to associate with this object.", "type": [ "object" ], "additionalProperties": { "type": [ "string" ], "maxLength": 1000 } } } }, "ListWebhooksResponse": { "type": [ "object" ], "properties": { "data": { "type": [ "array" ], "items": { "type": [ "object" ], "$ref": "#/components/schemas/Webhook" }, "description": "The list of webhooks" }, "hasMore": { "type": [ "boolean" ], "description": "Whether there are more results to paginate through" }, "nextCursor": { "type": "string", "description": "The cursor to paginate through the next set of results", "nullable": true } }, "required": [ "data", "hasMore", "nextCursor" ] }, "WebhookAttempt": { "type": [ "object" ], "properties": { "id": { "type": [ "string" ], "description": "The unique identifier for the webhook attempt" }, "object": { "type": "string", "const": "webhook_attempt", "default": "webhook_attempt" }, "eventId": { "type": [ "string" ], "description": "The unique identifier for the event" }, "eventType": { "type": [ "string" ], "enum": [ "webset.created", "webset.deleted", "webset.paused", "webset.idle", "webset.search.created", "webset.search.canceled", "webset.search.completed", "webset.search.updated", "import.created", "import.completed", "webset.item.created", "webset.item.enriched", "monitor.created", "monitor.updated", "monitor.deleted", "monitor.run.created", "monitor.run.completed", "webset.export.created", "webset.export.completed" ], "description": "The type of event" }, "webhookId": { "type": [ "string" ], "description": "The unique identifier for the webhook" }, "url": { "type": [ "string" ], "description": "The URL that was used during the attempt" }, "successful": { "description": "Whether the attempt was successful", "type": [ "boolean" ] }, "responseHeaders": { "type": [ "object" ], "additionalProperties": { "type": [ "string" ] }, "description": "The headers of the response" }, "responseBody": { "type": "string", "description": "The body of the response", "nullable": true }, "responseStatusCode": { "type": [ "number" ], "description": "The status code of the response" }, "attempt": { "type": [ "number" ], "description": "The attempt number of the webhook" }, "attemptedAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the webhook attempt was made" } }, "required": [ "id", "object", "eventId", "eventType", "webhookId", "url", "successful", "responseHeaders", "responseBody", "responseStatusCode", "attempt", "attemptedAt" ] }, "ListWebhookAttemptsResponse": { "type": [ "object" ], "properties": { "data": { "type": [ "array" ], "items": { "type": [ "object" ], "$ref": "#/components/schemas/WebhookAttempt" }, "description": "The list of webhook attempts" }, "hasMore": { "type": [ "boolean" ], "description": "Whether there are more results to paginate through" }, "nextCursor": { "type": "string", "description": "The cursor to paginate through the next set of results", "nullable": true } }, "required": [ "data", "hasMore", "nextCursor" ] }, "Event": { "discriminator": { "propertyName": "type" }, "oneOf": [ { "type": [ "object" ], "properties": { "id": { "description": "The unique identifier for the event", "type": [ "string" ] }, "object": { "type": "string", "const": "event", "default": "event" }, "type": { "type": "string", "const": "webset.created", "default": "webset.created" }, "data": { "type": [ "object" ], "$ref": "#/components/schemas/Webset" }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the event was created" } }, "required": [ "id", "object", "type", "data", "createdAt" ], "title": "WebsetCreatedEvent" }, { "type": [ "object" ], "properties": { "id": { "description": "The unique identifier for the event", "type": [ "string" ] }, "object": { "type": "string", "const": "event", "default": "event" }, "type": { "type": "string", "const": "webset.deleted", "default": "webset.deleted" }, "data": { "type": [ "object" ], "$ref": "#/components/schemas/Webset" }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the event was created" } }, "required": [ "id", "object", "type", "data", "createdAt" ], "title": "WebsetDeletedEvent" }, { "type": [ "object" ], "properties": { "id": { "description": "The unique identifier for the event", "type": [ "string" ] }, "object": { "type": "string", "const": "event", "default": "event" }, "type": { "type": "string", "const": "webset.idle", "default": "webset.idle" }, "data": { "type": [ "object" ], "$ref": "#/components/schemas/Webset" }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the event was created" } }, "required": [ "id", "object", "type", "data", "createdAt" ], "title": "WebsetIdleEvent" }, { "type": [ "object" ], "properties": { "id": { "description": "The unique identifier for the event", "type": [ "string" ] }, "object": { "type": "string", "const": "event", "default": "event" }, "type": { "type": "string", "const": "webset.paused", "default": "webset.paused" }, "data": { "type": [ "object" ], "$ref": "#/components/schemas/Webset" }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the event was created" } }, "required": [ "id", "object", "type", "data", "createdAt" ], "title": "WebsetPausedEvent" }, { "type": [ "object" ], "properties": { "id": { "description": "The unique identifier for the event", "type": [ "string" ] }, "object": { "type": "string", "const": "event", "default": "event" }, "type": { "type": "string", "const": "webset.item.created", "default": "webset.item.created" }, "data": { "type": [ "object" ], "$ref": "#/components/schemas/WebsetItem" }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the event was created" } }, "required": [ "id", "object", "type", "data", "createdAt" ], "title": "WebsetItemCreatedEvent" }, { "type": [ "object" ], "properties": { "id": { "description": "The unique identifier for the event", "type": [ "string" ] }, "object": { "type": "string", "const": "event", "default": "event" }, "type": { "type": "string", "const": "webset.item.enriched", "default": "webset.item.enriched" }, "data": { "type": [ "object" ], "$ref": "#/components/schemas/WebsetItem" }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the event was created" } }, "required": [ "id", "object", "type", "data", "createdAt" ], "title": "WebsetItemEnrichedEvent" }, { "type": [ "object" ], "properties": { "id": { "description": "The unique identifier for the event", "type": [ "string" ] }, "object": { "type": "string", "const": "event", "default": "event" }, "type": { "type": "string", "const": "webset.search.created", "default": "webset.search.created" }, "data": { "type": [ "object" ], "$ref": "#/components/schemas/WebsetSearch" }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the event was created" } }, "required": [ "id", "object", "type", "data", "createdAt" ], "title": "WebsetSearchCreatedEvent" }, { "type": [ "object" ], "properties": { "id": { "description": "The unique identifier for the event", "type": [ "string" ] }, "object": { "type": "string", "const": "event", "default": "event" }, "type": { "type": "string", "const": "webset.search.updated", "default": "webset.search.updated" }, "data": { "type": [ "object" ], "$ref": "#/components/schemas/WebsetSearch" }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the event was created" } }, "required": [ "id", "object", "type", "data", "createdAt" ], "title": "WebsetSearchUpdatedEvent" }, { "type": [ "object" ], "properties": { "id": { "description": "The unique identifier for the event", "type": [ "string" ] }, "object": { "type": "string", "const": "event", "default": "event" }, "type": { "type": "string", "const": "webset.search.canceled", "default": "webset.search.canceled" }, "data": { "type": [ "object" ], "$ref": "#/components/schemas/WebsetSearch" }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the event was created" } }, "required": [ "id", "object", "type", "data", "createdAt" ], "title": "WebsetSearchCanceledEvent" }, { "type": [ "object" ], "properties": { "id": { "description": "The unique identifier for the event", "type": [ "string" ] }, "object": { "type": "string", "const": "event", "default": "event" }, "type": { "type": "string", "const": "webset.search.completed", "default": "webset.search.completed" }, "data": { "type": [ "object" ], "$ref": "#/components/schemas/WebsetSearch" }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the event was created" } }, "required": [ "id", "object", "type", "data", "createdAt" ], "title": "WebsetSearchCompletedEvent" }, { "type": [ "object" ], "properties": { "id": { "description": "The unique identifier for the event", "type": [ "string" ] }, "object": { "type": "string", "const": "event", "default": "event" }, "type": { "type": "string", "const": "import.created", "default": "import.created" }, "data": { "type": [ "object" ], "$ref": "#/components/schemas/Import" }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the event was created" } }, "required": [ "id", "object", "type", "data", "createdAt" ], "title": "ImportCreatedEvent" }, { "type": [ "object" ], "properties": { "id": { "description": "The unique identifier for the event", "type": [ "string" ] }, "object": { "type": "string", "const": "event", "default": "event" }, "type": { "type": "string", "const": "import.completed", "default": "import.completed" }, "data": { "type": [ "object" ], "$ref": "#/components/schemas/Import" }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the event was created" } }, "required": [ "id", "object", "type", "data", "createdAt" ], "title": "ImportCompletedEvent" }, { "type": [ "object" ], "properties": { "id": { "description": "The unique identifier for the event", "type": [ "string" ] }, "object": { "type": "string", "const": "event", "default": "event" }, "type": { "type": "string", "const": "monitor.created", "default": "monitor.created" }, "data": { "type": [ "object" ], "$ref": "#/components/schemas/Monitor" }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the event was created" } }, "required": [ "id", "object", "type", "data", "createdAt" ], "title": "MonitorCreatedEvent" }, { "type": [ "object" ], "properties": { "id": { "description": "The unique identifier for the event", "type": [ "string" ] }, "object": { "type": "string", "const": "event", "default": "event" }, "type": { "type": "string", "const": "monitor.updated", "default": "monitor.updated" }, "data": { "type": [ "object" ], "$ref": "#/components/schemas/Monitor" }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the event was created" } }, "required": [ "id", "object", "type", "data", "createdAt" ], "title": "MonitorUpdatedEvent" }, { "type": [ "object" ], "properties": { "id": { "description": "The unique identifier for the event", "type": [ "string" ] }, "object": { "type": "string", "const": "event", "default": "event" }, "type": { "type": "string", "const": "monitor.deleted", "default": "monitor.deleted" }, "data": { "type": [ "object" ], "$ref": "#/components/schemas/Monitor" }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the event was created" } }, "required": [ "id", "object", "type", "data", "createdAt" ], "title": "MonitorDeletedEvent" }, { "type": [ "object" ], "properties": { "id": { "description": "The unique identifier for the event", "type": [ "string" ] }, "object": { "type": "string", "const": "event", "default": "event" }, "type": { "type": "string", "const": "monitor.run.created", "default": "monitor.run.created" }, "data": { "type": [ "object" ], "$ref": "#/components/schemas/MonitorRun" }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the event was created" } }, "required": [ "id", "object", "type", "data", "createdAt" ], "title": "MonitorRunCreatedEvent" }, { "type": [ "object" ], "properties": { "id": { "description": "The unique identifier for the event", "type": [ "string" ] }, "object": { "type": "string", "const": "event", "default": "event" }, "type": { "type": "string", "const": "monitor.run.completed", "default": "monitor.run.completed" }, "data": { "type": [ "object" ], "$ref": "#/components/schemas/MonitorRun" }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "The date and time the event was created" } }, "required": [ "id", "object", "type", "data", "createdAt" ], "title": "MonitorRunCompletedEvent" } ], "title": "Event" }, "ListEventsResponse": { "type": [ "object" ], "properties": { "data": { "type": [ "array" ], "items": { "discriminator": { "propertyName": "type" }, "$ref": "#/components/schemas/Event" }, "description": "The list of events" }, "hasMore": { "type": [ "boolean" ], "description": "Whether there are more results to paginate through" }, "nextCursor": { "type": "string", "description": "The cursor to paginate through the next set of results", "nullable": true } }, "required": [ "data", "hasMore", "nextCursor" ] }, "CreateWebsetSearchParameters": { "type": [ "object" ], "properties": { "count": { "type": [ "number" ], "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." }, "query": { "type": [ "string" ], "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" ] }, "entity": { "$ref": "#/components/schemas/Entity", "description": "Entity the search will return results for.\n\nIt is not required to provide it, we automatically detect the entity from all the information provided in the query. Only use this when you need more fine control." }, "criteria": { "type": [ "array" ], "items": { "type": [ "object" ], "$ref": "#/components/schemas/CreateCriterionParameters", "title": "CreateCriterionParameters" }, "minItems": 1, "maxItems": 5, "description": "Criteria every item is evaluated against.\n\nIt's not required to provide your own criteria, we automatically detect the criteria from all the information provided in the query. Only use this when you need more fine control." }, "maxPeoplePerCompany": { "type": [ "integer" ], "minimum": 1, "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." }, "exclude": { "type": [ "array" ], "items": { "type": [ "object" ], "properties": { "source": { "type": [ "string" ], "enum": [ "import", "webset" ] }, "id": { "description": "The ID of the source to exclude.", "type": [ "string" ], "minLength": 1 } }, "required": [ "source", "id" ] }, "description": "Sources (existing imports or websets) to exclude from search results. Any results found within these sources will be omitted to prevent finding them during search." }, "scope": { "type": [ "array" ], "items": { "type": [ "object" ], "properties": { "source": { "type": [ "string" ], "enum": [ "import", "webset" ] }, "id": { "type": [ "string" ], "minLength": 1, "description": "The ID of the source to search." }, "relationship": { "type": [ "object" ], "properties": { "definition": { "type": [ "string" ], "description": "What the relationship of the entities you hope to find is relative to the entities contained in the provided source." }, "limit": { "type": [ "number" ], "minimum": 1, "maximum": 10 } }, "required": [ "definition", "limit" ] } }, "required": [ "source", "id" ] }, "description": "Limit the search to specific sources (existing imports). Any results found within these sources matching the search criteria will be included in the Webset." }, "recall": { "type": [ "boolean" ], "description": "Whether to provide an estimate of how many total relevant results could exist for this search.\nResult of the analysis will be available in the `recall` field within the search request." }, "behavior": { "default": "override", "type": [ "string" ], "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.", "type": [ "object" ], "additionalProperties": { "type": [ "string" ], "maxLength": 1000 } } }, "required": [ "count", "query" ] }, "CreateMonitorParameters": { "type": [ "object" ], "properties": { "websetId": { "type": [ "string" ], "description": "The id of the Webset" }, "cadence": { "type": [ "object" ], "properties": { "cron": { "description": "Cron expression for monitor cadence (must be a valid Unix cron with 5 fields). The schedule must trigger at most once per day.", "type": [ "string" ] }, "timezone": { "description": "IANA timezone (e.g., \"America/New_York\")", "default": "Etc/UTC", "type": [ "string" ] } }, "required": [ "cron" ], "description": "How often the monitor will run" }, "behavior": { "type": [ "object" ], "properties": { "type": { "type": "string", "const": "search", "default": "search" }, "config": { "type": [ "object" ], "properties": { "query": { "type": [ "string" ], "minLength": 2, "maxLength": 10000, "description": "The query to search for. By default, the query from the last search is used." }, "criteria": { "type": [ "array" ], "items": { "type": [ "object" ], "properties": { "description": { "type": [ "string" ], "minLength": 2, "maxLength": 1000 } }, "required": [ "description" ] }, "maxItems": 5, "description": "The criteria to search for. By default, the criteria from the last search is used." }, "entity": { "$ref": "#/components/schemas/Entity", "title": "Entity", "description": "The entity to search for. By default, the entity from the last search/import is used." }, "count": { "type": [ "number" ], "exclusiveMinimum": 0, "description": "The maximum number of results to find" }, "behavior": { "default": "append", "type": [ "string" ], "enum": [ "override", "append" ], "description": "The behaviour of the Search when it is added to a Webset." } }, "required": [ "count" ], "description": "Specify the search parameters for the Monitor.\n\nBy default, the search parameters (query, entity and criteria) from the last search are used when no parameters are provided." } }, "required": [ "type", "config" ], "description": "Behavior to perform when monitor runs" }, "metadata": { "type": [ "object" ], "additionalProperties": { "type": [ "string" ] } } }, "required": [ "websetId", "cadence", "behavior" ] }, "ListMonitorsResponse": { "type": [ "object" ], "properties": { "data": { "type": [ "array" ], "items": { "type": [ "object" ], "$ref": "#/components/schemas/Monitor" }, "description": "The list of monitors" }, "hasMore": { "type": [ "boolean" ], "description": "Whether there are more results to paginate through" }, "nextCursor": { "type": "string", "description": "The cursor to paginate through the next set of results", "nullable": true } }, "required": [ "data", "hasMore", "nextCursor" ] }, "MonitorCadence": { "type": [ "object" ], "properties": { "cron": { "description": "Cron expression for monitor cadence (must be a valid Unix cron with 5 fields). The schedule must trigger at most once per day.", "type": [ "string" ] }, "timezone": { "description": "IANA timezone (e.g., \"America/New_York\")", "default": "Etc/UTC", "type": [ "string" ] } }, "required": [ "cron" ] }, "MonitorBehavior": { "type": [ "object" ], "properties": { "type": { "type": "string", "const": "search", "default": "search" }, "config": { "type": [ "object" ], "properties": { "query": { "type": [ "string" ], "minLength": 2, "maxLength": 10000, "description": "The query to search for. By default, the query from the last search is used." }, "criteria": { "type": [ "array" ], "items": { "type": [ "object" ], "properties": { "description": { "type": [ "string" ], "minLength": 2, "maxLength": 1000 } }, "required": [ "description" ] }, "maxItems": 5, "description": "The criteria to search for. By default, the criteria from the last search is used." }, "entity": { "$ref": "#/components/schemas/Entity", "title": "Entity", "description": "The entity to search for. By default, the entity from the last search/import is used." }, "count": { "type": [ "number" ], "exclusiveMinimum": 0, "description": "The maximum number of results to find" }, "behavior": { "default": "append", "type": [ "string" ], "enum": [ "override", "append" ], "description": "The behaviour of the Search when it is added to a Webset." } }, "required": [ "count" ], "description": "Specify the search parameters for the Monitor.\n\nBy default, the search parameters (query, entity and criteria) from the last search are used when no parameters are provided." } }, "required": [ "type", "config" ] }, "UpdateMonitor": { "type": [ "object" ], "properties": { "status": { "type": [ "string" ], "enum": [ "enabled", "disabled" ], "description": "The status of the monitor." }, "metadata": { "type": [ "object" ], "additionalProperties": { "type": [ "string" ] } }, "cadence": { "type": [ "object" ], "$ref": "#/components/schemas/MonitorCadence" }, "behavior": { "type": [ "object" ], "$ref": "#/components/schemas/MonitorBehavior" } } }, "ListMonitorRunsResponse": { "type": [ "object" ], "properties": { "data": { "type": [ "array" ], "items": { "type": [ "object" ], "$ref": "#/components/schemas/MonitorRun" }, "description": "The list of monitor runs" }, "hasMore": { "type": [ "boolean" ], "description": "Whether there are more results to paginate through" }, "nextCursor": { "type": "string", "description": "The cursor to paginate through the next set of results", "nullable": true } }, "required": [ "data", "hasMore", "nextCursor" ] }, "CreateImportParameters": { "discriminator": { "propertyName": "format" }, "oneOf": [ { "type": [ "object" ], "properties": { "size": { "type": [ "number" ], "maximum": 50000000, "description": "The size of the file in bytes. Maximum size is 50 MB." }, "count": { "type": [ "number" ], "description": "The number of records to import" }, "title": { "type": [ "string" ], "description": "The title of the import" }, "format": { "type": [ "string" ], "enum": [ "csv" ], "description": "When the import is in CSV format, we expect a column containing the key identifier for the entity - for now URL. If not provided, import will fail to be processed." }, "metadata": { "description": "Set of key-value pairs you want to associate with this object.", "type": [ "object" ], "additionalProperties": { "type": [ "string" ], "maxLength": 1000 } }, "entity": { "oneOf": [ { "type": [ "object" ], "$ref": "#/components/schemas/CompanyEntity" }, { "type": [ "object" ], "$ref": "#/components/schemas/PersonEntity" }, { "type": [ "object" ], "$ref": "#/components/schemas/ArticleEntity" }, { "type": [ "object" ], "$ref": "#/components/schemas/ResearchPaperEntity" }, { "type": [ "object" ], "$ref": "#/components/schemas/CustomEntity" } ], "description": "What type of entity the import contains (e.g. People, Companies, etc.), and thus should be attempted to be resolved as." }, "csv": { "type": [ "object" ], "properties": { "identifier": { "type": [ "integer" ], "minimum": 0, "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." } }, "description": "When format is `csv`, these are the specific import parameters." } }, "required": [ "size", "count", "format", "entity" ] } ] }, "CreateImportResponse": { "type": [ "object" ], "properties": { "id": { "type": [ "string" ], "description": "The unique identifier for the Import" }, "object": { "type": [ "string" ], "enum": [ "import" ], "description": "The type of object" }, "status": { "type": [ "string" ], "enum": [ "pending", "processing", "completed", "failed", "canceled" ], "description": "The status of the Import" }, "format": { "type": [ "string" ], "enum": [ "csv", "webset" ], "description": "The format of the import." }, "entity": { "$ref": "#/components/schemas/Entity", "description": "The type of entity the import contains.", "nullable": true }, "title": { "type": [ "string" ], "description": "The title of the import" }, "count": { "type": [ "number" ], "description": "The number of entities in the import" }, "metadata": { "description": "Set of key-value pairs you want to associate with this object.", "type": [ "object" ], "additionalProperties": { "type": [ "string" ], "maxLength": 1000 } }, "failedReason": { "type": "string", "enum": [ "invalid_format", "invalid_file_content", "missing_identifier" ], "description": "The reason the import failed", "nullable": true }, "failedAt": { "type": "string", "format": "date-time", "description": "When the import failed", "nullable": true }, "failedMessage": { "type": "string", "description": "A human readable message of the import failure", "nullable": true }, "createdAt": { "type": [ "string" ], "format": "date-time", "description": "When the import was created" }, "updatedAt": { "type": [ "string" ], "format": "date-time", "description": "When the import was last updated" }, "uploadUrl": { "type": [ "string" ], "description": "The URL to upload the file to" }, "uploadValidUntil": { "type": [ "string" ], "description": "The date and time until the upload URL is valid. The upload URL will be valid for 1 hour." } }, "required": [ "id", "object", "status", "format", "entity", "title", "count", "metadata", "failedReason", "failedAt", "failedMessage", "createdAt", "updatedAt", "uploadUrl", "uploadValidUntil" ], "description": "The response to a successful import. Includes the upload URL and the upload valid until date." }, "ListImportsResponse": { "type": [ "object" ], "properties": { "data": { "type": [ "array" ], "items": { "type": [ "object" ], "$ref": "#/components/schemas/Import" }, "description": "The list of imports" }, "hasMore": { "type": [ "boolean" ], "description": "Whether there are more results to paginate through" }, "nextCursor": { "type": "string", "description": "The cursor to paginate through the next set of results", "nullable": true } }, "required": [ "data", "hasMore", "nextCursor" ] }, "UpdateImport": { "type": [ "object" ], "properties": { "metadata": { "type": [ "object" ], "additionalProperties": { "type": [ "string" ] } }, "title": { "type": [ "string" ] } } }, "WebsetEnrichmentFormat": { "type": "string", "enum": [ "text", "date", "number", "options", "email", "phone", "url" ] }, "EventType": { "type": "string", "enum": [ "webset.created", "webset.deleted", "webset.paused", "webset.idle", "webset.search.created", "webset.search.canceled", "webset.search.completed", "webset.search.updated", "import.created", "import.completed", "webset.item.created", "webset.item.enriched", "monitor.created", "monitor.updated", "monitor.deleted", "monitor.run.created", "monitor.run.completed", "webset.export.created", "webset.export.completed" ] }, "WebsetSearchBehavior": { "type": "string", "enum": [ "override", "append" ] }, "WebsetSearchCanceledReason": { "type": "string", "enum": [ "webset_deleted", "webset_canceled", "out_of_credits" ] } }, "headers": { "XRequestId": { "description": "Unique identifier for the request. Matches the `requestId` field returned in response bodies that carry one.", "schema": { "type": "string" }, "example": "07e29bb1f4f1dd05f0d4b57bbcf6e4b8" }, "XExaQueued": { "description": "Whether the request waited in the customer rate-limit queue before being admitted.", "schema": { "type": "string", "enum": [ "true", "false" ] }, "example": "false" }, "XExaQueueMs": { "description": "Total milliseconds the request waited in the customer rate-limit queue.", "schema": { "type": "string" }, "example": "0" } }, "responses": { "BadRequestResponse": { "description": "The request body or query parameters failed validation.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "example": { "requestId": "0a1b2c3d4e5f60718293a4b5c6d7e8f9", "error": "Invalid request body: query: Invalid input: expected string, received undefined", "tag": "INVALID_REQUEST_BODY" }, "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": { "example": { "requestId": "f2a4c6e8b0d2f4a6c8e0b2d4f6a8c0e2", "error": "Invalid API key", "tag": "INVALID_API_KEY" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "TooManyRequestsResponse": { "description": "A rate limit was exceeded.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "example": { "requestId": "7f9b1d3e5a0c2e4b6d8f0a2c4e6b8d0f", "error": "You've exceeded the Exa rate limit for your network. If you believe this is in error, please email hello@exa.ai :)", "tag": "RATE_LIMIT_EXCEEDED" }, "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": { "example": { "requestId": "9b1d3f5e7a0c2e4b6d8f0a2c4e6b8d0f", "error": "Sorry, we encountered an error while processing your request. Please try again later", "tag": "DEFAULT_ERROR" }, "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": { "example": { "requestId": "1c3e5a7b9d0f2a4c6e8b0d2f4a6c8e0b", "error": "You have exceeded your credits limit. Please top up to keep using Exa at dashboard.exa.ai", "tag": "NO_MORE_CREDITS" }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFoundResponse": { "description": "The requested resource does not exist.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "example": { "requestId": "3b1d5f7a9c0e2b4d6f8a0c2e4b6d8f0a", "error": "Not found", "tag": "NOT_FOUND" }, "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": { "example": { "requestId": "5d7f9b1c3e0a2c4e6b8d0f2a4c6e8b0d", "error": "Batch is not in a cancellable state", "tag": "INVALID_REQUEST" }, "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 ." } } }, "tags": [] }