TypeScript SDK Specification
For ChatGPT-based TypeScript SDK assistance, go here.
Getting started
Installing the exa-js SDK
and then instantiate an Exa client
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 |
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 |
score? | number | Similarity score between query/url and result |
publishedDate? | string | Estimated creation date |
author? | string | Author of the content, if available |
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
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 |
Returns Example
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) |
Note: The actual fields present in the 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
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 |
score? | number | Similarity score between query/url and result |
publishedDate? | string | Estimated creation date |
author? | string | Author of the content, if available |
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
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
Return Parameters
SearchResponse
Field | Type | Description |
---|---|---|
results | SearchResult<T>[] | List of SearchResult objects |
SearchResult
Extends the Result
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 |
score? | number | Similarity score between query/url and 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) |
Note: The actual fields present in the 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
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
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) |
Note: The actual fields present in the 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
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
Return Parameters
AnswerResponse
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 |
Each citation is a 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
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:
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.
You can end iteration by using a break or by letting the loop finish naturally.
research.createTask
Method
Create an asynchronous research task that performs multi-step web research and returns structured JSON results with citations.
Input Example
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 |
output | { schema?: object, inferSchema?: boolean } | Output configuration with optional JSON schema or automatic schema inference. | undefined |
Returns Example
Return Type
Field | Type | Description |
---|---|---|
id | string | The unique identifier for the task |
research.getTask
Method
Get the current status and results of a research task by its ID.
Input Example
Input Parameters
Parameter | Type | Description | Default |
---|---|---|---|
id | string | The unique identifier of the task | Required |
Returns Example
Return Type
Field | Type | Description |
---|---|---|
id | 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.pollTask
Method
Poll a research task until it completes or fails, returning the final result.
Input Example
Input Parameters
Parameter | Type | Description | Default |
---|---|---|---|
id | string | The unique identifier of the task | Required |
Note: The pollTask method automatically polls every 1 second with a timeout of 10 minutes.
Returns
Returns a ResearchTask
object with the completed task data (same structure as getTask
).
research.listTasks
Method
List all research tasks with optional pagination.
Input Example
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
Return Type
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) |