Skip to main content

​
TakoClient

​
Initialization

from tako import TakoClient

client = TakoClient(
    api_key="your-api-key",  # Optional if TAKO_API_KEY env var is set
    server_url="https://trytako.com/",  # Optional
    api_version="v1"  # Optional
)
Search for knowledge cards based on a natural language query.

​
Parameters

  • text (str): The natural language query string
  • source_indexes (Optional[List[KnowledgeSearchSourceIndex]]): Priority order of sources to search. Search stops when results are found in first index.
    • Valid values: KnowledgeSearchSourceIndex.TAKO, KnowledgeSearchSourceIndex.WEB, KnowledgeSearchSourceIndex.CONNECTED_DATA
    • Default: [KnowledgeSearchSourceIndex.TAKO]
  • output_settings (Optional[KnowledgeSearchRequestOutputSettings]): Settings for controlling knowledge card outputs
  • country_code (Optional[str]): ISO3166-1 alpha-2 country code (e.g., ‘US’, ‘CA’, ‘GB’). Default: “US”

​
Returns

KnowledgeSearchResults object containing:
  • request_id: Unique request identifier
  • outputs.knowledge_cards: List of knowledge cards with:
    • card_id: Unique card identifier
    • title: Card title
    • description: Detailed description
    • webpage_url: Interactive card URL
    • image_url: Static image URL
    • embed_url: Embeddable iframe URL
    • sources: Data sources information
    • methodologies: Data collection methodologies
    • card_type: Type of card (chart, table, text, etc.)

​
Example

results = client.knowledge_search(
    text="what's the msft stock price today?",
    source_indexes=[KnowledgeSearchSourceIndex.TAKO, KnowledgeSearchSourceIndex.WEB]
)

for card in results.outputs.knowledge_cards:
    print(f"Title: {card.title}")
    print(f"URL: {card.webpage_url}")

​
get_image()

Retrieve a static image for a knowledge card.

​
Parameters

  • card_id (str): The ID of the knowledge card

​
Returns

bytes: The image content as bytes

​
Example

image_bytes = client.get_image("dnjTI20unRq_q13PX4Am")
with open("chart.png", "wb") as f:
    f.write(image_bytes)

​
beta_visualize()

Create visualizations from datasets or files.

​
Parameters

  • tako_formatted_dataset (Optional[TakoDataFormatDataset]): Dataset in Tako Data Format
  • file_id (Optional[str]): ID of uploaded file to visualize
  • query (Optional[str]): Query with visualization instructions
  • model (Optional[VisualizeSupportedModels]): Model to use
    • o3
    • o4-mini
    • qwen-3-32b
    • llama-3.3-70b
    • qwen-3-coder-480b
    • qwen-3-235b-a22b-instruct-2507
    • qwen-3-235b-a22b-thinking-2507
  • output_settings (Optional[KnowledgeSearchRequestOutputSettings]): Output control settings
  • viz_component_type (Optional[UserRequestedVizComponentType]): Visualization type
    • bar
    • timeseries
    • pie
    • scatter
    • boxplot
    • choropleth
    • heatmap
    • timeline
    • waterfall
Note: Either tako_formatted_dataset or file_id must be provided, but not both.

​
Returns

KnowledgeSearchResults: Visualization results as knowledge cards

​
Example

# Using uploaded file
results = client.beta_visualize(
    file_id="your-file-id",
    query="Create a bar chart showing revenue by quarter",
    viz_component_type=UserRequestedVizComponentType.BAR
)

# Using Tako Data Format
dataset = TakoDataFormatDataset(...)
results = client.beta_visualize(
    tako_formatted_dataset=dataset,
    query="Show trends over time"
)

​
beta_upload_file()

Upload a file to Tako for visualization and analysis.

​
Parameters

  • file_path (str): Path to the file to upload
  • file_context (Optional[str]): Context description to help Tako understand the file

​
Returns

str: The file ID for use in other methods

​
Example

file_id = client.beta_upload_file(
    file_path="./data/sales_data.csv",
    file_context="Monthly sales data for 2024 by region and product category"
)
print(f"Uploaded file ID: {file_id}")

​
beta_file_connector()

Connect to a file hosted at a URL for Tako to download and analyze.

​
Parameters

  • file_url (str): URL of the file to connect to
  • file_id (Optional[str]): ID of existing file to update. If not provided, creates new file

​
Returns

dict: Response containing:
  • message: Status message
  • id: File ID
  • metadata: File metadata including creation/update timestamps

​
Example

response = client.beta_file_connector(
    file_url="https://example.com/data/quarterly_results.xlsx"
)
print(f"Connected file ID: {response['id']}")

​
beta_file_info()

Get information about an uploaded file.

​
Parameters

  • file_id (str): The ID of the file to get information for

​
Returns

dict: Response containing file information including:
  • file_id: The unique file identifier
  • last_updated_at: ISO timestamp of last update (nullable)
  • key: File key in storage (nullable)
  • schema: Schema information with schema_id and display_name (nullable)
  • file_url: Downloadable file URL (nullable)
  • file_context: Context description provided during upload (nullable)
  • segment_id: Segment identifier (nullable)
  • source: File source information (nullable)
  • cleaned_files: Array of processed file versions with metadata
  • connected_private_index: Connected private index ID (nullable)

​
Example

file_info = client.beta_file_info("your-file-id")
print(f"File ID: {file_info['file_id']}")
print(f"Last updated: {file_info.get('last_updated_at')}")
print(f"File context: {file_info.get('file_context')}")
print(f"Cleaned files: {len(file_info['cleaned_files'])}")

​
beta_delete_file()

Delete an uploaded file from Tako.

​
Parameters

  • file_id (str): The ID of the file to delete

​
Returns

bool: Returns True if the file was successfully deleted, or raises an exception if the deletion fails

​
Example

try:
    success = client.beta_delete_file("your-file-id")
    print("File deleted successfully")
except Exception as e:
    print(f"Failed to delete file: {e}")

​
beta_chart_insights()

Get insights from a chart in a Tako Knowledge Card.

​
Parameters

  • card_id (str): The ID of the chart to get insights for

​
Returns

dict: Response containing:
  • insights: List of insights extracted from the visualization
  • description: Optional description of the chart insights

​
Example

insights = client.beta_chart_insights("dnjTI20unRq_q13PX4Am")
print(f"Insights: {insights['insights']}")
if insights.get('description'):
    print(f"Description: {insights['description']}")

​
AsyncTakoClient

For asynchronous operations, use AsyncTakoClient with the same methods but with async/await: 
from tako import AsyncTakoClient

async_client = AsyncTakoClient(api_key="your-api-key")

# All methods support timeout_seconds parameter
results = await async_client.knowledge_search(
    text="search query",
    timeout_seconds=60.0
)

file_id = await async_client.beta_upload_file(
    file_path="./data.csv",
    timeout_seconds=120.0
)

​
Common Response Format

Most methods return KnowledgeSearchResults: 
KnowledgeSearchResults(
    outputs=KnowledgeSearchOutputs(
        knowledge_cards=[
            KnowledgeCard(
                card_id='dnjTI20unRq_q13PX4Am',
                title='Microsoft Stock Overview',
                description='Microsoft stock price is 435.20 at 2025-05-02T21:40:00+00:00...',
                webpage_url='https://trytako.com/card/dnjTI20unRq_q13PX4Am/',
                image_url='https://trytako.com/api/v1/image/dnjTI20unRq_q13PX4Am/',
                embed_url='https://trytako.com/embed/dnjTI20unRq_q13PX4Am/',
                sources=[...],
                methodologies=[...],
                source_indexes=[KnowledgeSearchSourceIndex.TAKO],
                card_type='chart'
            )
        ]
    ),
    request_id='ab06f02c-8139-4166-b978-639cba618823'
)
⌘I