---
title: "useThreads"
description: "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 an Enterprise Intelligence Platform project"
  body="Sign up for a free account to get a public license key and start syncing threads."
  ctaLabel="Create a free account"
  surface="docs_reference_use_threads"
/>

## Overview

`useThreads` is a React hook for managing conversation threads on the Enterprise Intelligence Platform. 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 most recently updated first. The hook supports cursor-based pagination when a `limit` is provided.

## Signature

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

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

## Parameters

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

  <PropertyReference name="agentId" type="string">
    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

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

  ### State

  <PropertyReference name="threads" type="Thread[]">
    Array of threads for the current user and agent, sorted by most recently updated first. Each `Thread` contains:
    - `id: string` — unique thread identifier
    - `agentId: string` — the agent this thread belongs to
    - `name: string | null` — thread name (auto-generated by the LLM on first run, 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

  <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`. Archived threads can be restored via the `unarchived` platform event. The promise resolves on server confirmation, or rejects with an `Error` on failure. No built-in confirmation dialog — implement your own if needed.
  </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. No built-in confirmation dialog — implement your own if needed.
  </PropertyReference>
</PropertyReference>

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

- On mount, fetches the thread list and establishes a realtime WebSocket subscription.
- Thread creates, renames, archives, and deletes from any client are reflected immediately without polling.
- All mutation methods use **pessimistic updates** — the UI updates only after the server confirms the operation via WebSocket, not immediately on dispatch. Promises resolve on confirmation (15-second timeout) and reject on failure.
- The `error` state updates with the most recent error from any operation.
- The `threads` array stays sorted by `updatedAt` descending (most recent first).
- New threads are **automatically named** by the LLM after their first run (2–5 word title). This is configurable via `generateThreadNames` on the runtime.

## Next steps

- **Understand how it works:** [How Threads & Persistence Work](/premium/threads-explained) — architecture, event replay model, and WebSocket sync
- **Step-by-step guide:** [Threads](/threads) — set up thread management in your app
- **Tutorial:** [Build a Multi-Conversation Chat App](/tutorials/multi-conversation-chat) — end-to-end walkthrough building a chat app with thread history
