​

Agent API Reference

​

Canonical Docs Links

• Agent API guide: https://exa.ai/docs/reference/agent-api-guide
• Create a run: https://exa.ai/docs/reference/agent-api/create-a-run
• Get a run: https://exa.ai/docs/reference/agent-api/get-a-run
• List runs: https://exa.ai/docs/reference/agent-api/list-runs
• List run events: https://exa.ai/docs/reference/agent-api/list-run-events
• Cancel a run: https://exa.ai/docs/reference/agent-api/cancel-a-run
• Delete a run: https://exa.ai/docs/reference/agent-api/delete-a-run
• Exa Connect overview: https://exa.ai/docs/reference/agent-api/connect/overview
• Connect combining providers: https://exa.ai/docs/reference/agent-api/connect/combining-providers
• Connect providers: https://exa.ai/docs/reference/agent-api/connect/fiber, https://exa.ai/docs/reference/agent-api/connect/similarweb, https://exa.ai/docs/reference/agent-api/connect/baselayer, https://exa.ai/docs/reference/agent-api/connect/affiliatecom, https://exa.ai/docs/reference/agent-api/connect/particle, https://exa.ai/docs/reference/agent-api/connect/financialdatasets, https://exa.ai/docs/reference/agent-api/connect/jinko, https://exa.ai/docs/reference/agent-api/connect/additional-partners

​

Overview

• build lists from open-ended criteria, then enrich each result
• research entities across many fields with citations
• run multi-hop tasks such as “find companies, then find decision makers”
• produce structured JSON from a long-running web research task
• continue from a previous run with a follow-up request

​

Request Shape

POST https://api.exa.ai/agent/runs
{
  "query": "Find engineering leaders at AI infrastructure companies that raised a Series A or B in the last 6 months.",
  "effort": "auto",
  "outputSchema": {
    "type": "object",
    "properties": {
      "people": {
        "type": "array",
        "maxItems": 10,
        "items": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "job_title": { "type": "string" },
            "linkedin_url": { "type": "string", "format": "uri" }
          },
          "required": ["name", "job_title", "linkedin_url"]
        }
      }
    },
    "required": ["people"]
  }
}

​

Core Fields

​

Lifecycle

1. Create a run with POST /agent/runs.
2. Save the returned id, which has the agent_run_ prefix.
3. Wait for the run to reach a terminal status (completed, failed, or cancelled), either by:
   • Polling: GET /agent/runs/{id} until status is terminal, or
   • SSE events: Accept: text/event-stream on create, or replay from GET /agent/runs/{id}/events with Last-Event-ID. The two are equivalent; pick one per integration.
4. Check how the run ended: on completed, read output; on failed or cancelled, surface the error to the caller or UI. Only completed carries results — reading output without checking the status makes failures look like empty successes, and a hand-rolled wait loop that exits only on completed never finishes for failed runs.

• output.text: natural-language answer or summary
• output.structured: validated JSON matching outputSchema, when provided
• output.grounding: citations for text or structured fields
• costDollars: run cost breakdown

​

Polling

RUN_ID="agent_run_01j..."

while true; do
  RUN_JSON="$(curl -s "https://api.exa.ai/agent/runs/$RUN_ID" \
    -H "x-api-key: $EXA_API_KEY")"

  STATUS="$(echo "$RUN_JSON" | jq -r '.status')"
  echo "status=$STATUS"

  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] || [ "$STATUS" = "cancelled" ]; then
    echo "$RUN_JSON" | jq .
    break
  fi

  sleep 4
done

• Python: exa.agent.runs.poll_until_finished(run_id, poll_interval=4000)
• TypeScript: exa.agent.runs.pollUntilFinished(runId, { pollInterval: 4000 })

​

Streaming and Events

curl -N "https://api.exa.ai/agent/runs/agent_run_01j.../events" \
  -H "Accept: text/event-stream" \
  -H "Last-Event-ID: 1" \
  -H "x-api-key: $EXA_API_KEY"

​

Follow-up Runs

{
  "query": "Narrow that list to companies hiring in San Francisco.",
  "previousRunId": "agent_run_01j..."
}

​

Connect Data Sources

{
  "dataSources": [
    { "provider": "similarweb" },
    { "provider": "fiber_ai" }
  ]
}

• Overview: https://exa.ai/docs/reference/agent-api/connect/overview
• Combining providers: https://exa.ai/docs/reference/agent-api/connect/combining-providers
• Provider pages: fiber, similarweb, baselayer, affiliatecom, particle, financialdatasets, jinko, and additional-partners under /reference/agent-api/connect/

​

SDK Naming

from exa_py import Exa

exa = Exa()
run = exa.agent.runs.create(
    query="Find five recently launched developer tools for evaluating AI agents.",
    effort="auto",
    output_schema={
        "type": "object",
        "properties": {
            "tools": {
                "type": "array",
                "maxItems": 5,
                "items": {"type": "object"},
            }
        },
        "required": ["tools"],
    },
)
finished = exa.agent.runs.poll_until_finished(run.id, poll_interval=4000)
if finished.status == "completed":
    print(finished.output.structured)
    print(finished.output.grounding)
else:
    print(finished.status, getattr(finished, "error", None))

import Exa from "exa-js";

const exa = new Exa();
const run = await exa.agent.runs.create({
  query: "Find five recently launched developer tools for evaluating AI agents.",
  effort: "auto",
  outputSchema: {
    type: "object",
    properties: {
      tools: {
        type: "array",
        maxItems: 5,
        items: { type: "object" }
      }
    },
    required: ["tools"]
  }
});
const finished = await exa.agent.runs.pollUntilFinished(run.id, { pollInterval: 4000 });
if (finished.status === "completed") {
  console.log(finished.output?.structured);
  console.log(finished.output?.grounding);
} else {
  console.log(finished.status, finished.error);
}

​

Critical Pitfalls

• Do not stop at create. Wait for a terminal status via polling or SSE events, then check how the run ended before reading output; only completed carries results.
• Always set effort explicitly.
• When building an app, expose output.grounding (citations) where relevant in a product’s interface.
• Do not use /agent for simple low-latency search; prefer /search.
• Do not leave unbounded arrays in outputSchema when enrichment cost or result size matters.
• Use input.data for known rows to enrich; do not paste huge row sets into query.
• Use input.exclusion for records that should not be surfaced again.
• previousRunId must reference a completed run.
• budget.maxCostDollars is compatibility-only in the current spec; do not rely on it for enforcement.