Getting started
Installing the exa-js SDK- npm
- pnpm
TypeScript
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. Limits vary by search type: with “keyword”: max 10, with “neural”: max 100. If you want to increase the num results, contact sales ([email protected]) | 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 |
| context | boolean | { maxCharacters?: number } | Return page contents as a context string for LLM RAG. When true, combines all result contents into one string. We recommend 10000+ characters for best results. Context strings often perform better than highlights for RAG applications. | undefined |
| numResults | number | Number of search results to return. Limits vary by search type: with “keyword”: max 10, with “neural”: max 100. If you want to increase the num results, contact sales ([email protected]) | 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
contentis the partial text content of the answer so far (streamed in chunks).citationsis 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) |

