Getting started
Installing the exa-js SDKTypeScript
Get API Key
Follow this link to get your API key
search
Method
Perform an Exa search given an input query and retrieve a list of relevant results as links.
Input Example
Input Parameters
Parameter | Type | Description | Default |
---|---|---|---|
query | string | The input query string. | Required |
numResults | number | Number of search results to return. | 10 |
includeDomains | string[] | List of domains to include in the search. | undefined |
excludeDomains | string[] | List of domains to exclude in the search. | undefined |
startCrawlDate | string | Results will only include links crawled after this date. | undefined |
endCrawlDate | string | Results will only include links crawled before this date. | undefined |
startPublishedDate | string | Results will only include links with a published date after this date. | undefined |
endPublishedDate | string | Results will only include links with a published date before this date. | undefined |
type | string | The type of search, “keyword” or “neural”. | “auto” |
category | string | data category to focus on when searching, with higher comprehensivity and data cleanliness. Available categories: “company”, “research paper”, “news”, “linkedin profile”, “github”, “tweet”, “movie”, “song”, “personal site”, “pdf”, “financial report”. | undefined |
includeText | string[] | List of strings that must be present in webpage text of results. Currently, only 1 string is supported, of up to 5 words. | undefined |
excludeText | string[] | List of strings that must not be present in webpage text of results. Currently, only 1 string is supported, of up to 5 words. Checks from the first 1000 words of the webpage text. | undefined |
Returns Example
Return Parameters
SearchResponse
Field | Type | Description |
---|---|---|
results | Result[] | List of Result objects |
Result
Object
Field | Type | Description |
---|---|---|
url | string | URL of the search result |
id | string | Temporary ID for the document |
title | string | null | Title of the search result |
searchAndContents
Method
Perform an Exa search given an input query and retrieve a list of relevant results as links, optionally including the full text and/or highlights of the content.
Input Example
TypeScript
Input Parameters
Parameter | Type | Description | Default |
---|---|---|---|
query | string | The input query string. | Required |
text | boolean | { maxCharacters?: number, includeHtmlTags?: boolean } | If provided, includes the full text of the content in the results. | undefined |
highlights | boolean | { query?: string, numSentences?: number, highlightsPerUrl?: number } | If provided, includes highlights of the content in the results. | undefined |
numResults | number | Number of search results to return. | 10 |
includeDomains | string[] | List of domains to include in the search. | undefined |
excludeDomains | string[] | List of domains to exclude in the search. | undefined |
startCrawlDate | string | Results will only include links crawled after this date. | undefined |
endCrawlDate | string | Results will only include links crawled before this date. | undefined |
startPublishedDate | string | Results will only include links with a published date after this date. | undefined |
endPublishedDate | string | Results will only include links with a published date before this date. | undefined |
type | string | The type of search, “keyword” or “neural”. | “auto” |
category | string | A data category to focus on when searching, with higher comprehensivity and data cleanliness. Available categories: “company”, “research paper”, “news”, “linkedin profile”, “github”, “tweet”, “movie”, “song”, “personal site”, “pdf” and “financial report”. | undefined |
includeText | string[] | List of strings that must be present in webpage text of results. Currently, only 1 string is supported, of up to 5 words. | undefined |
excludeText | string[] | List of strings that must not be present in webpage text of results. Currently, only 1 string is supported, of up to 5 words. Checks from the first 1000 words of the webpage text. | undefined |
Returns Example
JSON
Return Parameters
SearchResponse
Field | Type | Description |
---|---|---|
results | SearchResult<T>[] | List of SearchResult objects |
SearchResult
Extends the Result
object from the search
method with additional fields based on T
:
Field | Type | Description |
---|---|---|
text? | string | Text of the search result page (if requested) |
highlights? | string[] | Highlights of the search result (if requested) |
highlightScores? | number[] | Scores of the highlights (if requested) |
SearchResult<T>
object depend on the options provided in the searchAndContents
call.
findSimilar
Method
Find a list of similar results based on a webpage’s URL.
Input Example
Input Parameters
Parameter | Type | Description | Default |
---|---|---|---|
url | string | The URL of the webpage to find similar results for. | Required |
numResults | number | Number of similar results to return. | undefined |
includeDomains | string[] | List of domains to include in the search. | undefined |
excludeDomains | string[] | List of domains to exclude from the search. | undefined |
startCrawlDate | string | Results will only include links crawled after this date. | undefined |
endCrawlDate | string | Results will only include links crawled before this date. | undefined |
startPublishedDate | string | Results will only include links with a published date after this date. | undefined |
endPublishedDate | string | Results will only include links with a published date before this date. | undefined |
excludeSourceDomain | boolean | If true, excludes results from the same domain as the input URL. | undefined |
category | string | A data category to focus on when searching, with higher comprehensivity and data cleanliness. | undefined |
Returns Example
JSON
Return Parameters
SearchResponse
Field | Type | Description |
---|---|---|
results | Result[] | List of Result objects |
Result
Object
Field | Type | Description |
---|---|---|
url | string | URL of the search result |
id | string | Temporary ID for the document |
title | string | null | Title of the search result |
findSimilarAndContents
Method
Find a list of similar results based on a webpage’s URL, optionally including the text content or highlights of each result.
Input Example
TypeScript
Input Parameters
Parameter | Type | Description | Default |
---|---|---|---|
url | string | The URL of the webpage to find similar results for. | Required |
text | boolean | { maxCharacters?: number, includeHtmlTags?: boolean } | If provided, includes the full text of the content in the results. | undefined |
highlights | boolean | { query?: string, numSentences?: number, highlightsPerUrl?: number } | If provided, includes highlights of the content in the results. | undefined |
numResults | number | Number of similar results to return. | undefined |
includeDomains | string[] | List of domains to include in the search. | undefined |
excludeDomains | string[] | List of domains to exclude from the search. | undefined |
startCrawlDate | string | Results will only include links crawled after this date. | undefined |
endCrawlDate | string | Results will only include links crawled before this date. | undefined |
startPublishedDate | string | Results will only include links with a published date after this date. | undefined |
endPublishedDate | string | Results will only include links with a published date before this date. | undefined |
excludeSourceDomain | boolean | If true, excludes results from the same domain as the input URL. | undefined |
category | string | A data category to focus on when searching, with higher comprehensivity and data cleanliness. | undefined |
Returns Example
JSON
Return Parameters
SearchResponse
Field | Type | Description |
---|---|---|
results | SearchResult<T>[] | List of SearchResult objects |
SearchResult
Extends theResult
object with additional fields based on the requested content:
Field | Type | Description | |
---|---|---|---|
url | string | URL of the search result | |
id | string | Temporary ID for the document | |
title | `string | null` | Title of the search result |
SearchResult<T>
object depend on the options provided in the findSimilarAndContents
call.
getContents
Method
Retrieves contents of documents based on a list of document IDs.
Input Example
TypeScript
Input Parameters
Parameter | Type | Description | Default |
---|---|---|---|
ids | string | string[] | SearchResult[]` | A single ID, an array of IDs, or an array of SearchResults. | Required |
text | boolean | { maxCharacters?: number, includeHtmlTags?: boolean } | If provided, includes the full text of the content in the results. | undefined |
highlights | boolean | { query?: string, numSentences?: number, highlightsPerUrl?: number } | If provided, includes highlights of the content in the results. | undefined |
Returns Example
JSON
Return Parameters
SearchResponse
Field | Type | Description |
---|---|---|
results | SearchResult<T>[] | List of SearchResult objects |
SearchResult
The fields in the SearchResult<T>
object depend on the options provided in the getContents
call:
Field | Type | Description | |
---|---|---|---|
id | string | Temporary ID for the document | |
url | string | URL of the search result | |
title | `string | null` | Title of the search result |
publishedDate? | string | Estimated creation date | |
author? | string | Author of the content, if available | |
text? | string | Text of the search result page (if requested) | |
highlights? | string[] | Highlights of the search result (if requested) | |
highlightScores? | number[] | Scores of the highlights (if requested) |
SearchResult<T>
object depend on the options provided in the getContents
call. If neither text
nor highlights
is specified, the method defaults to including the full text content.
answer
Method
Generate an answer to a query using Exa’s search and LLM capabilities. This returns an AnswerResponse object with the answer text and citations used. You may optionally retrieve the full text of each source by setting text: true
.
Input Example
TypeScript
Input Parameters
Parameter | Type | Description | Default |
---|---|---|---|
query | string | The question or query to answer. | Required |
options | {text?: boolean} | If text is true, each source in the result includes its full text. |
Returns Example
JSON
Return Parameters
AnswerResponse
TypeScript
Field | Type | Description |
---|---|---|
answer | string | The generated answer text |
citations | SearchResult<{ }>[] | The citations used to generate the answer |
requestId? | string | Optional request ID for reference |
SearchResult<{}>
— a basic result object that can include text if options.text was set to true.
streamAnswer
Method
Generate a streaming answer to a query with Exa’s LLM capabilities. This returns an async generator yielding chunks of text and/or citations as they become available.
Input Example
TypeScript
Input Parameters
Parameter | Type | Description | Default |
---|---|---|---|
query | string | The question to answer. | Required |
options | { text?: boolean } | If text is true, each citation chunk includes its full text. |
Return Type
An async generator of objects with the type:TypeScript
content
is the partial text content of the answer so far (streamed in chunks).citations
is an array of citation objects that appear at this chunk in the response.
research.create
Method
Create an asynchronous research task that performs multi-step web research and returns structured JSON results with citations.
Input Example
TypeScript
Input Parameters
Parameter | Type | Description | Default |
---|---|---|---|
instructions | string | Natural language instructions describing what the research task should accomplish. | Required |
model | ResearchModel | The research model to use. Options: ResearchModel.exa_research, ResearchModel.exa_research_pro | exa_research |
outputSchema | object | Optional JSON schema for structured output. If not provided, schema will be inferred. | undefined |
Returns Example
JSON
Return Type
TypeScript
Field | Type | Description |
---|---|---|
researchId | string | The unique identifier for the task |
research.get
Method
Get the current status and results of a research task by its ID.
Input Example
TypeScript
Input Parameters
Parameter | Type | Description | Default |
---|---|---|---|
researchId | string | The unique identifier of the task | Required |
Returns Example
JSON
Return Type
TypeScript
Field | Type | Description |
---|---|---|
researchId | string | The unique identifier for the task |
status | string | Task status: “running”, “completed”, or “failed” |
instructions | string | The original instructions provided |
schema | object (optional) | The JSON schema specification used |
data | object (optional) | The research results (when completed) |
citations | Record<string, Citation[]> (optional) | Citations grouped by root field (when completed) |
research.pollUntilFinished
Method
Poll a research task until it completes or fails, returning the final result.
Input Example
TypeScript
Input Parameters
Parameter | Type | Description | Default |
---|---|---|---|
researchId | string | The unique identifier of the task | Required |
Returns
Returns aResearchTask
object with the completed task data (same structure as getTask
).
research.list
Method
List all research tasks with optional pagination.
Input Example
TypeScript
Input Parameters
Parameter | Type | Description | Default |
---|---|---|---|
cursor | string | Pagination cursor from previous request | undefined |
limit | number | Number of results to return (1-200) | 25 |
Returns Example
JSON
Return Type
TypeScript
Field | Type | Description |
---|---|---|
data | ResearchTask[] | List of research task objects |
hasMore | boolean | Whether there are more results to paginate |
nextCursor | string (optional) | Cursor for the next page (if hasMore is true) |