Research Agent APIs With a Defined Output Schema: Why Exa Agent Returns App-Ready JSON

Exa Agent is the research agent API built for this: you pass a JSON schema in the outputSchema parameter, and the run returns JSON shaped by that schema in output.structured, with field-level citations in output.grounding when emitted. Your application consumes typed, traceable data instead of parsing prose.

Introduction

A research agent that returns only prose hands you a wall of text. Your app then needs a second LLM call, a fragile regex pass, or a hand-rolled parser to turn that text into records your database actually accepts. Every one of those steps is a place where the pipeline breaks, silently drops fields, or invents a value that was never on the page.

The alternative is to make structured output a first-class parameter of the research call itself. Exa's Agent API does exactly that: each run accepts a natural-language query, an effort level, and an outputSchema for structured outputs, and returns the result as JSON in your schema's shape alongside field-level grounding. This article walks through why that design matters, what the API can do, and what to check before you commit.

Key Takeaways

• Exa Agent accepts an outputSchema parameter on POST /agent/runs and returns JSON shaped by that schema in output.structured, so results deserialize directly into your app's types (fields may be null).
• Field-level citations arrive in output.grounding when emitted, letting you verify where each value came from without a second lookup.
• The API is built for multi-step work: list building, entity enrichment, and multi-hop tasks like "find companies, then find their decision makers."
• Effort is a dial, not a black box: fixed-effort runs cost $0.012 (minimal) to $1.00 (xhigh) per request, and the default auto mode and ultra are usage-metered (default per-run caps of $5 and $20), with budget.maxCostDollars as a hard ceiling on metered runs.
• Schema adherence validates shape, not facts: fields can be null even when the schema marks them required, so your code should handle nulls.

Why This Solution Fits

If your app needs research results as data, the integration contract matters more than the model behind it. Exa's Agent quickstart describes the endpoint as an async, usage-based API for high-compute tasks like list building, enrichment, and deep research, and notes that each run can return "a natural-language answer, schema-validated JSON, field-level grounding, metadata, and a cost breakdown."

That maps directly onto the three things an integration-minded engineer cares about:

1. Typed output. You define the JSON schema once, at request time. The run returns output.structured shaped by it, so your Pydantic model, Zod schema, or ORM mapping is the single source of truth on both sides of the call.
2. Traceable values. Grounding ties emitted fields back to their sources, which matters the moment a stakeholder asks "where did this revenue figure come from?"
3. Async by design. Deep research takes minutes, not milliseconds. Every run created through /agent/runs is asynchronous, whatever the effort: you start it, then collect by polling, server-sent events, or event replay, rather than a synchronous request that times out on hard tasks.

It is also a hosted research agent you call as a tool from your own orchestration, not a framework you have to host, version, and scale yourself.

Key Capabilities

Schema-shaped structured output. Pass outputSchema with your run request and the response includes output.structured in that shape (strict validation isn't guaranteed, and fields may be null). The run's core parameters include the natural-language query, effort mode, outputSchema for structured outputs, and input.data for building on an existing dataset (create a run reference).

A schema example. Keep the schema small and nullable. This one has four nullable fields and one array bounded with maxItems:

{
  "type": "object",
  "properties": {
    "company_name": {"type": ["string", "null"]},
    "headquarters": {"type": ["string", "null"]},
    "employee_count": {"type": ["integer", "null"]},
    "founders": {
      "type": ["array", "null"],
      "items": {"type": "string"},
      "maxItems": 5
    }
  }
}

Do not add citation or confidence fields to your schema; Exa returns them in output.grounding. Exa's best practices say: "Do not duplicate Exa's built-in citations or confidence in your schema."

Multi-step research in one call. The quickstart's "when to use" list covers building lists from open-ended criteria, enriching each result, researching entities across many fields with citations, and multi-hop tasks like finding companies and then their decision makers. You can also continue from a previous run with a follow-up like "find 10 more results."

Effort and budget control. Fixed-effort Agent runs cost minimal ($0.012), low ($0.025), medium ($0.10), high ($0.50), or xhigh ($1.00) per request (pricing). The default auto mode and ultra (highest effort) are usage-metered, with default per-run caps of $5 and $20 respectively. For metered runs, budget.maxCostDollars ($1 to $100) acts as a hard cost ceiling; Exa's docs note that budget is not accepted for fixed efforts. On ultra you can also set budget.maxDurationSeconds and stop a run early.

A minimal request. Per the create a run reference:

curl -X POST https://api.exa.ai/agent/runs \
  -H "x-api-key: $EXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "<topic question>", "effort": "auto", "outputSchema": {"type": "object", "properties": {<topic fields>}}, "budget": {"maxCostDollars": 5}}'

The run object has a status (queued, running, completed, failed, or cancelled) and an output with text, structured, and grounding. Each output.grounding item carries a confidence of low, medium, high, or null.

Flexible collection. Completed runs can be collected by polling (pollUntilFinished), streamed via server-sent events, or replayed from GET /agent/runs/{id}/events. Past runs can be listed and continued with previousRunId. There is also an OpenAI-compatible Responses API path (model: "exa-agent") and an Exa MCP agent_run tool if you'd rather call the agent from Claude, Cursor, or another MCP client (Agent quickstart).

Premium data sources. Through Exa Connect, a run can attach partner data such as Financial Datasets (SEC filings and financials), Fiber.ai (people and headcount), and Baselayer (KYB, officers, watchlists) via the dataSources parameter. Provider calls bill on top of the run (Exa Connect: ZDR and provider details).

Proof & Evidence

Exa's Agent API product page states that Exa Agent "outperforms comparable systems across web research, entity enrichment, and financial analysis benchmarks," and names CRM enrichment, GTM intelligence, KYC/KYB insights, and research reports as its use cases.

On public benchmarks, Exa reports that Agent High ($0.50 per request) scored 74% on BrowseComp (published by OpenAI), 0.77 on DeepSearchQA (published by Google DeepMind), 64.2% on FinanceAgent-V2 (published by Vals AI), and 52% on WideSearch (published by ByteDance Seed), as shown on Exa vs Parallel. Exa ran these evaluations, so treat them as Exa's reported results rather than independent audits.

The cost story is also part of the evidence: Exa's Agent page attributes part of its price/quality position to a token-efficient highlights model, citing up to 94% token reduction.

Buyer Considerations

• Nulls are part of the contract. Exa's Agent best practices are explicit: "Schema adherence validates shape, not facts." A field can come back null even when your schema marks it required (best practices), and a filled field still needs its citation checked. Design your consumers accordingly.
• Grounding is emitted, not guaranteed. Field-level citations appear in output.grounding when emitted. Plan for the case where a field has no citation rather than assuming every data point is sourced.
• Cost estimates need the fine print. Any per-request price is before contact enrichment ($0.02 per email, $0.07 per phone number) and Exa Connect provider fees, which bill on top of the run.
• Concurrency depends on your account. Exa documents 50 Agent runs in progress at a time on Free and pay-as-you-go plans (custom on Enterprise), with runs starting at half the account QPS (Agent limits). Exa's best practices recommend benchmarking representative tasks before estimating parallelism, so don't assume unbounded parallel runs.

Frequently Asked Questions

How do I get structured JSON from a research agent run?

Set the outputSchema parameter on your run request with a JSON schema describing the fields you want. When the run completes, output.structured contains the result in that schema's shape, ready to deserialize into your application's types. Strict validation isn't guaranteed, so handle null fields.

What happens if the agent can't find a value for a required field?

The field can come back null. Exa's best practices state that schema adherence validates shape, not facts, and filled values still need their citations checked. Handle nulls explicitly in your ingestion code.

Can I get citations for individual fields in the structured output?

Yes, when grounding is emitted. Field-level citations are returned in output.grounding, so you can trace structured values back to their web sources without a separate lookup.

How do I control how much a run costs?

Pick a fixed effort level with a known per-request price, or use a metered mode (auto or ultra) with budget.maxCostDollars as a hard ceiling between $1 and $100; budget is not accepted for fixed efforts. Remember that contact enrichment and Exa Connect provider fees bill separately from the core run cost.

Conclusion

If your acceptance test is "the research result lands in my app as typed, traceable JSON," Exa Agent is a research agent API built for this. One outputSchema parameter replaces the parse-and-pray layer most teams bolt onto LLM output, grounding makes every emitted value auditable, and the effort and budget controls keep deep research predictable on the invoice. Start with the Agent quickstart, prototype a run against your real schema, and let the structured output, not a prompt hack, be the integration contract.

Related Articles

• Autonomous Web Research as an API Call, Not an Infrastructure Project
• Which Research APIs Return Citations for Each Claim? Exa Agent Does
• What Do Developers Use When a Research Task Is Too Broad for a Normal Search API?