> 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/agent_lookup.md).

# Exa Agent Lookup

Blocks for checking on and waiting for Exa Agent runs started elsewhere in a workflow.

## Exa Get Agent Run

### What it is

Get an Exa Agent run's status and, once it has finished, its answer, structured output, citations and cost

### How it works

This block reads one run with `GET /agent/runs/{id}` and returns its current status and, once it has finished, the answer, structured output, citations, usage and cost, plus the query and effort it was given. 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. A failed run does not fail the block; instead `failure_reason` explains why, read from the run or, failing that, from its stored events.

### Inputs

| Input   | Description             | Type | Required |
| ------- | ----------------------- | ---- | -------- |
| run\_id | ID of the Exa Agent run | str  | Yes      |

### Outputs

| Output          | Description                                                                                                                                                                                                | Type                  |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| error           | Error message if the operation failed                                                                                                                                                                      | str                   |
| run\_id         | Exa Agent run ID (starts with agent\_run\_)                                                                                                                                                                | str                   |
| status          | queued, running, completed, failed or cancelled                                                                                                                                                            | str                   |
| stop\_reason    | Why the run stopped: schema\_satisfied (done), budget\_reached, time\_limit\_reached, iteration\_limit\_reached, token\_limit\_reached, stopped (you stopped it; partial results kept), error or cancelled | str                   |
| text            | The natural-language answer                                                                                                                                                                                | str                   |
| structured      | JSON matching your output schema (empty without a schema). Fields Exa could not support with evidence may be null.                                                                                         | Any                   |
| grounding       | Citations for each output field, with confidence                                                                                                                                                           | List\[AgentGrounding] |
| usage           | Billed usage: compute units, searches, enrichments, data source calls                                                                                                                                      | Usage                 |
| cost\_total     | Total cost of the run in USD                                                                                                                                                                               | float                 |
| created\_at     | When the run was created (ISO 8601)                                                                                                                                                                        | str                   |
| completed\_at   | When the run finished (ISO 8601), empty while running                                                                                                                                                      | str                   |
| query           | The query the run was given                                                                                                                                                                                | str                   |
| effort          | The effort the run used                                                                                                                                                                                    | str                   |
| failure\_reason | Why the run failed (only when status is failed)                                                                                                                                                            | str                   |

### Possible use case

**Status Check**: Look up a run started with wait for completion off and branch on whether it is still queued, running or finished.

**Result Retrieval**: Fetch the answer and citations of a finished run by its ID, for example in a later execution of the workflow.

**Failure Handling**: Read `failure_reason` from a failed run and route the workflow to a retry or a notification.

***

## Exa Wait For Agent Run

### What it is

Wait for an Exa Agent run to finish, then return its answer, structured output, citations and cost

### How it works

This block polls `GET /agent/runs/{id}` until the run is completed, failed or cancelled, or the timeout (default 900 seconds, up to 10800) passes. The first re-check comes after `check_interval` seconds (default 5) and each gap after that grows by half, up to 30 seconds, so short runs return quickly and long ultra runs are not polled constantly. On timeout the block does not fail: it returns the run's current state with `timed_out` true, and the run keeps going on Exa.

When the run has finished, the block returns its total cost as reported by Exa. 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. A failed run does not fail the block; `failure_reason` explains why it failed.

### Inputs

| Input           | Description                                                                                                     | Type | Required |
| --------------- | --------------------------------------------------------------------------------------------------------------- | ---- | -------- |
| run\_id         | ID of the Exa Agent run to wait for                                                                             | str  | Yes      |
| timeout         | Longest time to wait in seconds (1-10800). Ultra runs usually take about 30 minutes and can take up to 3 hours. | int  | No       |
| check\_interval | Seconds before the first re-check (1-60); the gap then grows gradually up to 30 seconds                         | int  | No       |

### Outputs

| Output           | Description                                                                                                                                                                                                | Type                  |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| error            | Error message if the operation failed                                                                                                                                                                      | str                   |
| run\_id          | Exa Agent run ID (starts with agent\_run\_)                                                                                                                                                                | str                   |
| status           | queued, running, completed, failed or cancelled                                                                                                                                                            | str                   |
| stop\_reason     | Why the run stopped: schema\_satisfied (done), budget\_reached, time\_limit\_reached, iteration\_limit\_reached, token\_limit\_reached, stopped (you stopped it; partial results kept), error or cancelled | str                   |
| text             | The natural-language answer                                                                                                                                                                                | str                   |
| structured       | JSON matching your output schema (empty without a schema). Fields Exa could not support with evidence may be null.                                                                                         | Any                   |
| grounding        | Citations for each output field, with confidence                                                                                                                                                           | List\[AgentGrounding] |
| usage            | Billed usage: compute units, searches, enrichments, data source calls                                                                                                                                      | Usage                 |
| cost\_total      | Total cost of the run in USD                                                                                                                                                                               | float                 |
| created\_at      | When the run was created (ISO 8601)                                                                                                                                                                        | str                   |
| completed\_at    | When the run finished (ISO 8601), empty while running                                                                                                                                                      | str                   |
| timed\_out       | True if the run was still going when the timeout passed                                                                                                                                                    | bool                  |
| elapsed\_seconds | How long the block waited                                                                                                                                                                                  | float                 |
| failure\_reason  | Why the run failed (only when status is failed)                                                                                                                                                            | str                   |

### Possible use case

**Fire Then Collect**: Start several Exa Agent runs with wait for completion off, do other work, then wait for each run's result.

**Long Ultra Runs**: Wait up to 3 hours for an ultra-effort run without holding up the block that started it.

**Timeout Fallback**: Use `timed_out` to send a partial-progress notice or stop the run when it takes longer than the 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/agent_lookup.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.
