Skip to main content

​
What Are Threads?

Threads let you have multi-turn conversations with Tako, similar to how you’d chat with an AI assistant. Instead of one-off queries, you can ask follow-up questions, refine your requests, and build context over multiple messages. The thread interface is similar to OpenAI’s Assistants API: you must first create a thread with one API call, then attach messages to it with separate calls. This two-step process gives you full control over the conversation flow.

​
How Threads Work

1. Create a Thread: Start a new conversation thread. Thread creation and message sending are separate operations—you cannot include a message when creating a thread. You can initialize threads with context like an in-focus card (for follow-up questions) or file sources (for data analysis), but you’ll need to add your first message in a separate API call. 2. Add Messages: Send user messages to the thread. Tako processes each message and responds with assistant messages that can include text, visualizations, data queries, and more. 3. Retrieve Messages: Get the full conversation history, including all user messages and Tako’s responses with rich content blocks. 
curl -X POST https://tako.com/api/v1/threads/thread_abc123/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_message": "How does that compare to AMD?"
  }'
Tako understands the context from previous messages and responds accordingly:
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Let me show you a comparison between Nvidia and AMD stock performance:"
    },
    {
      "type": "visualization",
      "card_id": "def456",
      "title": "Nvidia vs AMD Stock Comparison",
      "embed_url": "https://tako.com/embed/def456"
    }
  ]
}
Thread creation and message sending are always separate operations:
# Step 1: Create thread
curl -X POST https://tako.com/api/v1/threads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Response: {"thread_id": "thread_abc123"}

# Step 2: Add first message (separate request)
curl -X POST https://tako.com/api/v1/threads/thread_abc123/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_message": "What are the top performing tech stocks this week?"
  }'
When you want to ask follow-up questions about a specific visualization or card, initialize the thread with in_focus_card_id, then add your message separately:
# Step 1: Create thread with in-focus card
curl -X POST https://tako.com/api/v1/threads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "in_focus_card_id": "card_xyz789"
  }'

# Response: {"thread_id": "thread_abc123", "in_focus_card_id": "card_xyz789"}

# Step 2: Add your first message (separate request)
curl -X POST https://tako.com/api/v1/threads/thread_abc123/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_message": "What caused this spike in November?"
  }'
Tako will understand the context of the in-focus card and respond with relevant analysis:
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "The spike in November was primarily driven by three factors..."
    }
  ]
}
When you have data files that are relevant to the conversation—either for analyzing alongside an in-focus card or for creating new visualizations—include them as file sources when creating the thread, then add your message separately:
# Step 1: Create thread with file sources
curl -X POST https://tako.com/api/v1/threads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_sources": [
      {
        "name": "Q4_sales_data.csv",
        "url": "https://example.com/data/q4_sales.csv"
      }
    ]
  }'

# Response: {"thread_id": "thread_abc123"}

# Step 2: Add your message (separate request)
curl -X POST https://tako.com/api/v1/threads/thread_abc123/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_message": "Analyze the sales trends in this data"
  }'
Alternative: Inline CSV DataIf you want to pass CSV data directly instead of using file URLs, use the csv field:
# Step 1: Create thread with inline CSV
curl -X POST https://data.tako.com/api/v1/threads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "csv": "product,revenue,units_sold\nWidget A,50000,1200\nWidget B,45000,980\nWidget C,38000,850"
  }'

# Response: {"thread_id": "thread_abc123"}

# Step 2: Add your message (separate request)
curl -X POST https://tako.com/api/v1/threads/thread_abc123/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_message": "Show me the top products by revenue"
  }'
When to Include File Sources or CSV:
  • When you want Tako to analyze data from your files to create new visualizations
  • When you have an in-focus card and want to provide additional data context for follow-up questions
  • When the user is asking about data that lives in CSV files or other data sources

​
Understanding Assistant Responses

Tako’s assistant messages can include multiple types of content blocks:
  • Text: Natural language explanations and context
  • Visualizations: Interactive Tako cards with data visualizations
  • Queries: The underlying data queries Tako used
  • Follow-ups: Suggested follow-up questions
  • Thinking Steps: Tako’s reasoning process (when available)
Each visualization includes rich metadata (title, description, embed_url, image_url, sources, methodologies) that you can use to display the content or ground your own responses.

​
Pro Tips for Using Threads

1. Threads Maintain Context:
  • The Power: Unlike single queries, threads remember the conversation. Ask a follow-up and Tako knows what “that” or “it” refers to.
  • Use Case: Perfect for exploratory analysis, iterative refinement, or when users naturally ask follow-up questions in your app.
2. Thread Creation is Always Two Steps:
  • Step 1 - Create Thread: First, create the thread (optionally with context like in_focus_card_id or file_sources). You’ll get back a thread_id.
  • Step 2 - Add Messages: Then, add messages to the thread using the thread_id from step 1. Each message requires a separate API call.
  • Why Two Steps? This gives you control over the thread lifecycle and makes it easy to manage conversation state in your app.
3. Retrieve Full Conversation History:
  • GET /v1/threads//messages returns the complete conversation, including all content blocks.
  • Why It Matters: You can display the full conversation in your UI, resume conversations later, or analyze what visualizations were generated.
4. Use Visualizations in Responses:
  • Rich Content: Assistant messages can include multiple visualizations, not just text.
  • Display Options: Each visualization includes:
    • embed_url: Drop into an iframe for interactive charts
    • image_url: Static image for reports or thumbnails
    • webpage_url: Link to the full Tako card page
    • description: Natural language summary of the data for grounding
    • sources & methodologies: Build trust by showing data provenance
5. Thread Management:
  • List Threads: Use GET /v1/threads to see all threads for your account
  • Get Specific Thread: Use GET /v1/threads/ to retrieve thread metadata
  • Plan for Scale: Consider how you’ll manage threads in your app – map them to user sessions, projects, or conversations
6. Natural Language All The Way:
  • No Special Syntax: Just send natural language messages like “compare that to last year” or “show me the breakdown by region”
  • Context-Aware: Tako understands references to previous messages, data points, and visualizations
  • Conversational: Users can chat naturally without learning a query language
7. Initialize Threads With Context:
  • In-Focus Card: Use in_focus_card_id when users want to ask follow-up questions about a specific visualization. This tells Tako “the conversation is about this card” from the start.
  • File Sources: Include file_sources when you have data files (CSV, JSON, etc.) that Tako should analyze to create new visualizations or provide context for an in-focus card.
  • Inline CSV: Use the csv field to pass CSV data directly in the request—it serves the same function as file sources but without needing a URL.
  • When to Use: Add context at thread creation when you know what data or card the conversation will focus on. This helps Tako provide more relevant, grounded responses.
Basically: Threads are perfect for conversational, multi-turn interactions where context matters. Create them first (optionally with context like in-focus cards or file sources), then add natural language messages separately, and use the rich visualization content in your app. The two-step process gives you control over conversation flow. Think ChatGPT-style conversations, but with data visualizations!