exa-js/dist/index.d.ts

Exa SDK for Node.js and the browser

import { ZodSchema } from 'zod';

/**
 * Types for the Exa Agent API.
 */

/**
 * @deprecated Agent API beta header is no longer required for `exa.agent`.
 * Retained for legacy `exa.beta.agent` compatibility.
 */
declare const AGENT_BETA_HEADER = "agent-2026-05-07";
interface AgentBetaOptions {
    /**
     * @deprecated Agent API beta header is no longer required for `exa.agent`.
     * Values supplied to `exa.beta.agent` are sent as the `Exa-Beta` header.
     */
    betas?: string[];
}
type AgentRunStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
type AgentStopReason = "schema_satisfied" | "budget_reached" | "error" | "cancelled";
type AgentConfidence = "low" | "medium" | "high";
type AgentEffort = "low" | "medium" | "high" | "xhigh" | "auto";
/**
 * Identifier of an Exa Connect data provider, e.g. `"fiber_ai"`,
 * `"financial_datasets"`, `"similarweb"`, `"baselayer"`, `"affiliate"`,
 * `"particle_news"`, or `"jinko"`.
 */
type AgentDataSourceProvider = string;
/** Exa Connect data source to enable for an Agent run. */
interface AgentDataSource {
    /** Exa Connect data provider to enable for the run. */
    provider: AgentDataSourceProvider;
}
interface AgentInput {
    data?: Record<string, unknown>[];
    exclusion?: Record<string, unknown>[];
    [key: string]: unknown;
}
interface AgentGroundingCitation {
    url: string;
    title?: string | null;
    [key: string]: unknown;
}
interface AgentGroundingEntry {
    field: string;
    citations: AgentGroundingCitation[];
    score?: number | null;
    confidence?: AgentConfidence | null;
    [key: string]: unknown;
}
interface AgentOutput {
    text?: string | null;
    structured?: unknown;
    grounding?: AgentGroundingEntry[] | null;
    [key: string]: unknown;
}
interface AgentUsage {
    agentComputeUnits?: number;
    searches?: number;
    emails?: number;
    phoneNumbers?: number;
    /** Per-provider tool call counts for Exa Connect data sources used during the run. */
    dataSources?: Record<string, number>;
    [key: string]: unknown;
}
interface AgentCostDollars {
    total?: number;
    agentCompute?: number;
    search?: number;
    emails?: number;
    phoneNumbers?: number;
    /** Per-provider cost in dollars for Exa Connect data sources used during the run. */
    dataSources?: Record<string, number>;
    [key: string]: unknown;
}
interface AgentError {
    type?: string;
    code?: string;
    message?: string;
    path?: string;
    keyword?: string;
    expected?: unknown;
    actual?: unknown;
    [key: string]: unknown;
}
interface AgentRun {
    id: string;
    object?: string;
    status: AgentRunStatus;
    stopReason?: AgentStopReason | null;
    createdAt?: string;
    completedAt?: string | null;
    request?: Record<string, unknown>;
    output?: AgentOutput | null;
    usage?: AgentUsage;
    costDollars?: AgentCostDollars;
    error?: AgentError;
    [key: string]: unknown;
}
type AgentRunTyped<T> = AgentRun & {
    output?: (AgentOutput & {
        structured?: T;
    }) | null;
};
interface ListAgentRunsParams {
    cursor?: string;
    limit?: number;
}
interface ListAgentRunsResponse {
    object?: string;
    data: AgentRun[];
    hasMore: boolean;
    nextCursor: string | null;
}
interface DeletedAgentRun {
    id: string;
    object?: string;
    deleted: boolean;
}
interface AgentEvent {
    id?: string;
    event: string;
    data: Record<string, unknown>;
    createdAt?: string;
    [key: string]: unknown;
}
interface ListAgentRunEventsParams {
    cursor?: string;
    limit?: number;
}
interface ListAgentRunEventsResponse {
    object?: string;
    data: AgentEvent[];
    hasMore: boolean;
    nextCursor: string | null;
}
interface CreateAgentRunParams {
    query: string;
    systemPrompt?: string;
    input?: AgentInput;
    outputSchema?: Record<string, unknown>;
    effort?: AgentEffort;
    previousRunId?: string;
    metadata?: Record<string, unknown>;
    /** Exa Connect data providers to enable for the run. Each entry enables all of that provider's tools. */
    dataSources?: AgentDataSource[];
}
type CreateAgentRunParamsTyped<T> = Omit<CreateAgentRunParams, "outputSchema"> & {
    outputSchema?: T;
};
type AgentCreateOptions<T = Record<string, unknown>> = CreateAgentRunParamsTyped<Record<string, unknown> | ZodSchema<T>> & {
    stream?: boolean;
};

/**
 * Base client for the Exa Agent API.
 */

type QueryParams$3 = Record<string, string | number | boolean | string[] | undefined>;
type RequestBody$2 = Record<string, unknown>;
declare class AgentBaseClient {
    protected client: Exa;
    constructor(client: Exa);
    protected request<T = unknown>(endpoint: string, method?: string, data?: RequestBody$2, params?: QueryParams$3, headers?: Record<string, string>): Promise<T>;
    protected rawRequest(endpoint: string, method?: string, data?: RequestBody$2, params?: QueryParams$3, headers?: Record<string, string>): Promise<Response>;
    protected buildPaginationParams(pagination?: ListAgentRunsParams | ListAgentRunEventsParams): QueryParams$3;
}

/**
 * Client for the Exa Agent API.
 */

type WithBetaOptions<T> = T & AgentBetaOptions;
type AgentTerminalStatus = "completed" | "failed" | "cancelled";
type AgentTerminalRun = AgentRun & {
    status: AgentTerminalStatus;
};
type AgentCompletedRun = AgentRun & {
    status: "completed";
};
type AgentCompletedRunTyped<T> = AgentRunTyped<T> & {
    status: "completed";
};
type AgentWaitOptions = {
    pollInterval?: number;
    timeoutMs?: number;
};
declare class AgentRunFailedError extends Error {
    run: AgentRun & {
        status: "failed";
    };
    constructor(run: AgentRun & {
        status: "failed";
    });
}
declare class AgentRunCancelledError extends Error {
    run: AgentRun & {
        status: "cancelled";
    };
    constructor(run: AgentRun & {
        status: "cancelled";
    });
}
declare class AgentRunEventsClient extends AgentBaseClient {
    /**
     * List stored events for an Agent run.
     */
    list(runId: string, options?: ListAgentRunEventsParams): Promise<ListAgentRunEventsResponse>;
}
declare class AgentRunsClient extends AgentBaseClient {
    /**
     * Client for Agent run events.
     */
    events: AgentRunEventsClient;
    constructor(client: Exa);
    /**
     * Create an Agent run.
     */
    create<T>(params: AgentCreateOptions<T> & {
        stream: true;
    }): Promise<AsyncGenerator<AgentEvent>>;
    create<T>(params: AgentCreateOptions<T> & {
        stream?: false;
    }): Promise<AgentRunTyped<T>>;
    create(params: CreateAgentRunParams): Promise<AgentRun>;
    /**
     * Get an Agent run by ID.
     */
    get(runId: string): Promise<AgentRun>;
    /**
     * List Agent runs.
     */
    list(options?: ListAgentRunsParams): Promise<ListAgentRunsResponse>;
    /**
     * Iterate through all Agent runs, handling pagination automatically.
     */
    listAll(options?: ListAgentRunsParams): AsyncGenerator<AgentRun>;
    /**
     * Collect all Agent runs into an array.
     */
    getAll(options?: ListAgentRunsParams): Promise<AgentRun[]>;
    /**
     * Cancel a queued or running Agent run.
     */
    cancel(runId: string): Promise<AgentRun>;
    /**
     * Delete a stored Agent run.
     */
    delete(runId: string): Promise<DeletedAgentRun>;
    /**
     * Poll an Agent run until it reaches a terminal status.
     */
    pollUntilFinished(runId: string, options?: AgentWaitOptions): Promise<AgentTerminalRun>;
    /**
     * Create an Agent run and wait until it reaches a terminal status.
     */
    createAndWait<T>(params: Omit<AgentCreateOptions<T>, "stream">, options?: AgentWaitOptions): Promise<AgentCompletedRunTyped<T>>;
    createAndWait(params: CreateAgentRunParams, options?: AgentWaitOptions): Promise<AgentCompletedRun>;
}
declare class AgentClient {
    /**
     * @internal
     */
    readonly client: Exa;
    /**
     * Client for Agent runs.
     */
    runs: AgentRunsClient;
    constructor(client: Exa);
}
declare class AgentBetaRunEventsClient extends AgentRunEventsClient {
    /**
     * List stored events for an Agent run.
     *
     * @deprecated Use exa.agent.runs.events instead.
     */
    list(runId: string, options?: WithBetaOptions<ListAgentRunEventsParams>): Promise<ListAgentRunEventsResponse>;
}
declare class AgentBetaRunsClient extends AgentRunsClient {
    /**
     * @deprecated Use exa.agent.runs.events instead.
     */
    events: AgentBetaRunEventsClient;
    constructor(client: Exa);
    create<T>(params: WithBetaOptions<AgentCreateOptions<T>> & {
        stream: true;
    }): Promise<AsyncGenerator<AgentEvent>>;
    create<T>(params: WithBetaOptions<AgentCreateOptions<T>> & {
        stream?: false;
    }): Promise<AgentRunTyped<T>>;
    create(params: CreateAgentRunParams & AgentBetaOptions): Promise<AgentRun>;
    get(runId: string, options?: AgentBetaOptions): Promise<AgentRun>;
    list(options?: WithBetaOptions<ListAgentRunsParams>): Promise<ListAgentRunsResponse>;
    listAll(options?: WithBetaOptions<ListAgentRunsParams>): AsyncGenerator<AgentRun>;
    getAll(options?: WithBetaOptions<ListAgentRunsParams>): Promise<AgentRun[]>;
    cancel(runId: string, options?: AgentBetaOptions): Promise<AgentRun>;
    delete(runId: string, options?: AgentBetaOptions): Promise<DeletedAgentRun>;
    pollUntilFinished(runId: string, options?: WithBetaOptions<AgentWaitOptions>): Promise<AgentTerminalRun>;
    createAndWait<T>(params: WithBetaOptions<Omit<AgentCreateOptions<T>, "stream">>, options?: AgentWaitOptions): Promise<AgentCompletedRunTyped<T>>;
    createAndWait(params: CreateAgentRunParams & AgentBetaOptions, options?: AgentWaitOptions): Promise<AgentCompletedRun>;
}
/**
 * @deprecated Use AgentClient instead.
 */
declare class AgentBetaClient extends AgentClient {
    /**
     * @deprecated Use exa.agent.runs instead.
     */
    runs: AgentBetaRunsClient;
    constructor(clientOrAgent: Exa | AgentClient);
}
declare class BetaClient {
    /**
     * @deprecated Use exa.agent instead.
     */
    agent: AgentBetaClient;
    constructor(clientOrAgent: Exa | AgentClient);
}

/**
 * Types for the Search Monitors API
 */

type SearchMonitorStatus = "active" | "paused" | "disabled";
type SearchMonitorRunStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
type SearchMonitorRunFailReason = "api_key_invalid" | "insufficient_credits" | "invalid_params" | "rate_limited" | "search_unavailable" | "search_failed" | "internal_error";
type SearchMonitorWebhookEvent = "monitor.created" | "monitor.updated" | "monitor.deleted" | "monitor.run.created" | "monitor.run.completed";
interface SearchMonitorSearch {
    query: string;
    numResults?: number;
    includeDomains?: string[];
    excludeDomains?: string[];
    contents?: ContentsOptions;
}
interface SearchMonitorTrigger {
    type: "interval";
    period: string;
}
interface SearchMonitorWebhook {
    url: string;
    events?: SearchMonitorWebhookEvent[];
}
interface GroundingCitation {
    url: string;
    title: string;
}
interface GroundingEntry {
    field: string;
    citations: GroundingCitation[];
    confidence: "low" | "medium" | "high";
}
interface SearchMonitorRunOutput {
    results?: Record<string, unknown>[] | null;
    /**
     * Synthesized output. When the monitor is configured with an `outputSchema`,
     * the API returns this as a structured object; otherwise it is a string.
     */
    content?: string | Record<string, unknown> | null;
    grounding?: GroundingEntry[] | null;
}
interface SearchMonitor {
    id: string;
    name: string | null;
    status: SearchMonitorStatus;
    search: SearchMonitorSearch;
    trigger: SearchMonitorTrigger | null;
    outputSchema: Record<string, unknown> | null;
    metadata: Record<string, string> | null;
    webhook: SearchMonitorWebhook;
    nextRunAt: string | null;
    createdAt: string;
    updatedAt: string;
}
interface CreateSearchMonitorResponse extends SearchMonitor {
    webhookSecret: string;
}
interface SearchMonitorRun {
    id: string;
    monitorId: string;
    status: SearchMonitorRunStatus;
    output: SearchMonitorRunOutput | null;
    failReason: SearchMonitorRunFailReason | null;
    startedAt: string | null;
    completedAt: string | null;
    failedAt: string | null;
    cancelledAt: string | null;
    durationMs: number | null;
    createdAt: string;
    updatedAt: string;
}
interface CreateSearchMonitorParams {
    name?: string;
    search: SearchMonitorSearch;
    trigger?: SearchMonitorTrigger;
    outputSchema?: Record<string, unknown>;
    metadata?: Record<string, string>;
    webhook: SearchMonitorWebhook;
}
interface UpdateSearchMonitorParams {
    name?: string | null;
    status?: SearchMonitorStatus;
    search?: SearchMonitorSearch;
    trigger?: SearchMonitorTrigger | null;
    outputSchema?: Record<string, unknown> | null;
    metadata?: Record<string, string> | null;
    webhook?: SearchMonitorWebhook;
}
interface ListSearchMonitorsParams {
    cursor?: string;
    limit?: number;
    status?: SearchMonitorStatus;
}
interface ListSearchMonitorRunsParams {
    cursor?: string;
    limit?: number;
}
interface ListSearchMonitorsResponse {
    data: SearchMonitor[];
    hasMore: boolean;
    nextCursor: string | null;
}
interface ListSearchMonitorRunsResponse {
    data: SearchMonitorRun[];
    hasMore: boolean;
    nextCursor: string | null;
}
interface TriggerSearchMonitorResponse {
    triggered: boolean;
}

/**
 * Base client for Search Monitors API
 */

type QueryParams$2 = Record<string, string | number | boolean | string[] | undefined>;
declare class SearchMonitorsBaseClient {
    protected client: Exa;
    constructor(client: Exa);
    protected request<T = unknown>(endpoint: string, method?: string, data?: Record<string, any>, params?: QueryParams$2): Promise<T>;
    protected buildPaginationParams(pagination?: ListSearchMonitorsParams | ListSearchMonitorRunsParams): QueryParams$2;
}

/**
 * Client for the Search Monitors API
 */

/**
 * Client for managing Search Monitor Runs
 */
declare class SearchMonitorRunsClient extends SearchMonitorsBaseClient {
    /**
     * List all runs for a Search Monitor
     * @param monitorId The ID of the Search Monitor
     * @param options Pagination options
     * @returns The list of Search Monitor runs
     */
    list(monitorId: string, options?: ListSearchMonitorRunsParams): Promise<ListSearchMonitorRunsResponse>;
    /**
     * Get a specific Search Monitor run
     * @param monitorId The ID of the Search Monitor
     * @param runId The ID of the run
     * @returns The Search Monitor run
     */
    get(monitorId: string, runId: string): Promise<SearchMonitorRun>;
    /**
     * Iterate through all runs for a Search Monitor, handling pagination automatically
     * @param monitorId The ID of the Search Monitor
     * @param options Pagination options
     * @returns Async generator of Search Monitor runs
     */
    listAll(monitorId: string, options?: ListSearchMonitorRunsParams): AsyncGenerator<SearchMonitorRun>;
    /**
     * Collect all runs for a Search Monitor into an array
     * @param monitorId The ID of the Search Monitor
     * @param options Pagination options
     * @returns Promise resolving to an array of all Search Monitor runs
     */
    getAll(monitorId: string, options?: ListSearchMonitorRunsParams): Promise<SearchMonitorRun[]>;
}
/**
 * Client for managing Search Monitors
 */
declare class SearchMonitorsClient extends SearchMonitorsBaseClient {
    /**
     * Client for managing Search Monitor Runs
     */
    runs: SearchMonitorRunsClient;
    constructor(client: Exa);
    /**
     * Create a Search Monitor
     * @param params The monitor creation parameters
     * @returns The created Search Monitor with webhookSecret
     */
    create(params: CreateSearchMonitorParams): Promise<CreateSearchMonitorResponse>;
    /**
     * Get a Search Monitor by ID
     * @param id The ID of the Search Monitor
     * @returns The Search Monitor
     */
    get(id: string): Promise<SearchMonitor>;
    /**
     * List Search Monitors
     * @param options Pagination and filtering options
     * @returns The list of Search Monitors
     */
    list(options?: ListSearchMonitorsParams): Promise<ListSearchMonitorsResponse>;
    /**
     * Update a Search Monitor
     * @param id The ID of the Search Monitor
     * @param params The update parameters
     * @returns The updated Search Monitor
     */
    update(id: string, params: UpdateSearchMonitorParams): Promise<SearchMonitor>;
    /**
     * Delete a Search Monitor
     * @param id The ID of the Search Monitor
     * @returns The deleted Search Monitor
     */
    delete(id: string): Promise<SearchMonitor>;
    /**
     * Trigger a Search Monitor run immediately
     * @param id The ID of the Search Monitor
     * @returns Whether the monitor was triggered
     */
    trigger(id: string): Promise<TriggerSearchMonitorResponse>;
    /**
     * Iterate through all Search Monitors, handling pagination automatically
     * @param options Pagination and filtering options
     * @returns Async generator of Search Monitors
     */
    listAll(options?: ListSearchMonitorsParams): AsyncGenerator<SearchMonitor>;
    /**
     * Collect all Search Monitors into an array
     * @param options Pagination and filtering options
     * @returns Promise resolving to an array of all Search Monitors
     */
    getAll(options?: ListSearchMonitorsParams): Promise<SearchMonitor[]>;
}

interface components$1 {
    schemas: {
        ListResearchResponseDto: {
            /** @description Research requests ordered by creation time (newest first) */
            data: components$1["schemas"]["ResearchDtoClass"][];
            /** @description If true, use nextCursor to fetch more results */
            hasMore: boolean;
            /** @description Pass this value as the cursor parameter to fetch the next page */
            nextCursor: string | null;
        };
        ResearchCreateRequestDtoClass: {
            /** @description Instructions for what you would like research on. A good prompt clearly defines what information you want to find, how research should be conducted, and what the output should look like. */
            instructions: string;
            /**
             * @description Research model to use. exa-research is faster and cheaper, while exa-research-pro provides more thorough analysis and stronger reasoning.
             * @default exa-research
             * @enum {string}
             */
            model: "exa-research-fast" | "exa-research" | "exa-research-pro";
            /** @description JSON Schema to enforce structured output. When provided, the research output will be validated against this schema and returned as parsed JSON. */
            outputSchema?: {
                [key: string]: unknown;
            };
        };
        ResearchDtoClass: {
            /** @description When the research was created (Unix timestamp in milliseconds) */
            createdAt: number;
            /** @description The original research instructions provided */
            instructions: string;
            /**
             * @description The model used for this research request
             * @default exa-research
             * @enum {string}
             */
            model: "exa-research-fast" | "exa-research" | "exa-research-pro";
            /** @description The JSON Schema used to validate the output, if provided */
            outputSchema?: {
                [key: string]: unknown;
            };
            /** @description Unique identifier for tracking and retrieving this research request */
            researchId: string;
            /** @enum {string} */
            status: "pending";
        } | {
            /** @description When the research was created (Unix timestamp in milliseconds) */
            createdAt: number;
            /** @description Real-time log of operations as research progresses. Poll this endpoint or use ?stream=true for live updates. */
            events?: components$1["schemas"]["ResearchEventDtoClass"][];
            /** @description The original research instructions provided */
            instructions: string;
            /**
             * @description The model used for this research request
             * @default exa-research
             * @enum {string}
             */
            model: "exa-research-fast" | "exa-research" | "exa-research-pro";
            /** @description The JSON Schema used to validate the output, if provided */
            outputSchema?: {
                [key: string]: unknown;
            };
            /** @description Unique identifier for tracking and retrieving this research request */
            researchId: string;
            /** @enum {string} */
            status: "running";
        } | {
            /** @description Detailed cost breakdown for billing purposes */
            costDollars: {
                /** @description Count of web pages fully crawled and processed. Only pages that were read in detail are counted. */
                numPages: number;
                /** @description Count of web searches performed. Each search query counts as one search. */
                numSearches: number;
                /** @description Total AI tokens used for reasoning, planning, and generating the final output */
                reasoningTokens: number;
                /** @description Total cost in USD for this research request */
                total: number;
            };
            /** @description When the research was created (Unix timestamp in milliseconds) */
            createdAt: number;
            /** @description Detailed log of all operations performed during research. Use ?events=true to include this field for debugging or monitoring progress. */
            events?: components$1["schemas"]["ResearchEventDtoClass"][];
            /** @description When the research completed (Unix timestamp in milliseconds) */
            finishedAt: number;
            /** @description The original research instructions provided */
            instructions: string;
            /**
             * @description The model used for this research request
             * @default exa-research
             * @enum {string}
             */
            model: "exa-research-fast" | "exa-research" | "exa-research-pro";
            /** @description The final research results, containing both raw text and parsed JSON if outputSchema was provided */
            output: {
                /** @description The complete research output as text. If outputSchema was provided, this is a JSON string. */
                content: string;
                /** @description Structured JSON object matching your outputSchema. Only present when outputSchema was provided and the output successfully validated. */
                parsed?: {
                    [key: string]: unknown;
                };
            };
            /** @description The JSON Schema used to validate the output, if provided */
            outputSchema?: {
                [key: string]: unknown;
            };
            /** @description Unique identifier for tracking and retrieving this research request */
            researchId: string;
            /** @enum {string} */
            status: "completed";
        } | {
            /** @description When the research was created (Unix timestamp in milliseconds) */
            createdAt: number;
            /** @description Detailed log of all operations performed during research. Use ?events=true to include this field for debugging or monitoring progress. */
            events?: components$1["schemas"]["ResearchEventDtoClass"][];
            /** @description When the research was canceled (Unix timestamp in milliseconds) */
            finishedAt: number;
            /** @description The original research instructions provided */
            instructions: string;
            /**
             * @description The model used for this research request
             * @default exa-research
             * @enum {string}
             */
            model: "exa-research-fast" | "exa-research" | "exa-research-pro";
            /** @description The JSON Schema used to validate the output, if provided */
            outputSchema?: {
                [key: string]: unknown;
            };
            /** @description Unique identifier for tracking and retrieving this research request */
            researchId: string;
            /** @enum {string} */
            status: "canceled";
        } | {
            /** @description When the research was created (Unix timestamp in milliseconds) */
            createdAt: number;
            /** @description Human-readable error message explaining what went wrong. */
            error: string;
            /** @description Detailed log of all operations performed during research. Use ?events=true to include this field for debugging or monitoring progress. */
            events?: components$1["schemas"]["ResearchEventDtoClass"][];
            /** @description When the research failed (Unix timestamp in milliseconds) */
            finishedAt: number;
            /** @description The original research instructions provided */
            instructions: string;
            /**
             * @description The model used for this research request
             * @default exa-research
             * @enum {string}
             */
            model: "exa-research-fast" | "exa-research" | "exa-research-pro";
            /** @description The JSON Schema used to validate the output, if provided */
            outputSchema?: {
                [key: string]: unknown;
            };
            /** @description Unique identifier for tracking and retrieving this research request */
            researchId: string;
            /** @enum {string} */
            status: "failed";
        };
        ResearchEventDtoClass: ({
            /** @description When this event occurred (Unix timestamp in milliseconds) */
            createdAt: number;
            /** @enum {string} */
            eventType: "research-definition";
            /** @description The complete research instructions as provided */
            instructions: string;
            /** @description The JSON Schema that will validate the final output */
            outputSchema?: {
                [key: string]: unknown;
            };
            /** @description The research request this event belongs to */
            researchId: string;
        } | {
            /** @description When this event occurred (Unix timestamp in milliseconds) */
            createdAt: number;
            /** @enum {string} */
            eventType: "research-output";
            /** @description The final research result, either successful with data or failed with error */
            output: {
                /** @description The complete research output as text. If outputSchema was provided, this is a JSON string. */
                content: string;
                costDollars: {
                    /** @description Count of web pages fully crawled and processed. Only pages that were read in detail are counted. */
                    numPages: number;
                    /** @description Count of web searches performed. Each search query counts as one search. */
                    numSearches: number;
                    /** @description Total AI tokens used for reasoning, planning, and generating the final output */
                    reasoningTokens: number;
                    /** @description Total cost in USD for this research request */
                    total: number;
                };
                /** @enum {string} */
                outputType: "completed";
                /** @description Structured JSON object matching your outputSchema. Only present when outputSchema was provided and the output successfully validated. */
                parsed?: {
                    [key: string]: unknown;
                };
            } | {
                /** @description Detailed error message explaining why the research failed */
                error: string;
                /** @enum {string} */
                outputType: "failed";
            };
            /** @description The research request this event belongs to */
            researchId: string;
        }) | ({
            /** @description When this event occurred (Unix timestamp in milliseconds) */
            createdAt: number;
            /** @enum {string} */
            eventType: "plan-definition";
            /** @description Identifier for this planning cycle */
            planId: string;
            /** @description The research request this event belongs to */
            researchId: string;
        } | {
            /** @description When this event occurred (Unix timestamp in milliseconds) */
            createdAt: number;
            /** @description The actual operation performed (think, search, or crawl) */
            data: {
                /** @description The AI's reasoning process and decision-making steps */
                content: string;
                /** @enum {string} */
                type: "think";
            } | {
                /** @description What the AI is trying to find with this search */
                goal?: string;
                /** @description Token cost for processing search result snippets */
                pageTokens: number;
                /** @description The exact search query sent to the search engine */
                query: string;
                /** @description URLs returned by the search, ranked by relevance */
                results: {
                    url: string;
                }[];
                /**
                 * @description Search algorithm used (neural for semantic search, keyword for exact matches)
                 * @enum {string}
                 */
                searchType: "neural" | "keyword" | "auto" | "fast";
                /** @enum {string} */
                type: "search";
            } | {
                /** @description What information the AI expects to find on this page */
                goal?: string;
                /** @description Token cost for processing the full page content */
                pageTokens: number;
                /** @description The specific page that was crawled */
                result: {
                    url: string;
                };
                /** @enum {string} */
                type: "crawl";
            };
            /** @enum {string} */
            eventType: "plan-operation";
            /** @description Unique identifier for this specific operation */
            operationId: string;
            /** @description Which plan this operation belongs to */
            planId: string;
            /** @description The research request this event belongs to */
            researchId: string;
        } | {
            /** @description When this event occurred (Unix timestamp in milliseconds) */
            createdAt: number;
            /** @enum {string} */
            eventType: "plan-output";
            /** @description The plan's decision: either generate tasks or stop researching */
            output: {
                /** @enum {string} */
                outputType: "tasks";
                /** @description Why these specific tasks were chosen */
                reasoning: string;
                /** @description List of task instructions that will be executed in parallel */
                tasksInstructions: string[];
            } | {
                /** @enum {string} */
                outputType: "stop";
                /** @description Why the AI decided to stop researching */
                reasoning: string;
            };
            /** @description Which plan is producing this output */
            planId: string;
            /** @description The research request this event belongs to */
            researchId: string;
        }) | ({
            /** @description When this event occurred (Unix timestamp in milliseconds) */
            createdAt: number;
            /** @enum {string} */
            eventType: "task-definition";
            /** @description What this task should accomplish */
            instructions: string;
            /** @description The plan that generated this task */
            planId: string;
            /** @description The research request this event belongs to */
            researchId: string;
            /** @description Identifier for tracking this specific task */
            taskId: string;
        } | {
            /** @description When this event occurred (Unix timestamp in milliseconds) */
            createdAt: number;
            /** @description The actual operation performed within this task */
            data: {
                /** @description The AI's reasoning process and decision-making steps */
                content: string;
                /** @enum {string} */
                type: "think";
            } | {
                /** @description What the AI is trying to find with this search */
                goal?: string;
                /** @description Token cost for processing search result snippets */
                pageTokens: number;
                /** @description The exact search query sent to the search engine */
                query: string;
                /** @description URLs returned by the search, ranked by relevance */
                results: {
                    url: string;
                }[];
                /**
                 * @description Search algorithm used (neural for semantic search, keyword for exact matches)
                 * @enum {string}
                 */
                searchType: "neural" | "keyword" | "auto" | "fast";
                /** @enum {string} */
                type: "search";
            } | {
                /** @description What information the AI expects to find on this page */
                goal?: string;
                /** @description Token cost for processing the full page content */
                pageTokens: number;
                /** @description The specific page that was crawled */
                result: {
                    url: string;
                };
                /** @enum {string} */
                type: "crawl";
            };
            /** @enum {string} */
            eventType: "task-operation";
            /** @description Unique identifier for this specific operation */
            operationId: string;
            /** @description The plan that owns this task */
            planId: string;
            /** @description The research request this event belongs to */
            researchId: string;
            /** @description Which task is performing this operation */
            taskId: string;
        } | {
            /** @description When this event occurred (Unix timestamp in milliseconds) */
            createdAt: number;
            /** @enum {string} */
            eventType: "task-output";
            /** @description The successful completion result of this task */
            output: {
                /** @description The information gathered by this task */
                content: string;
                /** @enum {string} */
                outputType: "completed";
            };
            /** @description The plan that owns this task */
            planId: string;
            /** @description The research request this event belongs to */
            researchId: string;
            /** @description Which task produced this output */
            taskId: string;
        });
        ResearchOperationDtoClass: {
            /** @description The AI's reasoning process and decision-making steps */
            content: string;
            /** @enum {string} */
            type: "think";
        } | {
            /** @description What the AI is trying to find with this search */
            goal?: string;
            /** @description Token cost for processing search result snippets */
            pageTokens: number;
            /** @description The exact search query sent to the search engine */
            query: string;
            /** @description URLs returned by the search, ranked by relevance */
            results: {
                url: string;
            }[];
            /**
             * @description Search algorithm used (neural for semantic search, keyword for exact matches)
             * @enum {string}
             */
            searchType: "neural" | "keyword" | "auto" | "fast";
            /** @enum {string} */
            type: "search";
        } | {
            /** @description What information the AI expects to find on this page */
            goal?: string;
            /** @description Token cost for processing the full page content */
            pageTokens: number;
            /** @description The specific page that was crawled */
            result: {
                url: string;
            };
            /** @enum {string} */
            type: "crawl";
        };
    };
    responses: never;
    parameters: never;
    requestBodies: never;
    headers: never;
    pathItems: never;
}

type Research = components$1["schemas"]["ResearchDtoClass"];
type ResearchStatus = Research["status"];
type ResearchEvent = components$1["schemas"]["ResearchEventDtoClass"];
type ResearchOperation = components$1["schemas"]["ResearchOperationDtoClass"];
type DeepReplaceParsed<T, TData> = T extends {
    parsed?: Record<string, unknown>;
} ? Omit<T, "parsed"> & {
    parsed: TData;
} : T extends object ? {
    [K in keyof T]: DeepReplaceParsed<T[K], TData>;
} : T;
type ResearchTyped<T> = DeepReplaceParsed<Research, T>;
type ResearchStreamEventTyped<T> = DeepReplaceParsed<ResearchStreamEvent, T>;
type ListResearchRequest = {
    cursor?: string;
    limit?: number;
};
type ListResearchResponse = components$1["schemas"]["ListResearchResponseDto"];
type ResearchCreateRequest = components$1["schemas"]["ResearchCreateRequestDtoClass"];
type ResearchCreateResponse = Research;
type ResearchStreamEvent = ResearchEvent;
/**
 * Enhanced research creation params with zod schema support
 */
type ResearchCreateParamsTyped<T> = {
    instructions: string;
    model?: ResearchCreateRequest["model"];
    outputSchema?: T;
};
type ResearchDefinitionEvent = Extract<ResearchEvent, {
    eventType: "research-definition";
}>;
type ResearchOutputEvent = Extract<ResearchEvent, {
    eventType: "research-output";
}>;
type ResearchPlanDefinitionEvent = Extract<ResearchEvent, {
    eventType: "plan-definition";
}>;
type ResearchPlanOperationEvent = Extract<ResearchEvent, {
    eventType: "plan-operation";
}>;
type ResearchPlanOutputEvent = Extract<ResearchEvent, {
    eventType: "plan-output";
}>;
type ResearchTaskDefinitionEvent = Extract<ResearchEvent, {
    eventType: "task-definition";
}>;
type ResearchTaskOperationEvent = Extract<ResearchEvent, {
    eventType: "task-operation";
}>;
type ResearchTaskOutputEvent = Extract<ResearchEvent, {
    eventType: "task-output";
}>;

type QueryParams$1 = Record<string, string | number | boolean | string[] | undefined>;
interface RequestBody$1 {
    [key: string]: unknown;
}
declare class ResearchBaseClient {
    protected client: Exa;
    constructor(client: Exa);
    protected request<T = unknown>(endpoint: string, method?: string, data?: RequestBody$1, params?: QueryParams$1): Promise<T>;
    protected rawRequest(endpoint: string, method?: string, data?: RequestBody$1, params?: QueryParams$1): Promise<Response>;
    protected buildPaginationParams(pagination?: ListResearchRequest): QueryParams$1;
}

declare class ResearchClient extends ResearchBaseClient {
    constructor(client: Exa);
    create<T>(params: ResearchCreateParamsTyped<ZodSchema<T>>): Promise<ResearchCreateResponse>;
    create(params: {
        instructions: string;
        model?: ResearchCreateRequest["model"];
        outputSchema?: Record<string, unknown>;
    }): Promise<ResearchCreateResponse>;
    get(researchId: string): Promise<Research>;
    get(researchId: string, options: {
        stream?: false;
        events?: boolean;
    }): Promise<Research>;
    get<T>(researchId: string, options: {
        stream?: false;
        events?: boolean;
        outputSchema: ZodSchema<T>;
    }): Promise<ResearchTyped<T>>;
    get(researchId: string, options: {
        stream: true;
        events?: boolean;
    }): Promise<AsyncGenerator<ResearchStreamEvent, any, any>>;
    get<T>(researchId: string, options: {
        stream: true;
        events?: boolean;
        outputSchema?: ZodSchema<T>;
    }): Promise<AsyncGenerator<ResearchStreamEvent, any, any>>;
    list(options?: ListResearchRequest): Promise<ListResearchResponse>;
    pollUntilFinished(researchId: string, options?: {
        pollInterval?: number;
        timeoutMs?: number;
        events?: boolean;
    }): Promise<Research & {
        status: "completed" | "failed" | "canceled";
    }>;
    pollUntilFinished<T>(researchId: string, options?: {
        pollInterval?: number;
        timeoutMs?: number;
        events?: boolean;
        outputSchema: ZodSchema<T>;
    }): Promise<ResearchTyped<T> & {
        status: "completed" | "failed" | "canceled";
    }>;
}

/**
 * Base client for Websets API
 */

/**
 * Type for API query parameters
 */
type QueryParams = Record<string, string | number | boolean | string[] | undefined>;
/**
 * Type for API request body
 */
interface RequestBody {
    [key: string]: unknown;
}
/**
 * Common pagination parameters
 */
interface PaginationParams {
    /**
     * Cursor for pagination
     */
    cursor?: string;
    /**
     * Maximum number of items per page
     */
    limit?: number;
}
/**
 * Base client class for all Websets-related API clients
 */
declare class WebsetsBaseClient {
    protected client: Exa;
    /**
     * Initialize a new Websets base client
     * @param client The Exa client instance
     */
    constructor(client: Exa);
    /**
     * Make a request to the Websets API
     * @param endpoint The endpoint path
     * @param method The HTTP method
     * @param data Optional request body data
     * @param params Optional query parameters
     * @returns The response JSON
     * @throws ExaError with API error details if the request fails
     */
    protected request<T = unknown>(endpoint: string, method?: string, data?: RequestBody, params?: QueryParams, headers?: Record<string, string>): Promise<T>;
    /**
     * Helper to build pagination parameters
     * @param pagination The pagination parameters
     * @returns QueryParams object with pagination parameters
     */
    protected buildPaginationParams(pagination?: PaginationParams): QueryParams;
}

interface components {
    schemas: {
        /** Article */
        ArticleEntity: {
            /**
             * @default article
             * @constant
             */
            type: "article";
        };
        /** Company */
        CompanyEntity: {
            /**
             * @default company
             * @constant
             */
            type: "company";
        };
        CreateCriterionParameters: {
            /** @description The description of the criterion */
            description: string;
        };
        CreateEnrichmentParameters: {
            /** @description Provide a description of the enrichment task you want to perform to each Webset Item. */
            description: string;
            /**
             * @description Format of the enrichment response.
             *
             *     We automatically select the best format based on the description. If you want to explicitly specify the format, you can do so here.
             * @enum {string}
             */
            format?: CreateEnrichmentParametersFormat;
            /** @description Set of key-value pairs you want to associate with this object. */
            metadata?: {
                [key: string]: string;
            };
            /** @description When the format is options, the different options for the enrichment agent to choose from. */
            options?: {
                /** @description The label of the option */
                label: string;
            }[];
        };
        CreateImportParameters: {
            /** @description The number of records to import */
            count: number;
            /** @description When format is `csv`, these are the specific import parameters. */
            csv?: {
                /** @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. */
                identifier?: number;
            };
            /** @description What type of entity the import contains (e.g. People, Companies, etc.), and thus should be attempted to be resolved as. */
            entity: components["schemas"]["CompanyEntity"] | components["schemas"]["PersonEntity"] | components["schemas"]["ArticleEntity"] | components["schemas"]["ResearchPaperEntity"] | components["schemas"]["CustomEntity"];
            /**
             * @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.
             * @enum {string}
             */
            format: CreateImportParametersFormat;
            /** @description Set of key-value pairs you want to associate with this object. */
            metadata?: {
                [key: string]: string;
            };
            /** @description The size of the file in bytes. Maximum size is 50 MB. */
            size: number;
            /** @description The title of the import */
            title?: string;
        };
        /** @description The response to a successful import. Includes the upload URL and the upload valid until date. */
        CreateImportResponse: {
            /** @description The number of entities in the import */
            count: number;
            /**
             * Format: date-time
             * @description When the import was created
             */
            createdAt: string;
            /** @description The type of entity the import contains. */
            entity: components["schemas"]["Entity"];
            /**
             * Format: date-time
             * @description When the import failed
             */
            failedAt: string | null;
            /** @description A human readable message of the import failure */
            failedMessage: string | null;
            /**
             * @description The reason the import failed
             * @enum {string|null}
             */
            failedReason: CreateImportResponseFailedReason;
            /**
             * @description The format of the import.
             * @enum {string}
             */
            format: CreateImportResponseFormat;
            /** @description The unique identifier for the Import */
            id: string;
            /** @description Set of key-value pairs you want to associate with this object. */
            metadata: {
                [key: string]: string;
            };
            /**
             * @description The type of object
             * @enum {string}
             */
            object: CreateImportResponseObject;
            /**
             * @description The status of the Import
             * @enum {string}
             */
            status: CreateImportResponseStatus;
            /** @description The title of the import */
            title: string;
            /**
             * Format: date-time
             * @description When the import was last updated
             */
            updatedAt: string;
            /** @description The URL to upload the file to */
            uploadUrl: string;
            /** @description The date and time until the upload URL is valid. The upload URL will be valid for 1 hour. */
            uploadValidUntil: string;
        };
        CreateMonitorParameters: {
            /** @description Behavior to perform when monitor runs */
            behavior: {
                /** @description Specify the search parameters for the Monitor.
                 *
                 *     By default, the search parameters (query, entity and criteria) from the last search are used when no parameters are provided. */
                config: {
                    /**
                     * @description The behaviour of the Search when it is added to a Webset.
                     * @default append
                     * @enum {string}
                     */
                    behavior: WebsetSearchBehavior;
                    /** @description The maximum number of results to find */
                    count: number;
                    /** @description The criteria to search for. By default, the criteria from the last search is used. */
                    criteria?: {
                        description: string;
                    }[];
                    /**
                     * Entity
                     * @description The entity to search for. By default, the entity from the last search/import is used.
                     */
                    entity?: components["schemas"]["Entity"];
                    /** @description The query to search for. By default, the query from the last search is used. */
                    query?: string;
                };
                /**
                 * @default search
                 * @constant
                 */
                type: "search";
            };
            /** @description How often the monitor will run */
            cadence: {
                /** @description Cron expression for monitor cadence (must be a valid Unix cron with 5 fields). The schedule must trigger at m