TypeScript SDK Specification

For ChatGPT-based Typescript SDK assistance, go here.

Getting started

Installing the exa-js SDK

npm
pnpm


npm install exa-js

pnpm install exa-js

and then instantiate an Exa client

TypeScript

import Exa from 'exa-js';

const exa = new Exa(process.env.EXA_API_KEY);

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

const result = await exa.search(
  "hottest AI startups",
  {
    useAutoprompt: true,
    numResults: 2
  }
);

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
useAutoprompt	boolean	If true, convert query to a query best suited for Exa.	false
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”, “github”, “tweet”, “movie”, “song”, “personal site”, “pdf”.	undefined

Returns Example

{
  "autopromptString": "Here is a link to one of the hottest AI startups:",
  "results": [
    {
      "score": 0.17025552690029144,
      "title": "Adept: Useful General Intelligence",
      "id": "https://www.adept.ai/",
      "url": "https://www.adept.ai/",
      "publishedDate": "2000-01-01",
      "author": null
    },
    {
      "score": 0.1700288951396942,
      "title": "Home | Tenyx, Inc.",
      "id": "https://www.tenyx.com/",
      "url": "https://www.tenyx.com/",
      "publishedDate": "2019-09-10",
      "author": null
    }
  ]
}

Return Parameters

SearchResponse

Field	Type	Description
results	Result[]	List of Result objects
autopromptString?	string	Exa query created by autoprompt functionality

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

TypeScript

// Search with full text content
const resultWithText = await exa.searchAndContents(
  "AI in healthcare",
  {
    text: true,
    numResults: 2
  }
);

// Search with highlights
const resultWithHighlights = await exa.searchAndContents(
  "AI in healthcare",
  {
    highlights: true,
    numResults: 2
  }
);

// Search with both text and highlights
const resultWithTextAndHighlights = await exa.searchAndContents(
  "AI in healthcare",
  {
    text: true,
    highlights: true,
    numResults: 2
  }
);

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
useAutoprompt	boolean	If true, convert query to a query best suited for Exa.	false
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”, “github”, “tweet”, “movie”, “song”, “personal site”, “pdf”.	undefined

Returns Example

JSON

{
  "results": [
    {
      "score": 0.20826785266399384,
      "title": "2023 AI Trends in Health Care",
      "id": "https://aibusiness.com/verticals/2023-ai-trends-in-health-care-",
      "url": "https://aibusiness.com/verticals/2023-ai-trends-in-health-care-",
      "publishedDate": "2022-12-29",
      "author": "Wylie Wong",
      "text": "While the health care industry was initially slow to [... TRUNCATED FOR BREVITY ...]",
      "highlights": [
        "But to do so, many health care institutions would like to share data, so they can build a more comprehensive dataset to use to train an AI model. Traditionally, they would have to move the data to one central repository. However, with federated or swarm learning, the data does not have to move. Instead, the AI model goes to each individual health care facility and trains on the data, he said. This way, health care providers can maintain security and governance over their data."
      ],
      "highlightScores": [
        0.5566554069519043
      ]
    },
    {
      "score": 0.20796334743499756,
      "title": "AI in healthcare: Innovative use cases and applications",
      "id": "https://www.leewayhertz.com/ai-use-cases-in-healthcare",
      "url": "https://www.leewayhertz.com/ai-use-cases-in-healthcare",
      "publishedDate": "2023-02-13",
      "author": "Akash Takyar",
      "text": "The integration of AI in healthcare is not [... TRUNCATED FOR BREVITY ...]",
      "highlights": [
        "The ability of AI to analyze large amounts of medical data and identify patterns has led to more accurate and timely diagnoses. This has been especially helpful in identifying complex medical conditions, which may be difficult to detect using traditional methods. Here are some examples of successful implementation of AI in healthcare. IBM Watson Health: IBM Watson Health is an AI-powered system used in healthcare to improve patient care and outcomes. The system uses natural language processing and machine learning to analyze large amounts of data and provide personalized treatment plans for patients."
      ],
      "highlightScores": [
        0.6563674807548523
      ]
    }
  ]
}

Return Parameters

SearchResponse

Field	Type	Description
results	SearchResult<T>[]	List of SearchResult objects
autopromptString?	string	Exa query created by autoprompt functionality

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

const similarResults = await exa.findSimilar(
  "https://www.example.com",
  {
    numResults: 2,
    excludeSourceDomain: true
  }
);

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

{
  "results": [
    {
      "score": 0.8777582049369812,
      "title": "Play New Free Online Games Every Day",
      "id": "https://www.minigames.com/new-games",
      "url": "https://www.minigames.com/new-games",
      "publishedDate": "2000-01-01",
      "author": null
    },
    {
      "score": 0.87653648853302,
      "title": "Play The best Online Games",
      "id": "https://www.minigames.com/",
      "url": "https://www.minigames.com/",
      "publishedDate": "2000-01-01",
      "author": null
    }
  ]
}

Return Parameters

SearchResponse

Field	Type	Description
results	Result[]	List of Result objects
autopromptString?	string	Exa query created by autoprompt functionality

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

TypeScript

// Find similar with full text content
const similarWithText = await exa.findSimilarAndContents(
  "https://www.example.com/article",
  {
    text: true,
    numResults: 2
  }
);

// Find similar with highlights
const similarWithHighlights = await exa.findSimilarAndContents(
  "https://www.example.com/article",
  {
    highlights: true,
    numResults: 2
  }
);

// Find similar with both text and highlights
const similarWithTextAndHighlights = await exa.findSimilarAndContents(
  "https://www.example.com/article",
  {
    text: true,
    highlights: true,
    numResults: 2,
    excludeSourceDomain: true
  }
);

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

{
  "results": [
    {
      "score": 0.8777582049369812,
      "title": "Similar Article: AI and Machine Learning",
      "id": "https://www.similarsite.com/ai-ml-article",
      "url": "https://www.similarsite.com/ai-ml-article",
      "publishedDate": "2023-05-15",
      "author": "Jane Doe",
      "text": "Artificial Intelligence (AI) and Machine Learning (ML) are revolutionizing various industries. [... TRUNCATED FOR BREVITY ...]",
      "highlights": [
        "AI and ML are transforming how businesses operate, enabling more efficient processes and data-driven decision making.",
        "The future of AI looks promising, with potential applications in healthcare, finance, and autonomous vehicles."
      ],
      "highlightScores": [
        0.95,
        0.89
      ]
    },
    {
      "score": 0.87653648853302,
      "title": "The Impact of AI on Modern Technology",
      "id": "https://www.techblog.com/ai-impact",
      "url": "https://www.techblog.com/ai-impact",
      "publishedDate": "2023-06-01",
      "author": "John Smith",
      "text": "In recent years, artificial intelligence has made significant strides in various technological domains. [... TRUNCATED FOR BREVITY ...]",
      "highlights": [
        "AI is not just a buzzword; it's a transformative technology that's reshaping industries and creating new opportunities.",
        "As AI continues to evolve, ethical considerations and responsible development become increasingly important."
      ],
      "highlightScores": [
        0.92,
        0.88
      ]
    }
  ]
}

Return Parameters

SearchResponse

Field	Type	Description
results	SearchResult<T>[]	List of SearchResult objects
autopromptString?	string	Exa query created by autoprompt functionality

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

TypeScript

// Get contents for a single ID
const singleContent = await exa.getContents("https://www.example.com/article");

// Get contents for multiple IDs
const multipleContents = await exa.getContents([
  "https://www.example.com/article1",
  "https://www.example.com/article2"
]);

// Get contents with specific options
const contentsWithOptions = await exa.getContents(
  ["https://www.example.com/article1", "https://www.example.com/article2"],
  {
    text: { maxCharacters: 1000 },
    highlights: { query: "AI", numSentences: 2 }
  }
);

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

{
  "results": [
    {
      "id": "https://www.example.com/article1",
      "url": "https://www.example.com/article1",
      "title": "The Future of Artificial Intelligence",
      "publishedDate": "2023-06-15",
      "author": "Jane Doe",
      "text": "Artificial Intelligence (AI) has made significant strides in recent years. [... TRUNCATED FOR BREVITY ...]",
      "highlights": [
        "AI is revolutionizing industries from healthcare to finance, enabling more efficient processes and data-driven decision making.",
        "As AI continues to evolve, ethical considerations and responsible development become increasingly important."
      ],
      "highlightScores": [
        0.95,
        0.92
      ]
    },
    {
      "id": "https://www.example.com/article2",
      "url": "https://www.example.com/article2",
      "title": "Machine Learning Applications in Business",
      "publishedDate": "2023-06-20",
      "author": "John Smith",
      "text": "Machine Learning (ML) is transforming how businesses operate and make decisions. [... TRUNCATED FOR BREVITY ...]",
      "highlights": [
        "Machine Learning algorithms can analyze vast amounts of data to identify patterns and make predictions.",
        "Businesses are leveraging ML for customer segmentation, demand forecasting, and fraud detection."
      ],
      "highlightScores": [
        0.93,
        0.90
      ]
    }
  ]
}

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.

Exa Search

Rag Quick Start Guide

Concepts

Admin

SDK References

Tutorials

Live Demos

Integrations External Docs

Recent Updates

Documentation Index

​Getting started

Get API Key

​search Method

​Input Example

​Input Parameters

​Returns Example

​Return Parameters

​SearchResponse

​Result Object

​searchAndContents Method

​Input Example

​Input Parameters

​Returns Example

​Return Parameters

​SearchResponse

​SearchResult

​findSimilar Method

​Input Example

​Input Parameters

​Returns Example

​Return Parameters

​SearchResponse

​Result Object

​findSimilarAndContents Method

​Input Example

​Input Parameters

​Returns Example

​Return Parameters

​SearchResponse

​SearchResult

​getContents Method

​Input Example

​Input Parameters

​Returns Example

​Return Parameters

​SearchResponse

​SearchResult

Getting started

`search` Method

Input Example

Input Parameters

Returns Example

Return Parameters

SearchResponse

Result Object

`searchAndContents` Method

Input Example

Input Parameters

Returns Example

Return Parameters

SearchResponse

SearchResult

`findSimilar` Method

Input Example

Input Parameters

Returns Example

Return Parameters

SearchResponse

Result Object

`findSimilarAndContents` Method

Input Example

Input Parameters

Returns Example

Return Parameters

SearchResponse

SearchResult

`getContents` Method

Input Example

Input Parameters

Returns Example

Return Parameters

SearchResponse

SearchResult