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 create a thread with one call, then attach messages to it separately. This gives you full control over the conversation flow.

​
How Threads Work

1. Create a Thread: Start a new conversation thread. You can optionally include the first message when creating the thread, or add messages separately. You can also initialize threads with context like an in-focus card (for follow-up questions) or file sources (for data analysis). 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 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_message": "Show me Nvidia stock performance over the last year"
  }'
Response includes the thread_id and Tako’s first assistant message with visualizations:
{
  "thread_id": "thread_abc123",
  "messages": [
    {
      "role": "user",
      "content": "Show me Nvidia stock performance over the last year"
    },
    {
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "Here's Nvidia's stock performance over the past year:"
        },
        {
          "type": "visualization",
          "card_id": "xyz789",
          "title": "Nvidia Stock Price - Last 12 Months",
          "embed_url": "https://tako.com/embed/xyz789"
        }
      ]
    }
  ]
}

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"
    }
  ]
}
Sometimes you want to create a thread first, then add messages separately:
# Step 1: Create empty 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
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. This tells Tako the conversation is about that particular 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",
    "user_message": "What caused this spike in November?"
  }'
Tako will understand the context of the in-focus card and respond with relevant analysis:
{
  "thread_id": "thread_abc123",
  "in_focus_card_id": "card_xyz789",
  "messages": [
    {
      "role": "user",
      "content": "What caused this spike in November?"
    },
    {
      "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:
curl -X POST https://tako.com/api/v1/threads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_message": "Analyze the sales trends in this data",
    "file_sources": [
      {
        "name": "Q4_sales_data.csv",
        "url": "https://example.com/data/q4_sales.csv"
      }
    ]
  }'
Alternative: Inline CSV DataIf you want to pass CSV data directly instead of using file URLs, use the csv field. This serves the same function as file sources but lets you include the data inline:
curl -X POST https://data.tako.com/api/v1/threads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_message": "Show me the top products by revenue",
    "csv": "product,revenue,units_sold\nWidget A,50000,1200\nWidget B,45000,980\nWidget C,38000,850"
  }'
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. Choose Your Thread Creation Style:
  • With First Message: Create thread + send first message in one call. Great for getting started quickly.
  • Empty Then Messages: Create an empty thread, then add messages separately. Useful when you want the thread_id before adding content, or when managing conversation state in your app.
  • Both Work! The interface is flexible – use whichever fits your app’s flow.
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 easily (with or without a first message), send natural language messages, and use the rich visualization content in your app. Initialize with in-focus cards or file sources when you want to ground the conversation in specific data. Think ChatGPT-style conversations, but with data visualizations!