> For the complete documentation index, see [llms.txt](https://agpt.co/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://agpt.co/docs/integrations/block-integrations/research_queries.md).

# Exa Research Queries

Blocks for checking on and waiting for Exa research tasks, which now run on Exa Agent because Exa retired its Research API.

## Exa Get Research

### What it is

Get status and results of a research task. Legacy: now reads Exa Agent runs; use 'Get Exa Agent Run' for new workflows.

### How it works

Exa retired its Research API, so this block now reads the Exa Agent run with the given ID (`GET /agent/runs/{id}`) and returns it in the legacy research shape. Statuses map to pending (queued), running, completed, canceled (cancelled) and failed, and `model` is the legacy name for low, medium and high runs (`exa-research-fast`, `exa-research`, `exa-research-pro`) or the effort name for runs started with other efforts. Once the run has finished, it returns the total cost and the number of searches; Exa Agent reports no pages crawled or reasoning tokens, so `cost_pages` and `cost_reasoning_tokens` are always 0. `output_parsed` is only set when the run produced a JSON object, and for a failed run `error_message` gives Exa's reason.

The block only runs on your own Exa API key, so Exa bills the run to your own Exa account and the platform charges no credits. With include events on, it also reads up to 1,000 stored Exa Agent events (event, data and timestamp), which Exa does not keep for Zero Data Retention teams.

### Inputs

| Input           | Description                                                   | Type | Required |
| --------------- | ------------------------------------------------------------- | ---- | -------- |
| research\_id    | The ID of the research task to retrieve (an Exa Agent run ID) | str  | Yes      |
| include\_events | Include detailed event log of research operations             | bool | No       |

### Outputs

| Output                  | Description                                                                                     | Type                   |
| ----------------------- | ----------------------------------------------------------------------------------------------- | ---------------------- |
| error                   | Error message if the operation failed                                                           | str                    |
| research\_id            | The research task identifier                                                                    | str                    |
| status                  | Current status: pending, running, completed, canceled, or failed                                | str                    |
| instructions            | The original research instructions                                                              | str                    |
| model                   | The research model used (or the Exa Agent effort, for runs started outside the Research blocks) | str                    |
| created\_at             | When research was created (Unix timestamp in ms)                                                | int                    |
| finished\_at            | When research finished (Unix timestamp in ms, if completed/canceled/failed)                     | int                    |
| output\_content         | Research output as text (if completed)                                                          | str                    |
| output\_parsed          | Structured JSON output matching outputSchema (if provided and completed)                        | Dict\[str, Any]        |
| cost\_total             | Total cost in USD (if completed)                                                                | float                  |
| cost\_searches          | Number of searches performed (if completed)                                                     | int                    |
| cost\_pages             | Legacy: always 0, because Exa Agent does not report pages crawled                               | int                    |
| cost\_reasoning\_tokens | Legacy: always 0, because Exa Agent does not report reasoning tokens                            | int                    |
| error\_message          | Error message if research failed                                                                | str                    |
| events                  | Detailed event log (if include\_events was True)                                                | List\[Dict\[str, Any]] |

### Possible use case

**Status Monitoring**: Check progress of long-running research tasks that were started without waiting.

**Result Retrieval**: Fetch finished research results from tasks started earlier in your workflow.

**Cost Tracking**: Review the total cost and searches of finished research for budgeting.

***

## Exa Wait For Research

### What it is

Wait for a research task to complete with configurable timeout. Legacy: now waits on Exa Agent runs; use 'Wait for Exa Agent Run' for new workflows.

### How it works

Exa retired its Research API, so this block now polls the Exa Agent run with the given ID (`GET /agent/runs/{id}`) every `check_interval` seconds (default 10, fixed rather than growing) until it finishes or the timeout (default 600 seconds, up to 3600) passes. On timeout the block does not fail: it returns the last status with `timed_out` true and the run keeps going on Exa. Once the run finishes, the block returns the text answer, `output_parsed` (only when the run produced a JSON object) and the cost; `final_status` uses the legacy names pending, running, completed, canceled and failed.

### Inputs

| Input           | Description                                                   | Type | Required |
| --------------- | ------------------------------------------------------------- | ---- | -------- |
| research\_id    | The ID of the research task to wait for (an Exa Agent run ID) | str  | Yes      |
| timeout         | Maximum time to wait in seconds                               | int  | No       |
| check\_interval | Seconds between status checks                                 | int  | No       |

### Outputs

| Output          | Description                                                         | Type            |
| --------------- | ------------------------------------------------------------------- | --------------- |
| error           | Error message if the operation failed                               | str             |
| research\_id    | The research task identifier                                        | str             |
| final\_status   | Final status when polling stopped                                   | str             |
| output\_content | Research output as text (if completed)                              | str             |
| output\_parsed  | Structured JSON output (if outputSchema was provided and completed) | Dict\[str, Any] |
| cost\_total     | Total cost in USD                                                   | float           |
| elapsed\_time   | Total time waited in seconds                                        | float           |
| timed\_out      | Whether polling timed out before completion                         | bool            |

### Possible use case

**Sequential Workflows**: Make sure research finishes before dependent workflow steps run.

**Fire Then Collect**: Start research with wait for completion off, do other work, then wait for the result.

**Timeout Handling**: Use `timed_out` to handle research that takes longer than a time-sensitive workflow can wait.

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://agpt.co/docs/integrations/block-integrations/research_queries.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
