> ## Documentation Index
> Fetch the complete documentation index at: https://docs.novita.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Exa Search

Search the web and optionally extract content from returned results. This is a passthrough to Exa's Search API, exposed through the Novita gateway with a platform route prefix.

To authenticate with your Novita API key, get one from the [Novita dashboard](https://novita.ai/settings/key-management). Base URL: `https://api.novita.ai`.

## Quickstart

```bash theme={"system"}
curl -X POST 'https://api.novita.ai/v3/exa/search' \
  -H 'Authorization: Bearer <api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "what makes a good API design",
    "contents": {"highlights": true}
  }'
```

Running the quickstart above returns the following at the time of publishing. The default request returns up to 10 results; two are shown here.

```json theme={"system"}
{
  "requestId": "de41749e9680ea844f760e0ffacc0246",
  "results": [
    {
      "id": "https://docs.cloud.google.com/apis/design",
      "title": "API design guide  |  Cloud API Design Guide  |  Google Cloud Documentation",
      "url": "https://docs.cloud.google.com/apis/design",
      "highlights": [
        "This is a general design guide for networked APIs. It has been used inside Google since 2014 and is the guide that Google follows when designing Cloud APIs and other Google APIs. This design guide is shared here to inform outside developers and to make it…"
      ],
      "image": "https://docs.cloud.google.com/_static/cloud/images/social-icon-google-cloud-1200-630.png",
      "favicon": "https://www.gstatic.com/devrel-devsite/prod/v544324a32f4e1e28baf5bd35dca83b6157fef32c5ffbe146b7ca395602e11426/clouddocs/images/favicons/onecloud/favicon.ico"
    },
    {
      "id": "https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design",
      "title": "Web API Design Best Practices - Azure Architecture Center | Microsoft Learn",
      "url": "https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design",
      "author": "claytonsiemens77",
      "highlights": [
        "A RESTful web API implementation is a web API that employs Representational State Transfer (REST) architectural principles to achieve a stateless, loosely coupled interface between a client and service. A web API that is RESTful supports the standard HTTP…"
      ],
      "image": "https://learn.microsoft.com/en-us/media/open-graph-image.png"
    }
  ],
  "searchTime": 936.2
}
```

## Request Headers

All endpoints require platform API authentication.

**Content-Type** `string` *required*

Use `application/json`.

**Authorization** `string` *required* (default: Bearer YOUR\_API\_KEY)

Platform API key, formatted as `Bearer YOUR_API_KEY`.

## Request Body

**query** `string` *required*

Search query. Minimum length is 1.

**includeDomains** `string[]`

Restrict results to these domains. Maximum 1200 entries.

**excludeDomains** `string[]`

Exclude results from these domains. Maximum 1200 entries.

**startPublishedDate** `string`

Include links published after this ISO 8601 date-time.

**endPublishedDate** `string`

Include links published before this ISO 8601 date-time.

**numResults** `integer`

Number of results to return. Default is `10`; supported public range is `1` to `100`.

**moderation** `boolean`

Enable content moderation to filter unsafe content from search results. Default is `false`.

**contents** `object`

Content extraction options for search results.

**contents properties**

**text** `boolean | object`

Return page text, or an object to configure text extraction.

**text properties**

**maxCharacters** `integer`

Maximum number of text characters to return. Range is `1` to `10000`.

**includeHtmlTags** `boolean`

Include lightweight HTML tags instead of plain text.

**verbosity** `string` (default: compact)

Requested text verbosity. One of `compact`, `standard`, or `full`.

**includeSections** `string[]`

Semantic page sections to keep. Best-effort classification. Each entry is one of `header`, `navigation`, `banner`, `body`, `sidebar`, `footer`, or `metadata`.

**excludeSections** `string[]`

Semantic page sections to drop. Best-effort classification. Each entry is one of `header`, `navigation`, `banner`, `body`, `sidebar`, `footer`, or `metadata`.

**highlights** `boolean | object`

Return selected highlight snippets, or an object to configure highlight extraction.

**highlights properties**

**query** `string`

Custom query used to select highlights.

**maxCharacters** `integer`

Maximum characters to return for highlights. Range is `1` to `10000`.

**summary** `boolean | object`

Generate a summary of each result. Pass `true` for a default summary, or an object to configure it.

**summary properties**

**query** `string`

Custom instruction for summary generation.

**schema** `object`

Optional JSON schema for structured summary output.

**extras** `object`

Return extra page data such as links, image links, rich links, or code blocks.

**extras properties**

**links** `integer`

Number of links to return. Range is `0` to `1000`.

**imageLinks** `integer`

Number of image links to return. Range is `0` to `1000`.

**richImageLinks** `integer`

Number of rich image links to return. Range is `0` to `1000`.

**richLinks** `integer`

Number of rich links to return. Range is `0` to `1000`.

**codeBlocks** `integer`

Number of code blocks to return. Range is `0` to `1000`.

**livecrawlTimeout** `integer` (default: 10000)

Timeout for live crawling in milliseconds. Must be greater than `0` and at most `90000`. Default is `10000`.

**maxAgeHours** `integer`

Maximum cache age in hours. `0` requests fresh content; `-1` always uses cache. Range is `-1` to `720`.

**subpages** `integer`

Number of subpages to crawl. Range is `0` to `100`.

**subpageTarget** `string | string[]`

Term or terms used to find targeted subpages. Each string must be `1` to `100` characters.

**additionalQueries** `string[]`

Additional query variants for deep-search modes. Range is `1` to `10` entries.

**type** `string`

Search mode. One of `instant`, `fast`, `auto`, `deep-lite`, `deep`, or `deep-reasoning`.

**category** `string`

Data category hint. Known values include `company`, `research paper`, `news`, `personal site`, `financial report`, `publication`, and `people`.

Some values restrict which filters can be used:

* `company` does not support `startPublishedDate`, `endPublishedDate`, `startCrawlDate`, `endCrawlDate`, or `excludeDomains`.
* `people` does not support `startPublishedDate`, `endPublishedDate`, `startCrawlDate`, `endCrawlDate`, or `excludeDomains`, and `includeDomains` is limited to supported profile domains.

**userLocation** `string`

Two-letter ISO country code, such as `US`.

**compliance** `string`

Enterprise compliance mode. Only `hipaa` is supported.

**outputSchema** `object`

JSON Schema object for structured synthesized output. Supported root types include `text` and `object`; object schemas should describe the expected JSON object returned by Exa.

**outputSchema properties**

**type** `string`

JSON Schema root type, commonly `text` or `object`.

**description** `string`

Description of the structured output to guide generation.

**properties** `object`

Field definitions for the structured output.

**required** `string[]`

Required property names.

**additionalProperties** `boolean | object`

Whether undeclared fields are allowed, or a schema for additional fields.

**systemPrompt** `string`

Extra instructions that guide synthesized output.

## Examples

### Search with highlights

```bash theme={"system"}
curl -X POST 'https://api.novita.ai/v3/exa/search' \
  -H 'Authorization: Bearer <api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "how do vector databases handle high-dimensional indexing",
    "numResults": 10,
    "type": "auto",
    "contents": {
      "highlights": true
    }
  }'
```

### Restrict to trusted domains

Use `includeDomains` to keep results within sources you trust.

```bash theme={"system"}
curl -X POST 'https://api.novita.ai/v3/exa/search' \
  -H 'Authorization: Bearer <api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "postgres logical replication conflict handling",
    "includeDomains": ["postgresql.org", "aws.amazon.com"],
    "numResults": 5
  }'
```

### Recent results only

Combine the `news` category with a published-date floor to filter out stale pages.

```bash theme={"system"}
curl -X POST 'https://api.novita.ai/v3/exa/search' \
  -H 'Authorization: Bearer <api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "offshore wind farm capacity additions",
    "category": "news",
    "startPublishedDate": "2026-01-01T00:00:00.000Z"
  }'
```

### Structured output from a deep search

Use `type: deep` with an `outputSchema` to get a synthesized, schema-shaped result.

```bash theme={"system"}
curl -X POST 'https://api.novita.ai/v3/exa/search' \
  -H 'Authorization: Bearer <api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "which company acquired Instagram and in what year",
    "type": "deep",
    "outputSchema": {
      "type": "object",
      "properties": {
        "acquirer": {"type": "string"},
        "amountUsd": {"type": "string"},
        "yearAnnounced": {"type": "integer"}
      },
      "required": ["acquirer"]
    }
  }'
```

## Response

**requestId** `string`

Unique request identifier.

**results** `object[]`

Search results.

**result properties**

**title** `string`

Result title.

**url** `string`

Result URL.

**publishedDate** `string`

Published date when available.

**author** `string`

Author when available.

**id** `string`

Exa document ID.

**image** `string`

Associated image URL.

**favicon** `string`

Site favicon URL.

**text** `string`

Extracted page text when requested.

**highlights** `string[]`

Highlight snippets when requested.

**summary** `string`

Generated summary when requested.

**subpages** `object[]`

Subpage results when requested.

**subpage properties**

**title** `string` *required*

Subpage title.

**url** `string` *required*

Subpage URL.

**publishedDate** `string`

Published date when available.

**author** `string`

Author when available.

**id** `string`

Exa document ID.

**image** `string`

Associated image URL.

**favicon** `string`

Site favicon URL.

**extras** `object`

Container for extra page data. Each child field is present only when its matching `contents.extras` count is requested, and may be an empty array when the page has no such data.

**extras properties**

**links** `string[]`

Extracted links when `extras.links` is requested.

**imageLinks** `string[]`

Image links when `extras.imageLinks` is requested.

**richImageLinks** `object[]`

Rich image links when `extras.richImageLinks` is requested.

**richLinks** `object[]`

Rich links when `extras.richLinks` is requested.

**codeBlocks** `object[]`

Code blocks when `extras.codeBlocks` is requested.

**codeBlock properties**

**text** `string`

Code block content.

**source** `string`

Where the block was extracted from, such as `text`.

**entities** `object[]`

Structured entities extracted from the result, most often returned for the `company`, `people`, and `publication` categories. It may be absent or empty depending on the query and page.

**entity properties**

**id** `string`

Stable entity identifier.

**type** `string`

Entity discriminator. One of `company`, `person`, or `publication`.

**version** `integer`

Entity schema version.

**properties** `object`

Type-specific fields. The shape depends on `type`.

**company properties**

**name** `string`

Company name.

**foundedYear** `integer`

Year the company was founded.

**description** `string`

Short company description.

**workforce** `object`

Workforce data.

**workforce properties**

**total** `number`

Total headcount.

**headquarters** `object`

Headquarters location.

**headquarters properties**

**address** `string`

Street address.

**city** `string`

City.

**postalCode** `string`

Postal code.

**country** `string`

Country.

**financials** `object`

Financial data.

**financials properties**

**revenueAnnual** `number`

Annual revenue.

**fundingTotal** `number`

Total funding raised.

**fundingLatestRound** `object`

Most recent funding round.

**fundingLatestRound properties**

**name** `string`

Round name, such as `Series C`.

**date** `string`

Date of the round.

**amount** `number`

Amount raised in the round.

**webTraffic** `object`

Web traffic data.

**webTraffic properties**

**visitsMonthly** `number`

Monthly visits.

**countryRank** `integer`

Rank within the country.

**avgDurationSeconds** `number`

Average visit duration in seconds.

**history** `object[]`

Historical traffic data points.

**history item properties**

**value** `number`

Traffic value for the period.

**dateFrom** `string`

Period start, formatted as `YYYY-MM`.

**dateTo** `string`

Period end, formatted as `YYYY-MM`.

**research** `object`

Research output.

**research properties**

**worksCount** `integer`

Number of published works.

**citationCount** `integer`

Total citations.

**areas** `string[]`

Research areas.

**notableWorks** `object[]`

Notable works.

**notableWork item properties**

**title** `string`

Work title.

**year** `integer`

Publication year.

**venue** `string`

Publication venue.

**citationCount** `integer`

Number of citations.

**doi** `string`

Digital Object Identifier.

**id** `string`

Work identifier.

**type** `string`

Work type. One of `article`, `book`, `book-chapter`, `dataset`, `dissertation`, `preprint`, `report`, or `review`.

**topResearchers** `object[]`

Leading researchers associated with the company.

**topResearcher item properties**

**person** `object`

The researcher.

**person properties**

**name** `string`

Researcher name.

**id** `string`

Researcher identifier.

**worksCount** `integer`

Number of published works.

**citationCount** `integer`

Total citations.

**person properties**

**name** `string`

Full name.

**firstName** `string`

First name.

**lastName** `string`

Last name.

**location** `string`

Location.

**workHistory** `object[]`

Work history entries.

**workHistory item properties**

**title** `string`

Job title.

**location** `string`

Location.

**dates** `object`

Date range.

**dates properties**

**from** `string`

Start date.

**to** `string`

End date.

**company** `object`

Employer.

**company properties**

**id** `string`

Company identifier.

**name** `string`

Company name.

**educationHistory** `object[]`

Education entries.

**educationHistory item properties**

**degree** `string`

Degree earned.

**dates** `object`

Date range.

**dates properties**

**from** `string`

Start date.

**to** `string`

End date.

**institution** `object`

Institution.

**institution properties**

**id** `string`

Institution identifier.

**name** `string`

Institution name.

**research** `object`

Research output.

**research properties**

**worksCount** `integer`

Number of published works.

**citationCount** `integer`

Total citations.

**hIndex** `integer`

h-index.

**firstPublicationYear** `integer`

Year of first publication.

**latestPublicationYear** `integer`

Year of most recent publication.

**areas** `string[]`

Research areas.

**notableWorks** `object[]`

Notable works.

**notableWork item properties**

**title** `string`

Work title.

**year** `integer`

Publication year.

**venue** `string`

Publication venue.

**citationCount** `integer`

Number of citations.

**doi** `string`

Digital Object Identifier.

**id** `string`

Work identifier.

**type** `string`

Work type. One of `article`, `book`, `book-chapter`, `dataset`, `dissertation`, `preprint`, `report`, or `review`.

**publication properties**

**title** `string`

Publication title.

**year** `integer`

Publication year.

**date** `string`

Publication date.

**type** `string`

Publication type. One of `article`, `book`, `book-chapter`, `dataset`, `dissertation`, `preprint`, `report`, or `review`.

**language** `string`

Language.

**citationCount** `integer`

Number of citations.

**authors** `object[]`

Authors.

**author properties**

**name** `string`

Author name.

**id** `string`

Author identifier.

**referenceCount** `integer`

Number of references.

**abstract** `string`

Abstract text.

**output** `object`

Structured or synthesized output when requested.

**output properties**

**content** `string | object`

Generated content. It can be structured when `outputSchema` is provided.

**grounding** `object[]`

Field-level grounding and citation metadata when returned.

**grounding properties**

**field** `string`

The field path in `output.content` this grounding applies to.

**citations** `object[]`

Sources supporting the field.

**citation properties**

**url** `string` *required*

Source URL.

**title** `string` *required*

Source title.

**confidence** `string`

Grounding confidence. One of `low`, `medium`, or `high`.

**searchTime** `number`

Time taken to search in milliseconds.

## Errors

Errors are returned as a JSON envelope with `code`, `reason`, `message`, and `metadata`. The platform validates and authenticates the request before forwarding it to Exa, so some errors originate at the platform and others are surfaced from upstream.

| Status | `reason` | Meaning |
| - | - | - |
| `400` | `MISSING_API_KEY` | The `Authorization` header is absent. |
| `400` | `INVALID_REQUEST_BODY` | The body failed validation, such as a missing or malformed `query`. |
| `403` | `INVALID_API_KEY` | The API key is invalid or not authorized. |
| `404` | `PATH_NOT_FOUND` | The route does not exist. |
| `429` | `RATE_LIMIT_EXCEEDED` | Too many requests. Slow down and retry with backoff. |
| `500` | `TASK_FAILED` | Internal or upstream provider failure. Transient failures are safe to retry. |
| `503` | `SERVICE_UNAVAILABLE` | The service is temporarily overloaded or down. Retry with backoff. |

For validation failures, `message` is a JSON-encoded string carrying the detailed `error` and `tag`. The examples below show that inner detail decoded for readability.

```json 200 theme={"system"}
{
  "requestId": "string",
  "results": [
    {
      "id": "string",
      "title": "string",
      "url": "string",
      "publishedDate": "string",
      "author": "string",
      "image": "string",
      "favicon": "string",
      "text": "string",
      "highlights": ["string"],
      "summary": "string",
      "subpages": [
        {
          "title": "string",
          "url": "string",
          "publishedDate": "string",
          "author": "string",
          "id": "string",
          "image": "string",
          "favicon": "string"
        }
      ],
      "extras": {
        "links": ["string"],
        "imageLinks": ["string"],
        "richImageLinks": [{}],
        "richLinks": [{}],
        "codeBlocks": [{"text": "string", "source": "string"}]
      },
      "entities": [
        {
          "id": "string",
          "type": "string",
          "version": 0,
          "properties": {}
        }
      ]
    }
  ],
  "output": {
    "content": "string",
    "grounding": [
      {
        "field": "string",
        "citations": [
          {
            "url": "string",
            "title": "string"
          }
        ],
        "confidence": "string"
      }
    ]
  },
  "searchTime": 0
}
```

```json 400 theme={"system"}
{
  "code": 400,
  "reason": "INVALID_REQUEST_BODY",
  "message": "Invalid request body | Validation error: expected string, received undefined at \"query\"",
  "metadata": {
    "trace_id": "d1fbd8a046d4eb0d46f93c77c1ac59b4"
  }
}
```

```json 403 theme={"system"}
{
  "code": 403,
  "reason": "INVALID_API_KEY",
  "message": "invalid api-key",
  "metadata": {}
}
```

```json 404 theme={"system"}
{
  "code": 404,
  "reason": "PATH_NOT_FOUND",
  "message": "path not found for model",
  "metadata": {
    "trace_id": "3c3433f0cb475a04f9a4969b8c6ed903"
  }
}
```

```json 429 theme={"system"}
{
  "code": 429,
  "reason": "RATE_LIMIT_EXCEEDED",
  "message": "rate limit exceeded, please retry later",
  "metadata": {
    "trace_id": "5f2a9c7e41b8d0a36e9f4c2b7d81a0e5"
  }
}
```

```json 500 theme={"system"}
{
  "code": 500,
  "reason": "TASK_FAILED",
  "message": "upstream provider temporarily unavailable, please retry",
  "metadata": {
    "trace_id": "8846379c692d7218173460afe95640f1"
  }
}
```

```json 503 theme={"system"}
{
  "code": 503,
  "reason": "SERVICE_UNAVAILABLE",
  "message": "service temporarily unavailable",
  "metadata": {
    "trace_id": "b7e3f1a9d24c05e8f63a1b9c7e05d2f4"
  }
}
```

## Notes

* All request bodies are JSON.
* Extra Exa parameters not listed here may be passed through.
* Response shapes can vary depending on request options.
* This document intentionally omits billing-related fields.

## References

For more details, see the [Exa Search API reference](https://exa.ai/docs/reference/search).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.