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://tako.com/",  # Optional
    api_version="v1"  # Optional
)

knowledge_search()

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_update_file()

Update metadata for an uploaded file in Tako.

Parameters

file_id (str): The ID of the file to update
display_name (Optional[str]): New display name for the file
file_context (Optional[str]): Updated context description to help Tako understand the file
source (Optional[str]): Updated source information for the file

Returns

dict: Response containing updated file information

Example

response = client.beta_update_file(
    file_id="your-file-id",
    display_name="Updated Sales Data Q4 2024",
    file_context="Updated quarterly sales data with revised product categories",
    source="Internal CRM System"
)
print(f"Updated file: {response}")

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://tako.com/card/dnjTI20unRq_q13PX4Am/',
                image_url='https://tako.com/api/v1/image/dnjTI20unRq_q13PX4Am/',
                embed_url='https://tako.com/embed/dnjTI20unRq_q13PX4Am/',
                sources=[...],
                methodologies=[...],
                source_indexes=[KnowledgeSearchSourceIndex.TAKO],
                card_type='chart'
            )
        ]
    ),
    request_id='ab06f02c-8139-4166-b978-639cba618823'
)

Getting Started

Integrating Tako

Popular Integrations and Examples

​TakoClient

​Initialization

​knowledge_search()

​Parameters

​Returns

​Example

​get_image()

​Parameters

​Returns

​Example

​beta_visualize()

​Parameters

​Returns

​Example

​beta_upload_file()

​Parameters

​Returns

​Example

​beta_file_connector()

​Parameters

​Returns

​Example

​beta_file_info()

​Parameters

​Returns

​Example

​beta_update_file()

​Parameters

​Returns

​Example

​beta_delete_file()

​Parameters

​Returns

​Example

​beta_chart_insights()

​Parameters

​Returns

​Example

​AsyncTakoClient

​Common Response Format

TakoClient

Initialization

knowledge_search()

Parameters

Returns

Example

get_image()

Parameters

Returns

Example

beta_visualize()

Parameters

Returns

Example

beta_upload_file()

Parameters

Returns

Example

beta_file_connector()

Parameters

Returns

Example

beta_file_info()

Parameters

Returns

Example

beta_update_file()

Parameters

Returns

Example

beta_delete_file()

Parameters

Returns

Example

beta_chart_insights()

Parameters

Returns

Example

AsyncTakoClient

Common Response Format