# exa.web.research.start

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.

Page: https://telipot.com/catalog/tasks/exa.web.research.start · Markdown: https://telipot.com/catalog/tasks/exa.web.research.start/md · JSON: https://telipot.com/catalog/tasks/exa.web.research.start/json

| Field | Value |
| --- | --- |
| provider | [Exa](https://telipot.com/catalog/providers/exa) `exa` |
| capability | [`web.research.start`](https://telipot.com/catalog/capabilities/web.research.start) |
| kind | data |
| tier | core |
| price | $0.012–$20 / request (Exa docs · 2026-10-05) |
| price note | Fixed 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. |
| identity | Your plan |
| auth | `api_key · in header as x-api-key` |
| scope | any_account |
| principal | organization |
| required_scopes | none |
| retention | standard |
| route | `POST https://api.exa.ai/agent/runs` |
| verification | Verified on 2026-10-05. We ran a real request and checked the answer. This is a spot check, not a success rate. |
| status | live |
| docs | https://exa.ai/docs/reference/agent-api/create-a-run |

## Preview the price · nothing runs

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

## Run it

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

```bash
curl https://api.telipot.com/v1/tasks/exa.web.research.start/run \
  -H "Authorization: Bearer $TELIPOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"What is the capital of France?","effort":"minimal"}'
```

## Input

| Field | In | Type | Required | Constraints | Note |
| --- | --- | --- | --- | --- | --- |
| `query` | body | string | yes | at least 1 | Natural-language question or instructions for the run. |
| `effort` | body | string | no | 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` | body | string | no |  | Additional instructions that guide the run, such as source preferences, novelty constraints or duplication constraints. |
| `outputSchema` | body | object | no |  | 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` | body | object | no |  | 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` | body | string | no | 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. |

## Input schema

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Natural-language question or instructions for the run.",
      "examples": [
        "Find five recently launched developer tools for evaluating AI agents."
      ],
      "minLength": 1
    },
    "effort": {
      "type": "string",
      "description": "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.",
      "enum": [
        "minimal",
        "low",
        "medium",
        "high",
        "xhigh",
        "auto",
        "ultra"
      ],
      "default": "auto"
    },
    "systemPrompt": {
      "type": "string",
      "description": "Additional instructions that guide the run, such as source preferences, novelty constraints or duplication constraints."
    },
    "outputSchema": {
      "type": "object",
      "description": "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": {
      "type": "object",
      "description": "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": {
      "type": "string",
      "description": "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.",
      "minLength": 1,
      "maxLength": 200
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}
```

## Output schema

```json
{
  "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"
        }
      }
    }
  }
}
```

## Example response

From `examples/exa.web.research.start.json`.

```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
  }
}
```