# useThreads

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

## Overview [#overview]

`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. For a full walkthrough, see [Headless Threads](/headless-threads).

<Callout type="warn">
  Thread persistence runs in CopilotKit Intelligence, which is
  accessed with a `publicLicenseKey`. That key is **not yet supported on React
  Native** (see [`CopilotKitProvider`](/reference/react-native/components/CopilotKitProvider)),
  so `useThreads` is documented here for API parity but is not yet usable on
  React Native.
</Callout>

<Callout type="info">
  Re-exported from `@copilotkit/react-core/v2`, identical to the [React (V2) `useThreads`](/reference/v2/hooks/useThreads). The only difference is the import path.
</Callout>

Threads are sorted by most recent run first. The hook supports cursor-based pagination when a `limit` is provided.

## Signature [#signature]

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

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 name="enabled" type="boolean" default="true">
    When `false`, the hook does not fetch the thread list or subscribe to updates, and it skips mutations.
  </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 most recent run first. 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="listError" type="Error | null">
    The most recent list-load or mutation error, or `null`. Unlike `error`, it leaves out configuration errors (a missing runtime URL, or a runtime without thread endpoints), so you can show it to users.
  </PropertyReference>

  <PropertyReference name="fetchMoreError" type="Error | null">
    The error from the most recent failed next-page load, or `null`. It is cleared when you retry or when a next-page load succeeds.
  </PropertyReference>

  <PropertyReference name="isMutating" type="boolean">
    `true` while at least one rename, archive, unarchive, or delete waits for the server.
  </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="refetchThreads" type="() => void">
    Fetch the thread list again without clearing the current list. No-op until the runtime is connected.
  </PropertyReference>

  <PropertyReference name="startNewThread" type="() => void">
    Clears a stale thread-list error, so the welcome state shows cleanly. It
    does not create or switch the chat's thread. To start a new conversation,
    pass a new `threadId` to [`CopilotChat`](/reference/react-native/components/CopilotChat).
    A thread appears in `threads` after its first run is saved on the server.
  </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 it with `unarchiveThread`. 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 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-native"; // [!code highlight]
import { FlatList, Text, TouchableOpacity, View } from "react-native";

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

  if (isLoading) {
    return (
      <View>
        <Text>Loading threads...</Text>
      </View>
    );
  }

  return (
    <FlatList
      data={threads}
      keyExtractor={(thread) => thread.id}
      renderItem={({ item: thread }) => (
        <View>
          <Text>{thread.name ?? "Untitled"}</Text>
          <TouchableOpacity onPress={() => renameThread(thread.id, "New name")}>
            <Text>Rename</Text>
          </TouchableOpacity>
          <TouchableOpacity onPress={() => archiveThread(thread.id)}>
            <Text>Archive</Text>
          </TouchableOpacity>
          <TouchableOpacity onPress={() => deleteThread(thread.id)}>
            <Text>Delete</Text>
          </TouchableOpacity>
        </View>
      )}
    />
  );
}
```

## Behavior [#behavior]

- On mount, fetches the thread list and establishes a realtime WebSocket subscription. [AG-UI Streams & Framework Threads](/intelligence/threads-explained) explains the event replay model and the WebSocket sync.
- Thread creates, renames, archives, and deletes from any client are reflected immediately without polling.
- Mutations update the list at once, before the server confirms. If the server rejects a delete, the thread comes back and `error` is set. Rename, archive, and unarchive do not roll back. Promises resolve when the server accepts the request and reject on failure.
- The `error` state updates with the most recent error from any operation.
- The `threads` array is sorted by most recent run first (`lastRunAt`, then `updatedAt`, then `createdAt`). For a thread that has run, a rename or archive does not change its place.
- 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.
