Exa

Exa

Access the Exa API with managed API key authentication. Perform neural web searches, retrieve page contents, find similar pages, get AI-generated answers with citations, and run async research tasks.

Quick Start

# Search the web
python <<'EOF'
import urllib.request, os, json
data = json.dumps({"query": "latest AI research", "numResults": 5}).encode()
req = urllib.request.Request('https://gateway.maton.ai/exa/search', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Base URL

https://gateway.maton.ai/exa/{endpoint}

Replace {endpoint} with the Exa API endpoint (search, contents, findSimilar, answer, research/v1). The gateway proxies requests to api.exa.ai and automatically injects your API key.

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key

Connection Management

Manage your Exa API key connections at https://ctrl.maton.ai.

List Connections

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=exa&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Connection

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'exa', 'method': 'API_KEY'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Open the returned url in a browser to enter your Exa API key.

Get Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Delete Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Specifying Connection

If you have multiple Exa connections, specify which one to use with the Maton-Connection header:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({"query": "AI news"}).encode()
req = urllib.request.Request('https://gateway.maton.ai/exa/search', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If omitted, the gateway uses the default (oldest) active connection.

API Reference

Search

Perform a neural web search with optional content extraction.

POST /exa/search
Content-Type: application/json

{
  "query": "latest AI research papers",
  "numResults": 10
}

Request Parameters:

Contents Options:

{
  "contents": {
    "text": true,
    "highlights": true,
    "summary": true
  }
}

Response:

{
  "requestId": "abc123",
  "resolvedSearchType": "neural",
  "results": [
    {
      "id": "https://example.com/article",
      "title": "Article Title",
      "url": "https://example.com/article",
      "publishedDate": "2024-01-15T00:00:00.000Z",
      "author": "Author Name",
      "text": "Full page content...",
      "highlights": ["Relevant snippet 1", "Relevant snippet 2"],
      "summary": "AI-generated summary..."
    }
  ],
  "costDollars": {
    "total": 0.005
  }
}

Get Contents

Retrieve full page contents for specific URLs.

POST /exa/contents
Content-Type: application/json

{
  "ids": ["https://example.com/page1", "https://example.com/page2"],
  "text": true
}

Request Parameters:

Response:

{
  "requestId": "abc123",
  "results": [
    {
      "id": "https://example.com/page1",
      "url": "https://example.com/page1",
      "title": "Page Title",
      "text": "Full page content..."
    }
  ]
}

Find Similar

Find pages similar to a given URL.

POST /exa/findSimilar
Content-Type: application/json

{
  "url": "https://example.com",
  "numResults": 10
}

Request Parameters:

Response:

{
  "requestId": "abc123",
  "results": [
    {
      "id": "https://similar-site.com",
      "title": "Similar Site",
      "url": "https://similar-site.com",
      "score": 0.95
    }
  ],
  "costDollars": {
    "total": 0.005
  }
}

Answer

Get an AI-generated answer to a question with citations.

POST /exa/answer
Content-Type: application/json

{
  "query": "What is machine learning?",
  "text": true
}

Request Parameters:

Response:

{
  "requestId": "abc123",
  "answer": "Machine learning is a subset of artificial intelligence...",
  "citations": [
    {
      "id": "https://example.com/ml-guide",
      "url": "https://example.com/ml-guide",
      "title": "Machine Learning Guide"
    }
  ]
}

Research Tasks

Run asynchronous research tasks that explore the web, gather sources, and synthesize findings with citations.

Create Research Task

POST /exa/research/v1
Content-Type: application/json

{
  "instructions": "What are the top AI companies and their main products?",
  "model": "exa-research"
}

Request Parameters:

Response:

{
  "researchId": "r_01abc123",
  "createdAt": 1772969504083,
  "model": "exa-research",
  "instructions": "What are the top AI companies...",
  "status": "running"
}

Get Research Task

GET /exa/research/v1/{researchId}

Query Parameters:

Response (completed):

{
  "researchId": "r_01abc123",
  "status": "completed",
  "createdAt": 1772969504083,
  "finishedAt": 1772969520000,
  "model": "exa-research",
  "instructions": "What are the top AI companies...",
  "output": {
    "content": "Based on my research, the top AI companies are..."
  },
  "costDollars": {
    "total": 0.15,
    "numSearches": 5,
    "numPages": 20,
    "reasoningTokens": 1500
  }
}

Status values: pending, running, completed, canceled, failed

List Research Tasks

GET /exa/research/v1?limit=10

Query Parameters:

Response:

{
  "data": [
    {
      "researchId": "r_01abc123",
      "status": "completed",
      "model": "exa-research",
      "instructions": "What are the top AI companies..."
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Code Examples

JavaScript

// Search with content extraction
const response = await fetch('https://gateway.maton.ai/exa/search', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.MATON_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'latest AI news',
    numResults: 5,
    contents: { text: true, highlights: true }
  })
});
const data = await response.json();

Python

import os
import requests

# Search with content extraction
response = requests.post(
    'https://gateway.maton.ai/exa/search',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    json={
        'query': 'latest AI news',
        'numResults': 5,
        'contents': {'text': True, 'highlights': True}
    }
)
data = response.json()

Notes

• Search types: neural (semantic), auto (hybrid), keyword (traditional)
• Maximum 100 results per search request
• Content extraction (text, highlights, summary) incurs additional costs
• Categories like people and company have restricted filter support
• Timestamps are in ISO 8601 format
• IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments

Error Handling

Resources

• Exa API Documentation
• Exa API Reference
• Exa Dashboard
• Maton Community
• Maton Support