---
title: "Runs hooks"
description: "React hooks for runs — list, get, cancel, plus the high-level
{@link useExecuteRun} hook for executing any runnable entity
(agent, swarm, workflow) and tracking its status."
section: "Libraries"
group: "React hooks"
order: 442
---

## Usage

```tsx
import Aeontel from "@aeontel/sdk";
import { AeontelProvider, useListRuns } from "@aeontel/react";

const client = new Aeontel(import.meta.env.VITE_AEONTEL_API_KEY);

function App() {
  return (
    <AeontelProvider client={client}>
      <RunsList workspaceId="wsp_abc123" />
    </AeontelProvider>
  );
}

function RunsList({ workspaceId }: { workspaceId: string }) {
  const { data, isLoading } = useListRuns({ workspace_id: workspaceId });
  if (isLoading) return <p>Loading…</p>;
  return (
    <ul>
      {data?.data.map((r) => (
        <li key={r.id}>{r.status}</li>
      ))}
    </ul>
  );
}
```

## Hooks

### `useCancelRun` `composite`

Cancel a running run. Auto-invalidates run queries on success.

```ts
useCancelRun(options?: MutationOpts<Run, string>)
```

**Types:** [Run](/types/run)

```ts
const cancel = useCancelRun();
cancel.mutate("run_abc123");
```

### `useExecuteRun` `composite`

Execute any runnable entity (agent, swarm, workflow) and track its status.
Detects entity type from the ID prefix and routes to the correct API endpoint.

Status lifecycle: `idle` -> `pending` -> `running` -> `completed` | `failed`.
Polls the run status automatically when `poll` is true (default).

```ts
useExecuteRun<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput = unknown>(id: string, options: UseRunOptions = {})
```

```ts
const { execute, status, output, isRunning } = useExecuteRun("agt_abc123");
return (
  <>
    <button disabled={isRunning} onClick={() => execute({ prompt: "Hi" })}>Run</button>
    <div>{status}</div>
    {output && <pre>{JSON.stringify(output)}</pre>}
  </>
);
```

### `useListRuns` `query`

Fetch paginated list of runs. Supports workspace_id, status filters.

```ts
useListRuns(params?: Omit<ListRunsParams, | > & { filter?: RunFilter; orderBy?: RunOrderBy[]; } & RunShorthands, options?: QueryOpts<Page<Run>>)
```

**Types:** [ListRunsParams](/types/list-runs-params) · [RunFilter](/types/run-filter) · [RunOrderBy](/types/run-order-by) · [RunShorthands](/types/run-shorthands) · [Page](/types/page) · [Run](/types/run)

```ts
const { data } = useListRuns({ workspace_id: "wsp_abc123", status: "running" });
```

### `useRetrieveRun` `query`

Fetch a single run by ID.

```ts
useRetrieveRun(id: string, options?: QueryOpts<Run>)
```

**Types:** [Run](/types/run)

```ts
const { data: run } = useRetrieveRun("run_abc123");
```