Overview
useTamboThread is a React Query hook for fetching a single thread by ID with automatic caching and refetching.
Import
import { useTamboThread } from '@tambo-ai/react';
Signature
function useTamboThread(
threadId: string,
options?: UseQueryOptions<ThreadRetrieveResponse>
): UseQueryResult<ThreadRetrieveResponse>
Parameters
The unique identifier of the thread to fetch
options
UseQueryOptions<ThreadRetrieveResponse>
Additional React Query options for customizing the query behavior
Whether the query should automatically run. Defaults to true
Interval in milliseconds to automatically refetch data
Whether to refetch on component mount
Whether to refetch when window regains focus
Return Value
Returns a React Query result object:
The thread data including all messages and run status
Thread name (auto-generated or user-set)
User identifier who owns the thread
Current run status: idle, running, completed, failed, cancelled
Array of all messages in the thread
ISO 8601 timestamp of creation
ISO 8601 timestamp of last update
Custom metadata attached to the thread
Whether the initial data is being loaded
Whether an error occurred while fetching
Error object if the query failed
Function to manually refetch the thread data
Behavior
- Stale Time: Thread data is considered stale after 1 second (real-time data)
- Authentication: Automatically disabled until user is identified
- Caching: Uses React Query for intelligent caching and deduplication
- Auto-refetch: Refetches on window focus and reconnection by default
Examples
Basic Usage
import { useTamboThread } from '@tambo-ai/react';
function ThreadView({ threadId }: { threadId: string }) {
const { data: thread, isLoading, isError } = useTamboThread(threadId);
if (isLoading) {
return <div>Loading thread...</div>;
}
if (isError) {
return <div>Error loading thread</div>;
}
return (
<div>
<h2>{thread.name || 'Untitled Thread'}</h2>
<p>Status: {thread.runStatus}</p>
<div>
{thread.messages.map(message => (
<Message key={message.id} message={message} />
))}
</div>
</div>
);
}
With Polling
Poll for updates every 2 seconds:
function LiveThreadView({ threadId }: { threadId: string }) {
const { data: thread, isLoading } = useTamboThread(threadId, {
refetchInterval: 2000, // Poll every 2 seconds
});
if (isLoading) return <Spinner />;
return (
<div>
<StatusBadge status={thread.runStatus} />
<MessageList messages={thread.messages} />
</div>
);
}
Conditional Fetching
Only fetch when a thread ID is selected:
function ThreadDetailPanel() {
const [selectedThreadId, setSelectedThreadId] = useState<string | null>(null);
const { data: thread, isLoading } = useTamboThread(
selectedThreadId || '', // Provide empty string as fallback
{
enabled: selectedThreadId !== null, // Only fetch when ID exists
}
);
if (!selectedThreadId) {
return <div>Select a thread to view details</div>;
}
if (isLoading) return <Spinner />;
return <ThreadDetail thread={thread} />;
}
Manual Refetch
function ThreadWithRefresh({ threadId }: { threadId: string }) {
const { data: thread, isLoading, refetch } = useTamboThread(threadId);
const handleRefresh = async () => {
await refetch();
};
return (
<div>
<button onClick={handleRefresh} disabled={isLoading}>
Refresh Thread
</button>
{thread && <ThreadContent thread={thread} />}
</div>
);
}
useTamboThreadList
Fetch a list of threads
useTambo
Main hook for thread state
Thread Types
Thread type definitions
Threads Concept
Learn about threads