---
ref: tool:exa/run-agent
name: Run a list-building and research agent
company: company:exa
workflows: []
access: [mcp, api]
tags: [capability:build-audience, category:web-search, has:api, has:mcp]
docs: https://exa.ai/docs/reference/agent-api/create-a-run
updated: 2026-09-27
---

# Run a list-building and research agent

Starts an Exa Agent run that searches and reads the web to build lists, enrich records you pass in or research a question, and returns cited findings with optional schema-validated JSON.

Describe the data you want in `query`. Pass `outputSchema` for JSON in
`output.structured`, `input.data` for rows to enrich, and `effort` to trade
cost for completeness; `budget` caps what an `auto` or `ultra` run can spend.
Runs are asynchronous: the API returns the run to poll with
`GET /agent/runs/{id}`, and the MCP tool reports `status: "running"` with an
`id` to pass back as `runId`. `agent_run` needs OAuth or an API key.

## Set up

Use the first option your agent supports.

### MCP (official, remote)

Add this server to your agent's MCP settings, then sign in when asked.

```json
{ "mcpServers": { "exa": { "url": "https://mcp.exa.ai/mcp?login" } } }
```

Call the MCP tool `agent_run`.

Server URL: https://mcp.exa.ai/mcp?login

### API (official)

- Base URL: https://api.exa.ai
- Endpoint: `POST /agent/runs`
- Auth: send the header `Authorization: Bearer $EXA_API_KEY`
- Get a key: https://dashboard.exa.ai/api-keys
- Docs: https://exa.ai/docs/get-started/quickstart

Before doing anything else, make one read-only call to confirm access.

## Rules

- Ask the user before anything that sends messages, costs money, or changes data.
- Never print API keys.