# useThreads

> React hook for listing, managing, and syncing conversation threads with useThreads. Rename, archive, delete, and paginate threads with realtime updates via WebSocket.

<OpsPlatformCTA
  variant="card"
  title="useThreads needs a CopilotKit Intelligence project"
  body="Create a cloud-hosted project or connect a self-hosted deployment to start syncing threads."
  ctaLabel="Create a free account"
  surface="docs_reference_use_threads"
/>

## Overview [#overview]

Intelligence’s [AG-UI streams](/AG-UI-Streams) provide the event history and delivery behind these conversations. For the event replay model, see [AG-UI Streams & Framework Threads](/intelligence/threads-explained). Use `useThreads` to manage the conversation list, then pass the selected `threadId` to your chat. Your framework keeps its own conversation and model-context management.

`useThreads` is a React hook for managing conversation threads in CopilotKit Intelligence. It fetches the thread list for a given agent, keeps it synchronized in realtime via WebSocket, and exposes mutation methods for renaming, archiving, and deleting threads.

Threads are sorted by the most recent run (`lastRunAt`), then by `updatedAt` for threads that have not run. The hook supports cursor-based pagination when a `limit` is provided.

For a full thread sidebar, see [Headless Threads](/headless-threads).

`useThreads` only activates when the connected runtime advertises compatible REST thread endpoints. Cloud-hosted Intelligence provides those endpoints for thread metadata and realtime updates. A self-managed runner, such as `AgentRunner`, `SqliteAgentRunner`, or a custom runner, can persist and replay chat history. It does not provide the thread list, the thread mutations, or the realtime updates that `useThreads` needs.

## Signature [#signature]

```tsx
import { useThreads } from "@copilotkit/react-core/v2";

function useThreads(input: UseThreadsInput): UseThreadsResult
```

## Parameters [#parameters]

<PropertyReference name="input" type="UseThreadsInput">
  Configuration object for the hook.

  <PropertyReference name="agentId" type="string" required>
    The ID of the agent whose threads to list. Must match an agent configured in your runtime.
  </PropertyReference>

  <PropertyReference name="includeArchived" type="boolean" default="false">
    Whether to include archived threads in the list.
  </PropertyReference>

  <PropertyReference name="limit" type="number" default="undefined">
    Maximum number of threads to fetch per page. When set, enables cursor-based pagination via `fetchMoreThreads()` and `hasMoreThreads`.
  </PropertyReference>
</PropertyReference>

## Return Value [#return-value]

<PropertyReference name="result" type="UseThreadsResult">

  ### State [#state]

  <PropertyReference name="threads" type="Thread[]">
    Array of threads for the current user and agent, sorted by the most recent run (`lastRunAt`), then by `updatedAt` for threads that have not run. Each `Thread` contains:
    - `id: string`: unique thread identifier
    - `agentId: string`: the agent this thread belongs to
    - `name: string | null`: thread name (set automatically when the first run creates the thread, or set manually via `renameThread`)
    - `archived: boolean`: whether the thread is archived
    - `createdAt: string`: ISO 8601 timestamp
    - `updatedAt: string`: ISO 8601 timestamp
    - `lastRunAt?: string`: ISO 8601 timestamp of the most recent run on this thread. Only present when the thread has had at least one run. Useful for surfacing "last activity" timing distinct from `updatedAt` (which also bumps on metadata changes like rename/archive).
  </PropertyReference>

  <PropertyReference name="isLoading" type="boolean">
    `true` while the initial thread list is being fetched.
  </PropertyReference>

  <PropertyReference name="error" type="Error | null">
    The most recent error from fetching or mutating threads, or `null` if no error has occurred.
  </PropertyReference>

  <PropertyReference name="hasMoreThreads" type="boolean">
    `true` when more threads are available beyond the current page. Only meaningful when `limit` is set.
  </PropertyReference>

  <PropertyReference name="isFetchingMoreThreads" type="boolean">
    `true` while additional threads are being fetched.
  </PropertyReference>

  ### Methods [#methods]

  <PropertyReference name="fetchMoreThreads" type="() => void">
    Fetch the next page of threads. No-op if `hasMoreThreads` is `false` or a fetch is already in progress.
  </PropertyReference>

  <PropertyReference name="renameThread" type="(threadId: string, name: string) => Promise<void>">
    Rename a thread. The promise resolves when the server confirms the operation, or rejects with an `Error` on failure.
  </PropertyReference>

  <PropertyReference name="archiveThread" type="(threadId: string) => Promise<void>">
    Soft-delete a thread. The thread remains in the database with `archived: true` but is excluded from the list unless `includeArchived` is `true`. Restore an archived thread with `unarchiveThread(threadId)`. The promise resolves on server confirmation, or rejects with an `Error` on failure. There is no built-in confirmation dialog, so implement your own if needed.
  </PropertyReference>

  <PropertyReference name="unarchiveThread" type="(threadId: string) => Promise<void>">
    Restore an archived thread. The thread appears in the default list again. The promise resolves on server confirmation, or rejects with an `Error` on failure.
  </PropertyReference>

  <PropertyReference name="deleteThread" type="(threadId: string) => Promise<void>">
    Permanently and irreversibly delete a thread. The thread record is removed from the database entirely. The promise resolves on server confirmation, or rejects with an `Error` on failure. There is no built-in confirmation dialog, so implement your own if needed.
  </PropertyReference>
</PropertyReference>

## Usage [#usage]

```tsx title="ThreadList.tsx"
import { useThreads } from "@copilotkit/react-core/v2"; // [!code highlight]

function ThreadList() {
  const {
    threads,
    isLoading,
    renameThread,
    archiveThread,
    deleteThread,
  } = useThreads({ agentId: "my-agent" }); // [!code highlight]

  if (isLoading) return <div>Loading threads...</div>;

  return (
    <ul>
      {threads.map((thread) => (
        <li key={thread.id}>
          <span>{thread.name ?? "Untitled"}</span>
          <button onClick={() => renameThread(thread.id, "New name")}>
            Rename
          </button>
          <button onClick={() => archiveThread(thread.id)}>Archive</button>
          <button onClick={() => deleteThread(thread.id)}>Delete</button>
        </li>
      ))}
    </ul>
  );
}
```

## Behavior [#behavior]

- On mount, fetches the thread list and establishes a realtime WebSocket subscription.
- If the runtime does not advertise thread endpoints, no `/threads` request is made and `error` explains that thread endpoints are unavailable.
- Thread creates, renames, archives, and deletes from any client are reflected immediately without polling.
- Mutations update the list at once (optimistic). If the server rejects a delete, the thread comes back and `error` is set. Rename, archive, and unarchive do not roll back. The promises resolve on server confirmation and reject on failure.
- The `error` state updates with the most recent error from any operation.
- The `threads` array is sorted by the most recent run (`lastRunAt`), then by `updatedAt` for threads that have not run.
- New threads are **automatically named** when their first run creates them. By default, the name is the first user message. To get a short summary title from a model, set `generateThreadNames: { model }` on the runtime.
