Threads
This API is currently in Beta.
Overview
Threads keep every Investing Assistant API exchange stateful so you can execute long-running research, pause work, and resume with full context. Each thread stores metadata, message history, task progress, and structured artifacts generated during analysis.
- Use
POST /client/v1/threadsto create a new thread andGET /client/v1/threadsto discover existing ones. - Send instructions with
POST /client/v1/threads/{thread_id}/messages, stream events fromGET /client/v1/threads/stream/{thread_id}, and fall back toGET /client/v1/threads/{thread_id}/progresswhen the stream is unavailable. - See chat history and structured data table outputs with
GET /client/v1/threads/{thread_id}/messagesandGET /client/v1/threads/{thread_id}/artifacts/{artifact_id}respectively.
Review the API reference after finishing this guide to inspect every request and response schema.
Thread lifecycle
Send a message and stream updates
Submit the user prompt with POST /client/v1/threads/{thread_id}/messages. Immediately open GET /client/v1/threads/stream/{thread_id} to receive incremental reasoning, artifacts, and completion events through Server-Sent Events (SSE).
Collect outputs
Outputs are streamed through GET /client/v1/threads/stream/{thread_id}, but you can fetch the latest messages using GET /client/v1/threads/{thread_id}/messages?start_index=0&limit_num=25.
Structured data artifacts are accessible via GET /client/v1/threads/{thread_id}/artifacts/{artifact_id}.
Create and manage threads
Threads are lightweight resources. You can list, rename, or delete them without touching other workloads.
Deleting a thread removes all artifacts and history permanently. Be careful when issuing DELETE /client/v1/threads/{thread_id}.
Send and stream messages
POST /client/v1/threads/{thread_id}/messages validates the caller has access to the thread, queues the task, and returns immediately. Use the SSE stream to watch execution without polling.
If the SSE channel closes before completion, call GET /client/v1/threads/{thread_id}/progress. Issue DELETE /client/v1/threads/{thread_id}/task when a user manually stops work.
Retrieve history and artifacts
Use the history endpoint to build up the log of chat messages sent over the course of a conversation, and the artifacts endpoint to retrieve structured data output.
Artifacts are structured data outputs (such as tables, charts, or JSON objects) generated during thread execution. Unlike plain text responses, artifacts contain formatted data that can be retrieved and rendered separately using their unique artifact_id.
Tie artifact IDs to the message_id returned by GET /client/v1/threads/{thread_id}/messages so you can render both the prose answer and the structured data.
Upload user files to a thread
Attach supporting documents directly to a thread so the model can cite them during follow-up prompts. The endpoint expects multipart form data and associates the uploaded blob with the specified thread.
Store the returned file_id next to the thread metadata so later POST /client/v1/threads/{thread_id}/messages calls can reference the uploaded evidence in user prompts.
Cancel a running task
Use the cancellation endpoint to stop the currently processing message whenever a user changes their mind. The API records a “User cancelled” entry in the thread so downstream reviewers can see why work halted.
Complete example
The following example demonstrates the full workflow: creating a thread, establishing an SSE stream, sending a message, and processing real-time events until completion.
How streaming works
The SSE endpoint (GET /client/v1/threads/stream/{thread_id}) delivers events as they occur in the thread. To capture all events, open the stream connection before calling POST /client/v1/threads/{thread_id}/messages. The server pushes events in this typical flow:
message_work_in_progresslogs may appear before or between chunks, indicating background processing.message_chunkevents arrive incrementally as the AI generates its response. Each chunk contains the partial text undermessage_chunk.messageand afinal_chunkboolean flag.- When
final_chunk: truearrives, the complete message is ready. messageevents signal that a complete message has been assembled.task_statusorexecution_statusevents report progress. Whenstatus: "Complete"appears, the thread is idle.
Each message_chunk event follows this structure:
The message text is located at event.message_chunk.message. When final_chunk: true, no more chunks will arrive for that message. The example below uses Python’s threading module to handle the stream in the background while the main thread sends messages.
Script flow
The example script follows this sequence to ensure no events are missed:
- Create a thread using
POST /client/v1/threadsand capture thethread_id. - Start a background thread that opens the SSE connection to
/client/v1/threads/stream/{thread_id}. - Wait for confirmation that the stream is connected using
stream_connected.wait(). - Send the message via
POST /client/v1/threads/{thread_id}/messages. This triggers server-side processing. - Process events in the background thread: write message chunks to stdout, detect the final chunk, and exit when
status: "Complete"arrives.
The threading synchronization ensures the SSE listener is ready before the message triggers any events. Without this coordination, the first few chunks might be lost if the stream connects slowly.
Replace your-api-key-here with your actual API key. The example uses Python’s threading module to establish the SSE stream before sending the message, ensuring all events are captured.
Event types and structure
The stream emits several event types. Here are the most common:
Work in progress logs (background processing updates):
Message chunks (incremental response text):
Final chunk (last piece of the message):
Complete message (with metadata and tools):
Artifacts are JSON strings embedded in the message text (wrapped in triple backticks). Use GET /client/v1/threads/{thread_id}/artifacts/{artifact_id} to fetch the actual artifact data.
Task status (progress updates):
The example script writes message chunks directly to stdout as they arrive by reading event.message_chunk.message, creating a real-time typing effect. Work-in-progress logs may appear before or between chunks. When final_chunk: true appears, the complete message is ready. The client must parse any artifact markers from the message text to extract artifact_id values. The script continues listening until it receives a task_status event with status: "Complete", signaling that all processing has finished.
