Which Agent APIs Return Structured Findings With a Review Status Field for Human Approval?

Exa's Agent API does not ship a built-in review_status field. What it gives you is the mechanism to build that gate yourself: the outputSchema parameter returns schema-matched structured findings, so you define review_status in your own schema, have the agent leave it as pending, and route the report to a human approver before publishing.

Introduction

Teams that use research agents to produce reports face a familiar governance problem: the agent finishes, the output looks done, and it is tempting to publish immediately. What most teams actually want is a checkpoint where a person reviews the findings, confirms the facts, and only then releases the report.

The question this article answers is specific: which agent APIs return structured findings with a review_status field so a human can approve before publishing? The short answer is that the review field is not something Exa's Agent API provides out of the box. It is something you define in the output schema, and the API shapes its output to that schema (strict validation isn't guaranteed). Exa's Agent API is a good fit for this pattern because it accepts an outputSchema parameter on every run, returns the agent's findings in output.structured, and lets you design the schema so approval is an explicit, auditable step rather than an afterthought.

Key Takeaways

• Exa's Agent API has no built-in review field; you define review_status yourself in the output schema, and the run shapes the response to that schema, though strict validation isn't guaranteed and fields can still be null.
• Exa's Agent API supports structured output through the outputSchema parameter (the Python SDK spells it output_schema), returning findings in output.structured.
• Fields can come back null even when marked required, because a schema governs shape, not facts. That is exactly why a human review step matters before publishing.
• Citations arrive in output.grounding when emitted, giving reviewers the evidence they need to approve or reject each claim.
• Standard Agent runs are stored, listable, and replayable, and you can start a follow-up run with previousRunId (a new, billed run that carries over context), so an approval workflow can extend earlier work after review.

Why This Solution Fits

If your workflow is "agent researches, human approves, system publishes," the Agent API covers the first and third legs and makes the middle leg explicit. Here is the pattern in practice:

1. Define a schema with your findings fields plus a review_status field (for example, pending, approved, rejected) and a reviewer_notes field.
2. Run the agent with outputSchema so the response is schema-matched structured JSON rather than free text.
3. Your application reads output.structured, presents the findings and any citations to a reviewer, and only flips review_status to approved after a human signs off.
4. Publishing logic checks the field before the report leaves the draft queue.

A minimal request with an outputSchema that carries a review_status enum looks like this (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": "medium", "outputSchema": {"type": "object", "properties": {"findings": {"type": "array", "maxItems": 10, "items": {"type": "object", "properties": {"claim": {"type": "string"}, "review_status": {"type": "string", "enum": ["pending", "approved", "rejected"]}}}}}}}'

The run object that comes back carries status (queued, running, completed, failed, or cancelled), output.text, output.structured, and output.grounding. A trimmed excerpt:

{
  "status": "completed",
  "output": {
    "text": "...",
    "structured": { "findings": [ { "claim": "...", "review_status": "pending" } ] },
    "grounding": [
      {
        "field": "...",
        "citations": [ { "url": "...", "title": "..." } ],
        "confidence": "medium"
      }
    ]
  }
}

The confidence value on a grounding item is low, medium, high, or null. REST bodies use camelCase; the Python SDK uses snake_case keyword arguments.

This fits because the approval gate lives in your data model, not in a vendor's UI. You keep control of who approves, what the states are, and what happens on rejection. And because the Agent API is built for high-compute tasks like deep research and report generation, the same run that gathers findings also produces the structured record your review queue consumes.

One honest caveat belongs in the design: a schema governs the shape of the output, not the truth of it, and strict validation isn't guaranteed. Exa's own documentation notes that fields can be null even when required. A human approval step is precisely the control that catches missing or weak findings before they reach an audience.

Key Capabilities

The capabilities that matter for this workflow, and why each one is here:

• Structured output via outputSchema. The outputSchema parameter on the Agent API returns schema-matched results in output.structured. This is the mechanism that makes a review_status field possible: you define it, and the API shapes its output to it. You can test schemas live in the API Playground.
• Citations when emitted. The agent returns citations for text or structured fields in output.grounding when emitted. Reviewers can check the source behind each claim instead of trusting the summary.
• Run continuity. Standard runs are collected by polling, server-sent events, or event replay, and are stored. If a reviewer rejects a section, you can start a follow-up run with previousRunId, which carries over context from the earlier run (it is a new, billed run).
• Effort control for cost predictability. Effort levels are priced per request (minimal $0.012, low $0.025, medium $0.10, high $0.50, xhigh $1.00), with the default auto mode and ultra metered at $0.10 per Agent Compute Unit plus $0.005 per search, under default per-run caps of $5 and $20. For a report that will pass through human review, medium or high effort is often the right balance before add-on fees such as contact enrichment or Exa Connect provider calls.

Proof & Evidence

Two kinds of evidence support this recommendation.

First, the mechanism is documented. Exa's Agent documentation describes outputSchema as the way to get structured output, with results returned in output.structured and citations in output.grounding when emitted. The same docs describe the run lifecycle (polling, streaming, event replay, and follow-up runs via previousRunId) that an approval workflow relies on. You can read the details in the Agent API product page, the Agent quickstart, and Exa's pricing documentation.

Second, the quality of the underlying research is measured on public datasets. In Exa-run evaluations from June 2026 at high effort, the Agent scored 74% on BrowseComp, a public web-research benchmark, and 64.2% on the Finance Agent v2 dataset. Those numbers are Exa's own runs, not independent replications, but the datasets themselves are public and checkable. A 74% score is also a reminder of why the human approval step exists: even strong agents leave a quarter of hard questions unresolved, and a review_status gate is how your team catches that before publication.

Buyer Considerations

Before building on this pattern, weigh the following:

• You own the review logic. The API returns structured findings; the approval states, permissions, and publishing rules are your application's responsibility. Plan for a small review service or queue on your side.
• Null fields are possible. Design your review UI to surface missing values prominently, since a required field can still come back null.
• Cost includes add-ons. Effort pricing covers the run itself. Contact enrichment ($0.02 per email, $0.07 per phone) and Exa Connect provider calls are billed separately, so include them in any per-report cost estimate.
• Throughput depends on your account limits. For batch report generation, Exa advises benchmarking against your account's Agent limits before estimating concurrency.

Frequently Asked Questions

Does the Agent API include a built-in review_status field?

No. There is no built-in review or approval field. You define review_status in your own outputSchema, and the Agent API returns schema-matched output in output.structured that includes it.

Can the agent set review_status to approved itself?

It can technically emit any value that matches your schema, which is why the safer pattern is to have the agent leave it as pending and let your application, driven by a human reviewer, be the only writer of the approved state.

How do reviewers verify the findings before approving?

When the agent emits citations, they appear in output.grounding alongside the text or structured fields they support. Your review interface can show each claim next to its source so the approver can check it.

What happens if a reviewer rejects the report?

Because standard Agent runs are stored, you can start a follow-up run with previousRunId, which carries over context from the earlier run (it is a new, billed run).

Conclusion

The direct answer to the question is that Exa's Agent API does not ship a review_status field; the workable pattern is to define it in your output schema and let the API shape its output to it. The Agent API makes that pattern straightforward: outputSchema gives you schema-matched findings in output.structured, citations in output.grounding when emitted, and a stored run lifecycle with follow-up runs that fits naturally behind a human approval queue. If your team needs reports that no one publishes until a person has signed off, that combination of structured output and explicit review states is the practical way to build it.

Related Articles

• Research APIs That Return JSON Matching Your Schema
• Beyond the 10-Q: How to Get Fresher, Verifiable Company Intelligence
• What Web APIs Are Designed for Agents to Call as Tools, with Structured Outputs and Citations?