For ChatGPT-based TypeScript SDK assistance, go here.

Getting started

Installing the exa-js SDK


npm 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",
  {
    numResults: 2
  }
);

Input Parameters

ParameterTypeDescriptionDefault
querystringThe input query string.Required
numResultsnumberNumber of search results to return.10
includeDomainsstring[]List of domains to include in the search.undefined
excludeDomainsstring[]List of domains to exclude in the search.undefined
startCrawlDatestringResults will only include links crawled after this date.undefined
endCrawlDatestringResults will only include links crawled before this date.undefined
startPublishedDatestringResults will only include links with a published date after this date.undefined
endPublishedDatestringResults will only include links with a published date before this date.undefined
typestringThe type of search, “keyword” or “neural”.“auto”
categorystringdata 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


{
  "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

FieldTypeDescription
resultsResult[]List of Result objects

Result Object

FieldTypeDescription
urlstringURL of the search result
idstringTemporary ID for the document
titlestring | nullTitle of the search result
score?numberSimilarity score between query/url and result
publishedDate?stringEstimated creation date
author?stringAuthor 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
  }
);

// Search with structured summary schema
const companySchema = {
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Company Information",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the company"
    },
    "industry": {
      "type": "string",
      "description": "The industry the company operates in"
    },
    "foundedYear": {
      "type": "number",
      "description": "The year the company was founded"
    },
    "keyProducts": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "List of key products or services offered by the company"
    },
    "competitors": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "List of main competitors"
    }
  },
  "required": ["name", "industry"]
};

const resultWithStructuredSummary = await exa.searchAndContents(
  "OpenAI company information",
  {
    summary: {
      schema: companySchema
    },
    category: "company",
    numResults: 3
  }
);

// Parse the structured summary (returned as a JSON string)
const firstResult = resultWithStructuredSummary.results[0];
if (firstResult.summary) {
  const structuredData = JSON.parse(firstResult.summary);
  console.log(structuredData.name);        // e.g. "OpenAI"
  console.log(structuredData.industry);    // e.g. "Artificial Intelligence"
  console.log(structuredData.keyProducts); // e.g. ["GPT-4", "DALL-E", "ChatGPT"]
}

Input Parameters

ParameterTypeDescriptionDefault
querystringThe input query string.Required
textboolean | { maxCharacters?: number, includeHtmlTags?: boolean }If provided, includes the full text of the content in the results.undefined
highlightsboolean | { query?: string, numSentences?: number, highlightsPerUrl?: number }If provided, includes highlights of the content in the results.undefined
numResultsnumberNumber of search results to return.10
includeDomainsstring[]List of domains to include in the search.undefined
excludeDomainsstring[]List of domains to exclude in the search.undefined
startCrawlDatestringResults will only include links crawled after this date.undefined
endCrawlDatestringResults will only include links crawled before this date.undefined
startPublishedDatestringResults will only include links with a published date after this date.undefined
endPublishedDatestringResults will only include links with a published date before this date.undefined
typestringThe type of search, “keyword” or “neural”.“auto”
categorystringA 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

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

FieldTypeDescription
resultsSearchResult<T>[]List of SearchResult objects

SearchResult

Extends the Result object from the search method with additional fields based on T:

FieldTypeDescription
text?stringText 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

ParameterTypeDescriptionDefault
urlstringThe URL of the webpage to find similar results for.Required
numResultsnumberNumber of similar results to return.undefined
includeDomainsstring[]List of domains to include in the search.undefined
excludeDomainsstring[]List of domains to exclude from the search.undefined
startCrawlDatestringResults will only include links crawled after this date.undefined
endCrawlDatestringResults will only include links crawled before this date.undefined
startPublishedDatestringResults will only include links with a published date after this date.undefined
endPublishedDatestringResults will only include links with a published date before this date.undefined
excludeSourceDomainbooleanIf true, excludes results from the same domain as the input URL.undefined
categorystringA 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

FieldTypeDescription
resultsResult[]List of Result objects

Result Object

FieldTypeDescription
urlstringURL of the search result
idstringTemporary ID for the document
titlestring | nullTitle of the search result
score?numberSimilarity score between query/url and result
publishedDate?stringEstimated creation date
author?stringAuthor 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

ParameterTypeDescriptionDefault
urlstringThe URL of the webpage to find similar results for.Required
textboolean | { maxCharacters?: number, includeHtmlTags?: boolean }If provided, includes the full text of the content in the results.undefined
highlightsboolean | { query?: string, numSentences?: number, highlightsPerUrl?: number }If provided, includes highlights of the content in the results.undefined
numResultsnumberNumber of similar results to return.undefined
includeDomainsstring[]List of domains to include in the search.undefined
excludeDomainsstring[]List of domains to exclude from the search.undefined
startCrawlDatestringResults will only include links crawled after this date.undefined
endCrawlDatestringResults will only include links crawled before this date.undefined
startPublishedDatestringResults will only include links with a published date after this date.undefined
endPublishedDatestringResults will only include links with a published date before this date.undefined
excludeSourceDomainbooleanIf true, excludes results from the same domain as the input URL.undefined
categorystringA 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

FieldTypeDescription
resultsSearchResult<T>[]List of SearchResult objects

SearchResult

Extends the Result object with additional fields based on the requested content:

FieldTypeDescription
urlstringURL of the search result
idstringTemporary ID for the document
title`stringnull`Title of the search result
score?numberSimilarity score between query/url and result
publishedDate?stringEstimated creation date
author?stringAuthor of the content, if available
text?stringText 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

ParameterTypeDescriptionDefault
idsstring | string[] | SearchResult[]`A single ID, an array of IDs, or an array of SearchResults.Required
textboolean | { maxCharacters?: number, includeHtmlTags?: boolean }If provided, includes the full text of the content in the results.undefined
highlightsboolean | { 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

FieldTypeDescription
resultsSearchResult<T>[]List of SearchResult objects

SearchResult

The fields in the SearchResult<T> object depend on the options provided in the getContents call:

FieldTypeDescription
idstringTemporary ID for the document
urlstringURL of the search result
title`stringnull`Title of the search result
publishedDate?stringEstimated creation date
author?stringAuthor of the content, if available
text?stringText 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

TypeScript
// Basic usage
const answerResponse = await exa.answer("What is the capital of France?");
console.log(answerResponse);

// If you want the full text of each citation in the result
const answerWithText = await exa.answer("What is the capital of France?", { text: true });
console.log(answerWithText);

Input Parameters

ParameterTypeDescriptionDefault
querystringThe 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
{
  "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"
}

Return Parameters

AnswerResponse

TypeScript
interface AnswerResponse {
  answer: string;
  citations: SearchResult<{}>[];
  requestId?: string;
}
FieldTypeDescription
answerstringThe generated answer text
citationsSearchResult<{ }>[]The citations used to generate the answer
requestId?stringOptional 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

TypeScript
for await (const chunk of exa.streamAnswer("Explain quantum entanglement in simple terms.", { text: true })) {
  if (chunk.content) {
    process.stdout.write(chunk.content); // partial text
  }
  if (chunk.citations) {
    console.log("\nCitations:");
    console.log(chunk.citations);
  }
}

Input Parameters

ParameterTypeDescriptionDefault
querystringThe 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
interface AnswerStreamChunk {
  content?: string;
  citations?: Array<{
    id: string;
    url: string;
    title?: string;
    publishedDate?: string;
    author?: string;
    text?: string;
  }>;
}
  • 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

TypeScript
import Exa, { ResearchModel } from "exa-js";

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

// Simple research task
const instructions = "What is the latest valuation of SpaceX?";
const schema = {
  type: "object",
  properties: {
    valuation: { type: "string" },
    date: { type: "string" },
    source: { type: "string" }
  }
};

const task = await exa.research.createTask({
  instructions: instructions,
  output: { schema: schema }
});

// Or even simpler - let the model infer the schema
const simpleTask = await exa.research.createTask({
  instructions: "What are the main benefits of meditation?",
  output: { inferSchema: true }
});

console.log(`Task created with ID: ${task.id}`);

Input Parameters

ParameterTypeDescriptionDefault
instructionsstringNatural language instructions describing what the research task should accomplish.Required
modelResearchModelThe research model to use. Options: ResearchModel.exa_research, ResearchModel.exa_research_proexa_research
output{ schema?: object, inferSchema?: boolean }Output configuration with optional JSON schema or automatic schema inference.undefined

Returns Example

JSON
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Return Type

TypeScript
interface CreateTaskResponse {
  id: string;
}
FieldTypeDescription
idstringThe unique identifier for the task

research.getTask Method

Get the current status and results of a research task by its ID.


Input Example

TypeScript
// Get a research task by ID
const taskId = "your-task-id-here";
const task = await exa.research.getTask(taskId);

console.log(`Task status: ${task.status}`);
if (task.status === "completed") {
  console.log(`Results: ${JSON.stringify(task.data)}`);
  console.log(`Citations: ${JSON.stringify(task.citations)}`);
}

Input Parameters

ParameterTypeDescriptionDefault
idstringThe unique identifier of the taskRequired

Returns Example

JSON
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "instructions": "What is the latest valuation of SpaceX?",
  "schema": {
    "type": "object",
    "properties": {
      "valuation": {"type": "string"},
      "date": {"type": "string"},
      "source": {"type": "string"}
    }
  },
  "data": {
    "valuation": "$350 billion",
    "date": "December 2024",
    "source": "Financial Times"
  },
  "citations": {
    "valuation": [
      {
        "id": "https://www.ft.com/content/...",
        "url": "https://www.ft.com/content/...",
        "title": "SpaceX valued at $350bn in employee share sale",
        "snippet": "SpaceX has been valued at $350bn..."
      }
    ]
  }
}

Return Type

TypeScript
interface ResearchTask {
  id: string;
  status: "running" | "completed" | "failed";
  instructions: string;
  schema?: object;
  data?: object;
  citations?: Record<string, Citation[]>;
}

interface Citation {
  id: string;
  url: string;
  title?: string;
  snippet: string;
}
FieldTypeDescription
idstringThe unique identifier for the task
statusstringTask status: “running”, “completed”, or “failed”
instructionsstringThe original instructions provided
schemaobject (optional)The JSON schema specification used
dataobject (optional)The research results (when completed)
citationsRecord<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

TypeScript
// Create and poll a task until completion
const task = await exa.research.createTask({
  instructions: "Get information about Paris, France",
  output: {
    schema: {
      type: "object",
      properties: {
        name: { type: "string" },
        population: { type: "string" },
        founded_date: { type: "string" }
      }
    }
  }
});

// Poll until completion
const result = await exa.research.pollTask(task.id);
console.log(`Research complete: ${JSON.stringify(result.data)}`);

Input Parameters

ParameterTypeDescriptionDefault
idstringThe unique identifier of the taskRequired

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

TypeScript
// List all research tasks
const response = await exa.research.listTasks();
console.log(`Found ${response.data.length} tasks`);

// List with pagination
const paginatedResponse = await exa.research.listTasks({ limit: 10 });
if (paginatedResponse.hasMore) {
  const nextPage = await exa.research.listTasks({
    cursor: paginatedResponse.nextCursor
  });
}

Input Parameters

ParameterTypeDescriptionDefault
cursorstringPagination cursor from previous requestundefined
limitnumberNumber of results to return (1-200)25

Returns Example

JSON
{
  "data": [
    {
      "id": "task-1",
      "status": "completed",
      "instructions": "Research SpaceX valuation",
      ...
    },
    {
      "id": "task-2",
      "status": "running",
      "instructions": "Compare GPU specifications",
      ...
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI0LTAxLTE1VDE4OjMwOjAwWiIsImlkIjoidGFzay0yIn0="
}

Return Type

TypeScript
interface ListTasksResponse {
  data: ResearchTask[];
  hasMore: boolean;
  nextCursor?: string;
}
FieldTypeDescription
dataResearchTask[]List of research task objects
hasMorebooleanWhether there are more results to paginate
nextCursorstring (optional)Cursor for the next page (if hasMore is true)