For ChatGPT-based Python SDK assistance, go here.

Getting started

Install the exa-py SDK

pip install exa_py

and then instantiate an Exa client

from exa_py import Exa

import os

exa = Exa(os.getenv('EXA_API_KEY'))

Get API Key

`search` Method

Perform an Exa search given an input query and retrieve a list of relevant results as links.

Input Example

result = exa.search(
  "hottest AI startups",
  use_autoprompt=True,
  num_results=2
)

Input Parameters

Parameter	Type	Description	Default
`query`	`str`	The input query string.	Required
`num_results`	`Optional[int]`	Number of search results to return.	`10`
`include_domains`	`Optional[List[str]]`	List of domains to include in the search.	`None`
`exclude_domains`	`Optional[List[str]]`	List of domains to exclude in the search.	`None`
`include_text`	`Optional[List[str]]`	List of strings that must be present in the webpage text of results. Currently, only one string is supported, up to 5 words.	`None`
`start_crawl_date`	`Optional[str]`	Results will only include links crawled after this date.	`None`
`end_crawl_date`	`Optional[str]`	Results will only include links crawled before this date.	`None`
`start_published_date`	`Optional[str]`	Results will only include links with a published date after this date.	`None`
`end_published_date`	`Optional[str]`	Results will only include links with a published date before this date.	`None`
`use_autoprompt`	`Optional[bool]`	If true, convert query to a query best suited for Exa.	`False`
`type`	`Optional[str]`	The type of search, `keyword` or `neural`.	`"auto"`
`category`	`Optional[str]`	A data category to focus on when searching, with higher comprehensivity and data cleanliness. Currently, the available categories are: `company`, `research paper`, `news`, `github`, `tweet`, `movie`, `song`, `personal site`, `pdf`	`None`

Returns Example

Returns:

{
  "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
    }
  ],
  "requestId": "a78ebce717f4d712b6f8fe0d5d7753f8"
}

Return Parameters

SearchResponse[Result]

Field	Type	Description
`results`	`List[Result]`	List of Result objects
`autoprompt_string`	`Optional[str]`	Exa query created by autoprompt functionality

Result Object

Field	Type	Description
`url`	`str`	URL of the search result
`id`	`str`	Temporary ID for the document
`title`	`Optional[str]`	Title of the search result
`score`	`Optional[float]`	Similarity score between query/url and result
`published_date`	`Optional[str]`	Estimated creation date
`author`	`Optional[str]`	Author of the content, if available

`search_and_contents` 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

# Search with full text content
result_with_text = exa.search_and_contents(
    "AI in healthcare",
    text=True,
    num_results=2
)

# Search with highlights
result_with_highlights = exa.search_and_contents(
    "AI in healthcare",
    highlights=True,
    num_results=2
)

# Search with both text and highlights
result_with_text_and_highlights = exa.search_and_contents(
    "AI in healthcare",
    text=True,
    highlights=True,
    num_results=2
)

Input Parameters

Parameter	Type	Description	Default
`query`	`str`	The input query string.	Required
`text`	`Union[TextContentsOptions, Literal[True]]`	If provided, includes the full text of the content in the results.	`None`
`summaries`	`Union[SummariesContentsOptions, Literal[True]]`	If provided, provides a summary (Gemini-Flash-based) of the content in the results.	`None`
`highlights`	`Union[HighlightsContentsOptions, Literal[True]]`	If provided, includes highlights of the content in the results.	`None`
`num_results`	`Optional[int]`	Number of search results to return.	`10`
`include_domains`	`Optional[List[str]]`	List of domains to include in the search.	`None`
`exclude_domains`	`Optional[List[str]]`	List of domains to exclude in the search.	`None`
`include_text`	`Optional[List[str]]`	List of strings that must be present in the webpage text of results. Currently, only one string is supported, up to 5 words.	`None`
`start_crawl_date`	`Optional[str]`	Results will only include links crawled after this date.	`None`
`end_crawl_date`	`Optional[str]`	Results will only include links crawled before this date.	`None`
`start_published_date`	`Optional[str]`	Results will only include links with a published date after this date.	`None`
`end_published_date`	`Optional[str]`	Results will only include links with a published date before this date.	`None`
`use_autoprompt`	`Optional[bool]`	If true, convert query to a query best suited for Exa.	`False`
`type`	`Optional[str]`	The type of search, `keyword` or `neural`.	`"auto"`
`category`	`Optional[str]`	A data category to focus on when searching, with higher comprehensivity and data cleanliness. Currently, the available categories are: `company`, `research paper`, `news`, `github`, `tweet`, `movie`, `song`, `personal site`, `pdf`	`None`
`livecrawl`	`Literal["always", "fallback", "never"]`	Options for live crawling content. This will get the newest content for your results.	Default is "never" for neural/auto search, "fallback" for keyword search.
`livecrawlTimeout`	`int`	The timeout for live crawling in milliseconds. Max: 10000ms.	10000

Returns Example

{
  "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 IN THESE DOCS 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 IN THESE DOCS 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
      ]
    }
  ],
  "requestId": "d8fd59c78d34afc9da173f1fe5aa8965"
}

Return Parameters

The return type depends on the combination of text and highlights parameters:

SearchResponse[ResultWithText]: When only text is provided.
SearchResponse[ResultWithHighlights]: When only highlights is provided.
SearchResponse[ResultWithTextAndHighlights]: When both text and highlights are provided.

SearchResponse[ResultWithTextAndHighlights]

Field	Type	Description
`results`	`List[ResultWithTextAndHighlights]`	List of ResultWithTextAndHighlights objects
`autoprompt_string`	`Optional[str]`	Exa query created by autoprompt functionality

ResultWithTextAndHighlights Object

Field	Type	Description
`url`	`str`	URL of the search result
`id`	`str`	Temporary ID for the document
`title`	`Optional[str]`	Title of the search result
`score`	`Optional[float]`	Similarity score between query/url and result
`published_date`	`Optional[str]`	Estimated creation date
`author`	`Optional[str]`	Author of the content, if available
`text`	`str`	Text of the search result page (always present)
`highlights`	`List[str]`	Highlights of the search result (always present)
`highlight_scores`	`List[float]`	Scores of the highlights (always present)

Note: If neither text nor highlights is specified, the method defaults to including the full text content.

`find_similar` Method

Find a list of similar results based on a webpage's URL.

Input Example

similar_results = exa.find_similar(
    "miniclip.com",
    num_results=2,
    exclude_source_domain=True
)

Input Parameters

Parameter	Type	Description	Default
`url`	`str`	The URL of the webpage to find similar results for.	Required
`num_results`	`Optional[int]`	Number of similar results to return.	`None`
`include_domains`	`Optional[List[str]]`	List of domains to include in the search.	`None`
`exclude_domains`	`Optional[List[str]]`	List of domains to exclude from the search.	`None`
`include_text`	`Optional[List[str]]`	List of strings that must be present in the webpage text of results. Currently, only one string is supported, up to 5 words.	`None`
`start_crawl_date`	`Optional[str]`	Results will only include links crawled after this date.	`None`
`end_crawl_date`	`Optional[str]`	Results will only include links crawled before this date.	`None`
`start_published_date`	`Optional[str]`	Results will only include links with a published date after this date.	`None`
`end_published_date`	`Optional[str]`	Results will only include links with a published date before this date.	`None`
`exclude_source_domain`	`Optional[bool]`	If true, excludes results from the same domain as the input URL.	`None`
`category`	`Optional[str]`	A data category to focus on when searching, with higher comprehensivity and data cleanliness.	`None`

Returns Example

{
  "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
    }
  ],
  "requestId": "08fdc6f20e9f3ea87f860af3f6ccc30f"
}

Return Parameters

SearchResponse[_Result]: The response containing similar results and optional autoprompt string.

SearchResponse[Results]

Field	Type	Description
`results`	`List[ResultWithTextAndHighlights]`	List of ResultWithTextAndHighlights objects
`autoprompt_string`	`Optional[str]`	Exa query created by autoprompt functionality

Results Object

Field	Type	Description
`url`	`str`	URL of the search result
`id`	`str`	Temporary ID for the document
`title`	`Optional[str]`	Title of the search result
`score`	`Optional[float]`	Similarity score between query/url and result
`published_date`	`Optional[str]`	Estimated creation date
`author`	`Optional[str]`	Author of the content, if available

`find_similar_and_contents` 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

# Find similar with full text content
similar_with_text = exa.find_similar_and_contents(
    "https://example.com/article",
    text=True,
    num_results=2
)

# Find similar with highlights
similar_with_highlights = exa.find_similar_and_contents(
    "https://example.com/article",
    highlights=True,
    num_results=2
)

# Find similar with both text and highlights
similar_with_text_and_highlights = exa.find_similar_and_contents(
    "https://example.com/article",
    text=True,
    highlights=True,
    num_results=2
)

Input Parameters

Parameter	Type	Description	Default
`url`	`str`	The URL of the webpage to find similar results for.	Required
`text`	`Union[TextContentsOptions, Literal[True]]`	If provided, includes the full text of the content in the results.	`None`
`highlights`	`Union[HighlightsContentsOptions, Literal[True]]`	If provided, includes highlights of the content in the results.	`None`
`num_results`	`Optional[int]`	Number of similar results to return.	`None`
`summaries`	`Union[SummariesContentsOptions, Literal[True]]`	If provided, provides a summary (Gemini-Flash-based) of the content in the results.	`None`
`include_domains`	`Optional[List[str]]`	List of domains to include in the search.	`None`
`exclude_domains`	`Optional[List[str]]`	List of domains to exclude from the search.	`None`
`include_text`	`Optional[List[str]]`	List of strings that must be present in the webpage text of results. Currently, only one string is supported, up to 5 words.	`None`
`start_crawl_date`	`Optional[str]`	Results will only include links crawled after this date.	`None`
`end_crawl_date`	`Optional[str]`	Results will only include links crawled before this date.	`None`
`start_published_date`	`Optional[str]`	Results will only include links with a published date after this date.	`None`
`end_published_date`	`Optional[str]`	Results will only include links with a published date before this date.	`None`
`exclude_source_domain`	`Optional[bool]`	If true, excludes results from the same domain as the input URL.	`None`
`category`	`Optional[str]`	A data category to focus on when searching, with higher comprehensivity and data cleanliness.	`None`

Returns

The return type depends on the combination of text and highlights parameters:

SearchResponse[ResultWithText]: When only text is provided or when neither text nor highlights is provided (defaults to including text).
SearchResponse[ResultWithHighlights]: When only highlights is provided.
SearchResponse[ResultWithTextAndHighlights]: When both text and highlights are provided.

The response contains similar results and an optional autoprompt string.

Note: If neither text nor highlights is specified, the method defaults to including the full text content.

Getting started

search Method

Input Example

Input Parameters

Returns Example

Return Parameters

SearchResponse[Result]

Result Object

search_and_contents Method

Input Example

Input Parameters

Returns Example

Return Parameters

SearchResponse[ResultWithTextAndHighlights]

ResultWithTextAndHighlights Object

find_similar Method

Input Example

Input Parameters

Returns Example

Return Parameters

SearchResponse[Results]

Results Object

find_similar_and_contents Method

Input Example

Input Parameters

Returns

`search` Method

`search_and_contents` Method

`find_similar` Method

`find_similar_and_contents` Method