Agent Ultra

Agent Ultra is Exa Agent’s highest-effort mode. It runs longer and spends more compute than any other effort to return the most complete results. Use it for large list building, deep multi-source research, and criteria that are hard to verify, where completeness matters more than latency or cost. For a predictable price per request, use a fixed effort instead.

Agent Ultra is metered at the standard Agent usage rates, up to a default $20 per run. Runs that finish early cost less.

Run Agent Ultra

Set effort: "ultra" on an Agent run. The rest of the request works like any other run, including outputSchema, input.data, and streaming.

from exa_py import Exa

exa = Exa()

run = exa.agent.runs.create(
    query="Find all companies building browser automation tools in the United States.",
    effort="ultra",
)
run = exa.agent.runs.poll_until_finished(run.id, timeout_ms=3 * 60 * 60 * 1000)

print(run.stop_reason)
if run.output:
    print(run.output.text)

import Exa from "exa-js";

const exa = new Exa();

const run = await exa.agent.runs.create({
  query: "Find all companies building browser automation tools in the United States.",
  effort: "ultra"
});
const finished = await exa.agent.runs.pollUntilFinished(run.id, {
  timeoutMs: 3 * 60 * 60 * 1000
});

console.log(finished.stopReason);
console.log(finished.output?.text);

curl -s -X POST "https://api.exa.ai/agent/runs" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EXA_API_KEY" \
  -d '{
    "query": "Find all companies building browser automation tools in the United States.",
    "effort": "ultra"
  }'

Ultra runs typically complete complex tasks in about 30 minutes, but can take up to three hours for very challenging ones. By default, the SDK polling helpers time out after one hour, so use a longer timeout as shown above or stream events for extended runs.

Set a budget

Add budget to cap how much a run spends and how long it takes. Both fields are optional.

Field	Accepts	Default
`maxCostDollars`	$1 to $100	$20
`maxDurationSeconds`	300 to 10,800 (5 minutes to 3 hours)	None

{
  "query": "Find all companies building browser automation tools in the United States.",
  "effort": "ultra",
  "budget": {
    "maxCostDollars": 10,
    "maxDurationSeconds": 1800
  }
}

As a run approaches either limit, the agent stops starting new work and returns what it has found.

Stop a run early

Stop Agent Ultra run to end it now and keep what it has found. The run completes with stopReason: "stopped", and you are billed for usage up to the stop.

curl -s -X POST "https://api.exa.ai/agent/runs/$RUN_ID/stop" \
  -H "Authorization: Bearer $EXA_API_KEY"

Stop reasons

stopReason on a finished run says why it ended. Every reason except error and cancelled means the run completed and returned what it found.

`stopReason`	Meaning
`schema_satisfied`	The agent finished the task.
`budget_reached`	The run reached `budget.maxCostDollars`.
`time_limit_reached`	The run reached `budget.maxDurationSeconds`.
`stopped`	You stopped the run.
`error`	The run failed.
`cancelled`	The run was cancelled.

Limits and compatibility

Ultra-only controls

budget.maxDurationSeconds and stopping a run early work only with effort: "ultra". budget.maxCostDollars also works with auto.

OpenAI Responses API

On /responses, set reasoning.effort: "ultra" with stream: true or background: true.

Get Started

Search

Agent

Other APIs

SDKs

Integrations

Admin

Websets

Agent Ultra

Run Agent Ultra

Set a budget

Stop a run early

Stop reasons

Limits and compatibility

Next steps

Agent quickstart

Agent examples

​Run Agent Ultra

​Set a budget

​Stop a run early

​Stop reasons

​Limits and compatibility

​Next steps

Agent quickstart

Agent examples

Run Agent Ultra

Set a budget

Stop a run early

Stop reasons

Limits and compatibility

Next steps