Web APIs Built for Agent Tool Calls: Structured Outputs and Citations with Exa

Exa's Search API is a web API designed to be called as a tool by AI agents: pass an outputSchema parameter and it returns a schema-matched result in output.content, with field-level citations in output.grounding. It is a plain REST endpoint with official SDKs and an MCP server, so an agent can call it like any other tool.

Introduction

When you hand an agent a web API as a tool, two things decide whether the output is usable. First, the response has to arrive in a shape your code can act on, without the model parsing prose on every call. Second, the facts in it need to be traceable back to the page they came from, so you can audit what the agent actually read.

Exa is a web search and real-time web data API built for AI agents. Its Search API is the surface built for this job: a single POST request that searches the live web and returns ranked links with token-efficient highlights and, with outputSchema, also a synthesized, schema-matched answer with citations. This article explains how those two mechanisms work, what they cost, and what to check before wiring them into an agent.

Key Takeaways

• The outputSchema parameter (spelled output_schema in the Python SDK) makes the Search API return a schema-matched value in output.content alongside the ranked results.
• Citations come back in output.grounding, with field-level citations and a confidence value, so each claim in the structured answer points to the page it came from.
• Latency is tiered by search type: lite at about 450 ms and the auto default at about 1 second, per Exa's Search quickstart.
• outputSchema is not supported on lite (it returns a 400); use auto or a Deep type for structured outputs, and expect the synthesis step to add time to the call.
• For multi-step research jobs that one search call cannot cover, Exa's Agent API runs the task asynchronously and returns output.structured with citations in output.grounding when emitted.

Why This Solution Fits

An agent tool needs three properties: a predictable request and response contract, output the calling code can consume without another parsing pass, and evidence you can audit after the fact. The Search API is designed around exactly that contract.

The base call is a REST POST to the /search endpoint with a bearer key. Without outputSchema, you get ranked results with highlights, the specific passages that answer the query, which keeps token use low inside an agent loop. With outputSchema, the API also generates a value that matches your schema and returns it in output.content, with field-level citations and a confidence value in output.grounding. Either way, the response is JSON your tool handler can consume directly.

That combination matters because agents fail in two distinct ways: they misparse unstructured text, and they state facts nobody can check. Schema-matched output addresses the first, and grounding addresses the second.

Key Capabilities

Structured outputs via outputSchema. Pass a JSON schema and the API returns a value that matches it in output.content. Schemas are capped at a nesting depth of 2 and 10 total properties, and you should not add source, citation, or confidence fields to the schema yourself; grounding comes back separately. Note that a schema governs shape, not facts, so your tool handler should validate values, not just structure. outputSchema works with every search type except lite, which rejects it with a 400 error.

Citations in output.grounding. When outputSchema is used, the response includes field-level citations plus a confidence value, so each generated field points to the web page it was drawn from. You can test the whole mechanism live in Exa's API Playground before writing any code.

Latency and pricing you can plan around. The lite type returns in about 450 ms at $4 per 1,000 requests, and the auto default returns in about 1 second at $7 per 1,000, each including up to 10 results, per Exa's pricing docs. Requesting text and highlights is included in the base price; the only extra charges are results above 10 ($1 per 1,000 results) and AI page summaries ($1 per 1,000 pages). Adding outputSchema adds a synthesis step to the call, so budget extra time for structured responses.

Freshness and scoping controls. contents.maxAgeHours limits how old cached page content may be, from -1 to 720 hours (0 requests a fresh fetch, -1 uses the cache only, and when it's omitted, cached content is used where available and uncached pages are fetched live; lite rejects it), and includeDomains accepts path prefixes such as example.com/docs, so you can scope a tool call to sources you trust. For coding agents, Exa also hosts an MCP server at mcp.exa.ai/mcp that exposes the same search as an MCP tool.

A runnable example of the structured-output call:

curl -X POST "https://api.exa.ai/search" \
  -H "Authorization: Bearer $EXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "current Series B funding for AI infrastructure startups",
    "type": "auto",
    "outputSchema": {
      "type": "object",
      "properties": {
        "company_name": {"type": "string"},
        "funding_stage": {"type": "string"}
      },
      "required": ["company_name", "funding_stage"]
    }
  }'

The response returns the generated value in output.content and the per-field citations in output.grounding.

Proof & Evidence

The mechanisms above are documented, not inferred. Exa's Search API reference specifies the outputSchema parameter and the output.content and output.grounding response fields, and the Search quickstart publishes the typical latency figures for each search type, from about 450 ms for lite to about 1 second for the auto default.

For retrieval quality on code and documentation queries, Exa open-sources its WebCode evaluations in its own repository at github.com/exa-labs/benchmarks. The repo is Exa's own, not an independent audit, but the eval code and results are inspectable if you want to check how the underlying retrieval performs on developer sources.

On cost, the pricing docs list the per-type rates directly: $4 per 1,000 requests for lite and $7 for auto, each including up to 10 results, with results above 10 billed at $1 per 1,000. Exa's free tier includes $10 in credits every month (up to 2,500 Lite searches), plus a one-time $10 onboarding bonus, with no payment method required, so you can prototype the schema-and-grounding contract before committing to a paid plan (Exa's pricing page).

Buyer Considerations

• Match the search type to the call site. Use lite for latency-sensitive steps in an agent loop, and auto when you need structured outputs or parameters lite does not support. Deep research types exist, but for long-running, multi-hop jobs Exa's docs point to the Agent API instead.
• Validate values. Build your tool handler to check that values are present and grounded, not just that the JSON matches the schema.
• Watch the schema limits. Nesting depth of 2 and 10 total properties cap how complex a schema you can pass, so flatten the fields your agent actually needs.
• Budget the synthesis step. outputSchema adds a synthesis pass on top of the search latency, which is material if you are calling it in a tight loop; use plain highlights where a passage is enough.
• Start free. The free tier's monthly credits require no payment method, which is enough to test the schema-and-grounding contract against your own queries.

Frequently Asked Questions

Does the Search API return structured outputs?

Yes. Pass the outputSchema parameter (spelled output_schema in the Python SDK) and the API returns a schema-matched value in output.content alongside the ranked results. Schemas are limited to a nesting depth of 2 and 10 total properties, and outputSchema works with every search type except lite.

Where do the citations come from?

When outputSchema is used, the response includes output.grounding with field-level citations and a confidence value. Each citation points to the web page the generated field was drawn from, so you can audit any claim in the answer.

How fast is a structured-output search?

The search itself follows the normal latency tiers: about 450 ms for lite and about 1 second for the auto default. Structured outputs aren't available on lite, and the outputSchema synthesis step adds additional time on top of the search.

What does it cost?

lite costs $4 per 1,000 requests and auto costs $7 per 1,000, each including up to 10 results, with results above 10 at $1 per 1,000. Exa's free tier includes $10 in credits every month with no payment method required, so you can test the API before committing to a paid plan.

Conclusion

For agents that need web data as a tool, Exa's Search API covers the full contract: a REST endpoint with official SDKs, outputSchema for schema-matched structured results, and output.grounding for field-level citations with a confidence value. Latency tiers from about 450 ms to about 1 second let you pick the right speed for each step of an agent loop, and the free tier's monthly credits make it cheap to test the contract against your own schemas before you commit.

Related Articles

• Beyond the 10-Q: How to Get Fresher, Verifiable Company Intelligence
• Web Search APIs With First-Class TypeScript and Python SDKs and Typed Responses
• What Web APIs Are Designed for Agents to Call as Tools, with Structured Outputs and Citations?