> 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_manage.md).

# Exa Agent Manage

Blocks for listing, cancelling, stopping and deleting Exa Agent runs and reading their stored events.

## Exa Cancel Agent Run

### What it is

Cancel an Exa Agent run immediately. No results are kept; usage so far is still billed. To keep partial results of an ultra run, use 'Stop Exa Agent Run' instead.

### How it works

This block calls `POST /agent/runs/{id}/cancel`, which ends a queued or running run immediately and discards its results. It returns the run as Exa reports it after cancelling, including the usage the run built up before it was cancelled, which Exa bills to your own Exa account; the platform charges no credits, since the block only runs on your own Exa key. To keep what an ultra run has found so far, use 'Stop Exa Agent Run' instead.

### Inputs

| Input   | Description                       | Type | Required |
| ------- | --------------------------------- | ---- | -------- |
| run\_id | ID of the Exa Agent run to cancel | 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                   |

### Possible use case

**Cost Control**: Cancel a run that a workflow no longer needs, so it stops building up usage.

**Wrong Inputs**: Cancel a run started with a mistaken query or schema before it gets far.

**Workflow Abort**: Cancel outstanding runs when an earlier step of the workflow fails.

***

## Exa Delete Agent Run

### What it is

Permanently delete a stored Exa Agent run and its output. It can no longer be fetched or used as a previous run.

### How it works

This block calls `DELETE /agent/runs/{id}` to permanently remove a stored run and its output, and returns the run ID with `deleted` true once Exa accepts the delete, including an empty 204 response; only an explicit `deleted: false` from Exa reports false. A failed delete fails the block, and the delete is sent once, never retried. A deleted run can no longer be fetched or used as a previous run ID for a follow-up. Deleting cannot be undone.

### Inputs

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

### Outputs

| Output  | Description                           | Type |
| ------- | ------------------------------------- | ---- |
| error   | Error message if the operation failed | str  |
| run\_id | ID of the deleted run                 | str  |
| deleted | True when Exa deleted the run         | bool |

### Possible use case

**Data Hygiene**: Delete runs that processed sensitive input data once their results have been saved elsewhere.

**Retention Policy**: Remove old runs on a schedule to keep stored research within your retention rules.

**Clean Up Tests**: Delete runs created while building and testing a workflow.

***

## Exa List Agent Run Events

### What it is

List an Exa Agent run's stored events (created, started, completed, failed, cancelled, plus progress). Not available for Zero Data Retention teams.

### How it works

This block calls `GET /agent/runs/{id}/events` and returns one page of the run's stored events in the order Exa stored them, such as `agent_run.created`, `agent_run.started` and `agent_run.completed`, plus progress events. Use `limit` (1-100, default 20) and pass `next_cursor` back as `cursor` while `has_more` is true to read further pages. Exa stores no events for Zero Data Retention teams, so the block fails for them.

### Inputs

| Input   | Description                                                        | Type | Required |
| ------- | ------------------------------------------------------------------ | ---- | -------- |
| run\_id | ID of the Exa Agent run                                            | str  | Yes      |
| limit   | How many events to return (1-100)                                  | int  | No       |
| cursor  | Cursor from a previous call's next\_cursor, to fetch the next page | str  | No       |

### Outputs

| Output       | Description                           | Type                 |
| ------------ | ------------------------------------- | -------------------- |
| error        | Error message if the operation failed | str                  |
| events       | Events in the order Exa stored them   | List\[AgentRunEvent] |
| event        | Each event, one at a time             | Event                |
| has\_more    | Whether more events are available     | bool                 |
| next\_cursor | Pass as cursor to get the next page   | str                  |

### Possible use case

**Progress Tracking**: Show how far a long ultra run has got by reading its latest events.

**Debugging Failures**: Read the `agent_run.failed` event to see the error code and message behind a failed run.

**Audit Trail**: Record when each run was created, started and finished for reporting.

***

## Exa List Agent Runs

### What it is

List your Exa Agent runs, newest first, with paging

### How it works

This block calls `GET /agent/runs` and returns one page of your team's runs, newest first, both as a list and one at a time. Use `limit` (1-100, default 20) and pass `next_cursor` back as `cursor` while `has_more` is true to read further pages. Listing is free, and the list includes runs started by the legacy Research blocks. It needs your own Exa API key and fails with a clear message on the platform's shared Exa key, since every user of that key shares one Exa account and would see each other's runs.

### Inputs

| Input  | Description                                                        | Type | Required |
| ------ | ------------------------------------------------------------------ | ---- | -------- |
| limit  | How many runs to return (1-100)                                    | int  | No       |
| cursor | Cursor from a previous call's next\_cursor, to fetch the next page | str  | No       |

### Outputs

| Output       | Description                           | Type            |
| ------------ | ------------------------------------- | --------------- |
| error        | Error message if the operation failed | str             |
| runs         | Runs, newest first                    | List\[AgentRun] |
| run          | Each run, one at a time               | Run             |
| has\_more    | Whether more runs are available       | bool            |
| next\_cursor | Pass as cursor to get the next page   | str             |

### Possible use case

**Run Dashboard**: List recent runs with their status, effort and cost for a team overview.

**Find a Run**: Look up the ID of an earlier run to fetch its result or follow up on it.

**Spend Review**: Page through runs and add up `cost` to track Exa Agent spending.

***

## Exa Stop Agent Run

### What it is

Stop an Exa Agent run early and return the results gathered so far (stop reason 'stopped'). Exa currently supports this for ultra-effort runs only.

### How it works

This block calls `POST /agent/runs/{id}/stop`, which tells a running run to wrap up and keep the results gathered so far, with stop reason `stopped`. Exa currently supports this for ultra-effort runs only. The block returns the run as Exa reports it; if the run is still wrapping up, collect the final result with 'Wait for Exa Agent Run'. Exa bills the run to your own Exa account; the platform charges no credits, since the block only runs on your own Exa key.

### Inputs

| Input   | Description                             | Type | Required |
| ------- | --------------------------------------- | ---- | -------- |
| run\_id | ID of the running Exa Agent run to stop | 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                   |

### Possible use case

**Good Enough Results**: Stop an ultra run once it has found enough and keep its partial answer.

**Deadline Cut-Off**: Stop a long run when a workflow's own deadline arrives instead of losing the results.

**Budget Guard**: Stop an ultra run that is close to the spend you are willing to put into it.

***


---

# 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_manage.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.
