TypeScript SDK Specification

Enumeration of methods and types in the Exa TypeScript SDK (exa-js).

Getting started

Install the exa-js SDK

npm

npm install exa-js

and then instantiate an Exa client

import Exa from "exa-js";

const exa = new Exa(); // Reads EXA_API_KEY from environment
// or explicitly: const exa = new Exa("your-api-key");

Get API Key

Follow this link to get your API key

search Method

The options.type parameter accepts: "auto" (default), "fast", "deep-lite", "deep", "deep-reasoning", or "instant". See RegularSearchOptions for all available options.

Input Example

const result = await exa.search("hottest AI startups", {
  type: "auto",
  numResults: 10,
  contents: { highlights: true },
});

Input Parameters

Parameter	Type	Description	Default
query	string	-	Required
options	RegularSearchOptions & { contents?: T | false | null | undefined }	-	Required

Return Example

{
  "results": [
    {
      "title": "Adept: Useful General Intelligence",
      "id": "https://www.adept.ai/",
      "url": "https://www.adept.ai/",
      "publishedDate": "2024-01-16T00:00:00.000Z",
      "author": null,
      "score": 0.92,
      "highlights": ["Adept builds AI agents that can automate complex software workflows."],
      "highlightScores": [0.84]
    }
  ],
  "requestId": "a78ebce717f4d712b6f8fe0d5d7753f8",
  "statuses": [
    {
      "id": "https://www.adept.ai/",
      "status": "success"
    }
  ]
}

Result Object

Field	Type	Description
results	SearchResult<T>[]	The list of search results.
requestId	string	The request ID for the search.
output	{ content: string | Record<string, unknown>; grounding: { field: string; citations: { url: string; title: string }[]; confidence: "low" | "medium" | "high" }[] }	Synthesized output object returned when outputSchema is provided.
statuses	Status[]	Status information for each result.
costDollars	CostDollars	The cost breakdown for this request.

getContents Method

Retrieves contents of documents based on URLs.

Input Example

const result = await exa.getContents(
  ["https://www.example.com/article1", "https://www.example.com/article2"],
  {
    text: { maxCharacters: 1000 },
    highlights: { query: "AI" },
  },
);

Input Parameters

Parameter	Type	Description	Default
urls	string | string[] | SearchResult<T>[]	A URL or array of URLs, or an array of SearchResult objects. *	Required
options	T	-	Required

Return Example

{
  "results": [
    {
      "url": "https://example.com/article",
      "id": "https://example.com/article",
      "title": "Example Article",
      "text": "The full text content of the article..."
    }
  ]
}

Result Object

Field	Type	Description
results	SearchResult<T>[]	The list of search results.
requestId	string	The request ID for the search.
statuses	Status[]	Status information for each result.
costDollars	CostDollars	The cost breakdown for this request.

answer Method

Input Example

const result = await exa.answer("What is the capital of France?", {
  text: true,
  model: "exa",
});

Input Parameters

Parameter	Type	Description	Default
query	string	-	Required
options	AnswerOptions | AnswerOptionsTyped&lt;ZodSchema<T&gt;>	-	Required

Return Example

{
  "answer": "The capital of France is Paris.",
  "citations": [
    {
      "id": "https://www.example.com/france",
      "url": "https://www.example.com/france",
      "title": "France - Wikipedia",
      "publishedDate": "2023-01-01",
      "author": null,
      "text": "France, officially the French Republic, is a country in... [truncated for brevity]"
    }
  ],
  "requestId": "abc123"
}

Result Object

Field	Type	Description
answer	string | Record<string, unknown>	The generated answer text (or object matching outputSchema if provided).
citations	SearchResult<{}>[]	The sources used to generate the answer.
requestId	string	The request ID for the answer.
costDollars	CostDollars	The cost breakdown for this request.

streamAnswer Method

Input Example

for await (const chunk of exa.streamAnswer("What is quantum computing?", {
  text: true,
  model: "exa",
})) {
  if (chunk.content) process.stdout.write(chunk.content);
  if (chunk.citations) console.log("Citations:", chunk.citations);
}

Input Parameters

Parameter	Type	Description	Default
query	string	-	Required
options	{ text?: boolean; model?: "exa"; systemPrompt?: string; outputSchema?: Record<string, unknown> | ZodSchema<T>; userLocation?: string; }	-	Required

Return Example

{
  "content": "The capital of France is Paris.",
  "citations": [
    {
      "id": "https://www.example.com/france",
      "url": "https://www.example.com/france",
      "title": "France - Wikipedia"
    }
  ]
}

Result Object

Field	Type	Description
content	string	The partial text content of the answer (if present in this chunk).
citations	Array<{id, url, title?, publishedDate?, author?, text?}>	Citations associated with the current chunk of text (if present).

Types Reference

This section documents the types used throughout the SDK.

Content Options

These types configure content retrieval options for the contents parameter.

ContentsOptions

Options for retrieving page contents

Field	Type	Description
text	TextContentsOptions | true	Options for retrieving text contents.
highlights	HighlightsContentsOptions | true	Options for retrieving highlights.
summary	SummaryContentsOptions | true	Options for retrieving summary.
maxAgeHours	number	Maximum age of cached content in hours. If content is older, it will be fetched fresh. Special values: 0 = always fetch fresh content, -1 = never fetch fresh (cache only). Example: 168 = fetch fresh for pages older than 7 days.
filterEmptyResults	boolean	If true, filters out results with no contents. Default is true.
subpages	number	Number of subpages to return for each result.
subpageTarget	string | string[]	Text used to match/rank subpages in the returned list.
extras	ExtrasOptions	Miscellaneous data derived from results.

BaseSearchOptions

Options for performing a search query

Field	Type	Description
contents	ContentsOptions	-
numResults	number	-
includeDomains	string[]	-
excludeDomains	string[]	-
startPublishedDate	string	-
endPublishedDate	string	-
category	| "company" | "publication" | "news" | "personal site" | "financial report" | "people"	-
includeText	string[]	-
excludeText	string[]	-
flags	string[]	-
userLocation	string	-

RegularSearchOptions

Search options for performing a search query. Uses a discriminated union to ensure additionalQueries is only allowed when type is a deep search variant.

Field	Type	Description
type	"auto" | "fast" | "deep-lite" | "deep" | "deep-reasoning" | "instant"	The type of search to perform. Default is “auto”. “instant” provides the lowest latency optimized for real-time applications.
numResults	number	Number of search results to return. Default 10. Max 10 for basic plans.
includeDomains	string[]	List of domains to include in the search.
excludeDomains	string[]	List of domains to exclude in the search.
startPublishedDate	string	Start date for results based on published date (ISO format).
endPublishedDate	string	End date for results based on published date (ISO format).
category	"company" | "publication" | "news" | "personal site" | "financial report" | "people"	A data category to focus on.
includeText	string[]	List of strings that must be present in webpage text. Max 1 string of up to 5 words.
excludeText	string[]	List of strings that must not be present in webpage text. Max 1 string of up to 5 words.
contents	ContentsOptions	Options for retrieving page contents for each result.
moderation	boolean	If true, the search results are moderated for safety.
useAutoprompt	boolean	If true, uses autoprompt to enhance the query.
userLocation	string	The two-letter ISO country code of the user, e.g. US.
systemPrompt	string	Optional instructions that guide the synthesized search output. Use with outputSchema.
additionalQueries	string[]	Alternative query formulations for deep search. Max 10 queries. Only for deep search variants such as "deep-lite", "deep", and "deep-reasoning".
outputSchema	Record<string, unknown>	JSON schema for synthesized search output (output.content follows this schema).

ExtrasOptions

Field	Type	Description
links	number	-
imageLinks	number	-

TextContentsOptions

Options for retrieving text from page.

Field	Type	Description
maxCharacters	number	-
includeHtmlTags	boolean	-
verbosity	VerbosityOptions	-
includeSections	SectionTag[]	-
excludeSections	SectionTag[]	-

HighlightsContentsOptions

Options for retrieving highlights from page. These options are supported for deep search types (“deep”, “deep-reasoning”) as well.

Field	Type	Description
query	string	-
maxCharacters	number	-
dynamic	boolean	Allocate one shared highlight budget across the result set. Incompatible with maxCharacters.

Dynamic Highlights is a research preview. Requests that set dynamic require the Exa-Beta: dynamic-highlights-2026-08-28 header; the SDK sends it automatically.

SummaryContentsOptions

Options for retrieving summary from page.

Field	Type	Description
query	string	-
schema	Record<string, unknown> | ZodSchema	-

AnswerOptions

Options for the answer endpoint

Field	Type	Description
text	boolean	Whether to include text in the source results. Default false.
model	"exa"	The model to use for generating the answer. Default “exa”.
stream	boolean	Whether to stream the response. Default false.
systemPrompt	string	A system prompt to guide the LLM’s behavior when generating the answer.
outputSchema	Record<string, unknown>	A JSON Schema specification for the structure you expect the output to take.
userLocation	string	The two-letter ISO country code of the user, e.g. US.

Response Types

These types represent API response objects.

CostDollars

Represents the total cost breakdown. Only non-zero costs are included.

Field	Type	Description
total	number	-
search	CostDollarsSearch	-
contents	CostDollarsContents	-

SearchResult

Represents a search result object.

Field	Type	Description
title	string | null	The title of the search result.
url	string	The URL of the search result.
id	string	The temporary ID for the document.
publishedDate	string	The estimated creation date of the content.
author	string	The author of the content, if available.
score	number	Similarity score between the query/url and the result.
image	string	A representative image for the content, if any.
favicon	string	A favicon for the site, if any.
text	string	The text content of the page (if text option enabled).
highlights	string[]	Highlighted text snippets (if highlights option enabled).
highlightScores	number[]	Scores for each highlight.
summary	string	Summary of the content (if summary option enabled).
entities	Entity[]	Structured entity data for company or person search results.

SearchResponse

Represents a search response object.

Field	Type	Description
results	SearchResult<T>[]	The list of search results.
requestId	string	The request ID for the search.
output	{ content: string | Record<string, unknown>; grounding: { field: string; citations: { url: string; title: string }[]; confidence: "low" | "medium" | "high" }[] }	Synthesized output object containing structured/text content and field-level grounding when outputSchema is provided.
statuses	Status[]	Status information for each result.
costDollars	CostDollars	The cost breakdown for this request.
resolvedSearchType	string	The resolved search type when auto search is used.
searchTime	number	Time taken for the search in milliseconds.

Status

Field	Type	Description
id	string	-
status	string	-
source	string	-

AnswerResponse

Represents an answer response object from the /answer endpoint.

Field	Type	Description
answer	string | Record<string, unknown>	The generated answer text (or object matching outputSchema if provided).
citations	SearchResult<{}>[]	The sources used to generate the answer.
requestId	string	The request ID for the answer.
costDollars	CostDollars	The cost breakdown for this request.

AnswerStreamChunk

Field	Type	Description
content	string	The partial text content of the answer (if present in this chunk).
citations	Array<{id, url, title?, publishedDate?, author?, text?}>	Citations associated with the current chunk of text (if present).

Entity Types

These types represent structured entity data returned for company or person searches.

EntityCompanyProperties

Structured properties for a company entity.

Field	Type	Description
name	string | null	The company name.
foundedYear	number | null	The year the company was founded.
description	string | null	A description of the company.
workforce	EntityCompanyPropertiesWorkforce | null	Information about the company’s workforce.
headquarters	EntityCompanyPropertiesHeadquarters | null	Information about the company’s headquarters location.
financials	EntityCompanyPropertiesFinancials | null	Financial information about the company.
webTraffic	EntityCompanyPropertiesWebTraffic | null	Web traffic statistics for the company.

EntityPersonProperties

Structured properties for a person entity.

Field	Type	Description
name	string | null	The person’s name.
location	string | null	The person’s location.
workHistory	EntityPersonPropertiesWorkHistoryEntry[]	The person’s work history.

CompanyEntity

Structured entity data for a company.

Field	Type	Description
id	string	Unique identifier for the entity.
type	"company"	The entity type (always “company”).
version	number	The version of the entity schema.
properties	EntityCompanyProperties	Structured properties for the company.

PersonEntity

Structured entity data for a person.

Field	Type	Description
id	string	Unique identifier for the entity.
type	"person"	The entity type (always “person”).
version	number	The version of the entity schema.
properties	EntityPersonProperties	Structured properties for the person.