Skip to content
telipot
telipot
Join the waitlistSign in

Start web research from a question, returns a run id.

Create an asynchronous Agent run. By default, the API returns the run object immediately. Set `Accept: text/event-stream` to stream run lifecycle events until the run reaches a terminal status.

Job web.research.start

Your AI asks

checks the price first
telipot run exa.web.research.start \
  --input-json '{"query":"What is the capital of France?","effort":"minimal"}' \
  --quote

Price

$0.012–$20 / request
Priced· before it runs

exa.web.research.start

$0.012–$20 / requestYour plan

Whose account it uses

1The person asking
not needed
2Your company’s Exa plan
Selected identity for this example
3Our account
not used

What it sends

{
  "query": "What is the capital of France?",
  "effort": "minimal"
}

Your Exa login is added for you. Your AI never sees it.

What it costs

$0.012–$20

per request · billed per call

rate$0.012 to $20 per request, billed per call
sourcedocs · exa.ai/docs/admin/pricing · checked 2026-10-05
confidencedocumented
noteFixed efforts bill a flat price per request. auto and ultra bill actual usage (Agent Compute Units at $0.10, search calls at $0.005, email enrichment at $0.02 and phone enrichment at $0.07 each) up to a cap that defaults to $5 for auto and $20 for ultra; the rows hold those default caps. The budget and dataSources fields that would change them are not exposed here. The finished run reports its charge in costDollars.total.

Preview the price first. --quote runs nothing.

For developers · run it

Shell · runs the task on the named account

telipot run exa.web.research.start \
  --input-json '{"query":"What is the capital of France?","effort":"minimal"}'

query

string · required · at least 1

Natural-language question or instructions for the run.

effort

string · one of "minimal", "low", "medium", "high", "xhigh", "auto", "ultra" · default "auto"

Cost and reasoning effort preference. auto lets Exa choose and ultra is the highest-effort tier; both are metered by usage up to a cap. minimal, low, medium, high and xhigh bill a flat price per request, $0.012, $0.025, $0.10, $0.50 and $1.00.

systemPrompt

string

Additional instructions that guide the run, such as source preferences, novelty constraints or duplication constraints.

outputSchema

object

JSON Schema for validated structured output in output.structured. Fields unsupported by evidence may be returned as null. Supports draft-07, 2019-09 and 2020-12 via $schema.

input

object

Records to process and records or entities to exclude from the answer, as { data: [records to process or enrich], exclusion: [records or entities to avoid returning] }.

previousRunId

string · 1 to 200

Id of an earlier run to continue from, such as for a follow-up request like find 10 more results. Ids carry the agent_run_ prefix and use only letters, digits and _ . - and a colon.

id

string

Run id with the agent_run_ prefix

object

string

status

string

stopReason

string | null

Why the run stopped; null while it is queued or running

createdAt

string

completedAt

string | null

request

object | null

The request fields stored with the run

output

object

usage

object

costDollars

object

Full output schema · JSONNested fields and constraints

Output JSON Schema

{
  "type": "object",
  "required": [
    "id",
    "object",
    "status",
    "stopReason",
    "createdAt",
    "completedAt",
    "request",
    "output",
    "usage",
    "costDollars"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Run id with the agent_run_ prefix"
    },
    "object": {
      "type": "string",
      "const": "agent_run"
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "running",
        "completed",
        "failed",
        "cancelled"
      ]
    },
    "stopReason": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "schema_satisfied",
            "budget_reached",
            "time_limit_reached",
            "stopped",
            "error",
            "cancelled"
          ]
        },
        {
          "type": "null"
        }
      ],
      "description": "Why the run stopped; null while it is queued or running"
    },
    "createdAt": {
      "type": "string"
    },
    "completedAt": {
      "type": [
        "string",
        "null"
      ]
    },
    "request": {
      "type": [
        "object",
        "null"
      ],
      "description": "The request fields stored with the run"
    },
    "output": {
      "type": "object",
      "required": [
        "text",
        "structured",
        "grounding"
      ],
      "properties": {
        "text": {
          "type": "string",
          "description": "Natural-language answer or summary"
        },
        "structured": {
          "description": "JSON shaped by outputSchema; null when no schema was given"
        },
        "grounding": {
          "type": "array",
          "description": "Field-level citations",
          "items": {
            "type": "object",
            "required": [
              "field",
              "citations"
            ],
            "properties": {
              "field": {
                "type": "string"
              },
              "citations": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    },
                    "title": {
                      "type": "string"
                    }
                  }
                }
              },
              "confidence": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "low",
                      "medium",
                      "high"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          }
        }
      }
    },
    "usage": {
      "type": "object",
      "required": [
        "agentComputeUnits",
        "searches",
        "emails",
        "phoneNumbers"
      ],
      "properties": {
        "agentComputeUnits": {
          "type": "number"
        },
        "searches": {
          "type": "integer"
        },
        "emails": {
          "type": "integer"
        },
        "phoneNumbers": {
          "type": "integer"
        },
        "dataSources": {
          "type": "object"
        }
      }
    },
    "costDollars": {
      "type": "object",
      "required": [
        "total",
        "agentCompute",
        "search",
        "emails",
        "phoneNumbers"
      ],
      "properties": {
        "total": {
          "type": "number"
        },
        "agentCompute": {
          "type": "number"
        },
        "search": {
          "type": "number"
        },
        "emails": {
          "type": "number"
        },
        "phoneNumbers": {
          "type": "number"
        },
        "dataSources": {
          "type": "object"
        }
      }
    }
  }
}

A real answer

examples/exa.web.research.start.json

{
  "id": "agent_run_2064f73e278349d6a73f56733b4665ec",
  "object": "agent_run",
  "status": "running",
  "stopReason": null,
  "createdAt": "2026-10-05T17:44:44.142Z",
  "completedAt": null,
  "request": {},
  "output": {
    "text": "",
    "structured": null,
    "grounding": []
  },
  "usage": {
    "agentComputeUnits": 0,
    "searches": 3,
    "emails": 0,
    "phoneNumbers": 0
  },
  "costDollars": {
    "total": 0.012,
    "agentCompute": 0,
    "search": 0.012,
    "emails": 0,
    "phoneNumbers": 0
  }
}