Python SDK Specification

from exa_py import Exa

exa = Exa()  # Reads EXA_API_KEY from environment
# or explicitly: exa = Exa(api_key="your-api-key")

# Basic search
result = exa.search(
  "hottest AI startups",
  num_results=2
)

# Deep search with query variations
deep_result = exa.search(
  "blog post about AI",
  type="deep",
  additional_queries=["AI blogpost", "machine learning blogs"],
  num_results=5
)

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

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

{
  "results": [
    {
      "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
    },
    {
      "title": "Play The best Online Games",
      "id": "https://www.minigames.com/",
      "url": "https://www.minigames.com/",
      "publishedDate": "2000-01-01",
      "author": null
    }
  ],
  "requestId": "08fdc6f20e9f3ea87f860af3f6ccc30f"
}

# Get contents for a single URL
contents = exa.get_contents("https://example.com/article")

# Get contents for multiple URLs
contents = exa.get_contents([
    "https://example.com/article1",
    "https://example.com/article2"
])

{
  "results": [
    {
      "url": "https://example.com/article",
      "id": "https://example.com/article",
      "title": "Example Article",
      "text": "The full text content of the article..."
    }
  ]
}

response = exa.answer("What is the capital of France?")

print(response.answer)       # e.g. "Paris"
print(response.citations)    # list of citations used

# If you want the full text of the citations in the response:
response_with_text = exa.answer(
    "What is the capital of France?",
    text=True
)
print(response_with_text.citations[0].text)  # Full page text

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

stream = exa.stream_answer("What is the capital of France?", text=True)

for chunk in stream:
    if chunk.content:
        print("Partial answer:", chunk.content)
    if chunk.citations:
        for citation in chunk.citations:
            print("Citation found:", citation.url)

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

from exa_py import Exa
import os

exa = Exa(os.environ["EXA_API_KEY"])

# Create a simple research task
instructions = "What is the latest valuation of SpaceX?"
schema = {
    "type": "object",
    "properties": {
        "valuation": {"type": "string"},
        "date": {"type": "string"},
        "source": {"type": "string"}
    }
}

task = exa.research.create(
    instructions=instructions,
    output_schema=schema
)

print(f"Task created with ID: {task.research_id}")

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

# Get a research task by ID
task_id = "your-task-id-here"
task = exa.research.get(task_id)

print(f"Task status: {task.status}")
if task.status == "completed":
    print(f"Results: {task.output}")

{
  "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"
      }
    }
  },
  "output": {
    "valuation": "$350 billion",
    "date": "December 2024",
    "source": "Financial Times"
  }
}

# Create and poll a task until completion
task = exa.research.create(
    instructions="Get information about Paris, France",
    output_schema={
        "type": "object",
        "properties": {
            "name": {"type": "string"},
            "population": {"type": "string"},
            "founded_date": {"type": "string"}
        }
    }
)

# Poll until completion
result = exa.research.poll_until_finished(task.research_id)
print(f"Research complete: {result.output}")

# List all research tasks
response = exa.research.list()
print(f"Found {len(response.data)} tasks")

# List with pagination
response = exa.research.list(limit=10)
if response.has_more:
    next_page = exa.research.list(cursor=response.next_cursor)

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