For Your Coding Agent

This page is a complete, self-contained reference for building against Tako Contents — the endpoint that downloads the structured data behind a Search or Answer result. Every example runs after you supply an API key, every parameter is grounded in the live API, and the common mistakes are called out explicitly. For the auto-generated schema, see the Contents API reference; for a narrative introduction, see the Overview.

What Contents does

POST https://tako.com/api/v1/contents takes a result url and returns the full content behind that result — one of two forms, depending on what the URL points to: a structured-data CSV export of a Tako card’s underlying data, or the full extracted text of any other web page. You don’t pass a format — Tako detects the right content from the URL and the response reports what it produced. Reach for it when you’ve already found the right result with Search or Answer and you want the content itself, fast, in a form you can parse and feed to a model. The CSV is the Tako card’s data and the extracted text is the web page — there’s no synthesis and nothing to re-derive — which makes Contents well suited to agentic loops that need precise, source-grounded inputs quickly.

Base URL: https://tako.com/api/
Auth: send your API key in the X-API-Key request header (not a bearer token). Create a key in the Tako console.
Prerequisite: a result is downloadable only when it carries a content descriptor in the Search/Answer response. Use that result’s URL here — a card’s webpage_url or a web result’s url. If a result has no content descriptor, its data isn’t exportable — don’t call Contents on it; the endpoint will refuse it (see Errors).

Minimal working example

This downloads the data behind a Tako card. The default url mode returns a short-lived presigned link; fetch that link to get the CSV.

cURL

curl -X POST https://tako.com/api/v1/contents \
  -H "X-API-Key: $TAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tako.com/card/KfYeym50vtsF93LMsIFW/"
  }'

Response

{
  "contents": [
    {
      "format": "csv",
      "source_url": "https://tako.com/card/KfYeym50vtsF93LMsIFW/",
      "cost": 0.021,
      "url": "https://tako.com/...signed-download...",
      "expires_at": "2026-06-29T18:30:00Z"
    }
  ],
  "request_id": "9c1b..."
}

Request parameters

The body is a ContentsRequest. Only url is required.

Parameter	Type	Default	Description
`url`	string	— (required)	The result URL to download. A Tako card’s `webpage_url` yields a CSV of the card’s data; any other URL yields the page’s extracted text.
`mode`	string enum	`url`	Delivery mode. `url` returns a short-lived presigned download link; `inline` returns the content in the response body.
`max_rows`	integer	the whole card in `url` mode; 2,000 rows in `inline` mode	Card URLs only; web URLs ignore it. Rows to return, clamped to the 100,000-row ceiling. Every card format honors it, `card_json` included. See Which rows a capped export keeps. This is the field that decides the bill: every row returned is billed. Omit it in `url` mode to get the whole card. See Contents pricing.
`quote_only`	boolean	`false`	Return the `cost` for this download without fetching it or being charged.

Delivery modes

mode controls how the content comes back:

`mode`	Returns	Use when
`url` (default)	A presigned, short-lived download `url` plus `expires_at`.	You want to stream or store the file, it may be large, or an agent will parse it.
`inline`	The content directly in the response (`data`), with `total_rows` and `truncated`.	You want a small card’s data in-process immediately. Returns 2,000 rows unless you set `max_rows`. Check `truncated` and `total_rows`.

inline mode

curl -X POST https://tako.com/api/v1/contents \
  -H "X-API-Key: $TAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tako.com/card/KfYeym50vtsF93LMsIFW/",
    "mode": "inline"
  }'

Give a large export to an agent

A model reads every row you pass it as tokens, so keep the export out of the model’s context. Write the export to a file, on disk or in memory, and give your agent a code tool that parses it. The tool returns only what the model needs, such as the latest 12 rows or a computed growth rate.

DOWNLOAD_URL=$(curl -s -X POST https://tako.com/api/v1/contents \
  -H "X-API-Key: $TAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://tako.com/card/KfYeym50vtsF93LMsIFW/"}' | jq -r '.contents[0].url')

curl -s -o card.csv "$DOWNLOAD_URL"

import os

import pandas as pd
import requests

response = requests.post(
    "https://tako.com/api/v1/contents",
    headers={"X-API-Key": os.environ["TAKO_API_KEY"]},
    json={"url": "https://tako.com/card/KfYeym50vtsF93LMsIFW/"},
    timeout=30,
)
response.raise_for_status()
df = pd.read_csv(response.json()["contents"][0]["url"])

On disk, point the agent’s code tool at card.csv. In memory, have your tool functions read df. Either way, the model sees the tool’s result, not the rows. The download url is short-lived, so fetch it before expires_at.

What a response looks like

A 200 returns a ContentsResponse. contents is a list (today it always carries exactly one item, so the contract stays stable if a result ever yields multiple artifacts).

Field	Type	Description
`contents`	array	The downloadable artifacts (see `ContentItem` below).
`request_id`	string	Always present — log it for support/debugging.

Each ContentItem carries:

Field	Type	Description
`format`	string	`csv` for a Tako card, `text` for a web page.
`cost`	number	USD cost of this download. A card CSV bills a per-export baseline plus a per-row rate; web text extraction bills per page. See Contents pricing.
`source_url`	string	The originating result URL that was resolved.
`url`	string \| null	url mode: presigned, short-lived download link. Null in inline mode.
`expires_at`	string \| null	url mode: ISO‑8601 UTC time when `url` expires. Null in inline mode.
`data`	string \| null	inline mode: the content itself (CSV text or web text). Null in url mode.
`total_rows`	integer \| null	inline mode: total rows in the source CSV (so you can tell whether the 100,000-row ceiling truncated it).
`truncated`	boolean	inline mode: `true` when the export returned fewer rows than the card holds — because `max_rows` cut it, or because the card exceeds the 100,000-row ceiling.

The CSV behind a Tako card

For a Tako card, the CSV has a header row naming each series exactly as the card sources it, then one row per data point. A time-series card is keyed by an ISO‑8601 Timestamp (with timezone offset), one column per series:

Timestamp,usaspending_sum_obligation - Palantir Technologies Inc. Federal Contract Obligations
2007-10-01 00:00:00+00:00,135211.06
2008-10-01 00:00:00+00:00,4378216.96
2009-10-01 00:00:00+00:00,5801023.5
2010-10-01 00:00:00+00:00,20915978.15
2011-10-01 00:00:00+00:00,39889371.870000005
2012-10-01 00:00:00+00:00,33785816.41
2013-10-01 00:00:00+00:00,75264989.77

…one row per fiscal year through the latest data point. The header is self-describing, so the values are ready to compute on and to attribute back to the card.

Which rows a capped export keeps

When a card holds more rows than max_rows or the 100,000-row ceiling, Contents returns part of it. Which part depends on the format. csv, json_records, and json_compact:

A card with a date column keeps the rows with the latest dates. Contents counts back from the latest date in the card’s data, not from today. On a card with future rows, such as a season schedule or a weather forecast, a capped export keeps the far end of the future and drops the dates nearest today.
A card without a date column, such as a ranking or a comparison table, keeps its first rows.
Either way, the rows stay in the card’s own order. A card that shows newest first exports newest first.

card_json cuts each card type its own way. A price or indicator series keeps its newest readings. A forecast, a schedule, or a ranking keeps its first records. So a capped schedule card can return its latest games as csv and its earliest games as card_json. To get a specific stretch of a large card, don’t rely on the cap. Check truncated and total_rows, and raise max_rows until truncated is false, or use a card that covers a narrower range.

When to use Contents

Contents fetches the full content behind a result you already have from Search or Answer — a structured-data CSV export of a Tako card’s underlying series, or the full extracted text of any other web page. Reach for it when:

You’ve already found the result and want the content itself, not prose. There’s no synthesis and nothing to re-derive — the CSV is the card’s data, and the extracted text is the page, ready to use directly.
It’s a second step, not a search. Contents operates on a URL you already have: find the result with Search or Answer first, then fetch what’s behind it.
You’re building agentic apps that need precise, source-grounded inputs fast. Pull the exact numbers behind a card, or the full clean text behind a web result, and act on real content instead of scraping it yourself.

Search and Answer find the result; Contents fetches the content behind it. To skip the second call, inline the content directly in a Search/Answer response with the per-source include_contents setting.

Common mistakes

Avoid these — they are the patterns coding agents most often get wrong.

Wrong	Correct
`Authorization: Bearer $KEY`	`X-API-Key: $KEY`
Passing a `format` field	You don’t — Tako detects `csv` vs `text` from the URL and reports it back
Passing a query string as `url`	`url` must be a result URL from Search/Answer (a card’s `webpage_url` or a web result’s `url`)
Reading `data` after a `url`-mode call	`url` mode returns a download link in `url`; `data` is populated only in `inline` mode
Leaving `max_rows` unset on a large card	An omitted `max_rows` returns the whole card in `url` mode, up to 100,000 rows, and 2,000 rows in `inline` mode. It bills every row returned. Set it when you want a slice — and use `quote_only` to price the call first
Trusting an export is complete	An export returns at most 100,000 rows in either mode. Check `truncated` and `total_rows`, and narrow the card or its time range if rows remain
Reading a large export into a model’s context	Write the export to a file, on disk or in memory, and have the agent parse it with code. Give the model only the rows it needs. See Give a large export to an agent
Reusing the download `url` later	It’s short-lived — honor `expires_at` and re-request if it has expired
Calling Contents on a result with no `content` descriptor	Its absence means the data isn’t exportable — check for `content` first and skip those results

Errors

Failures return a BaseAPIError body: { "error_message": "...", "error_type": "..." }.

Status	Meaning	Fix
`400`	Malformed request — bad JSON, missing `url`, or a `url` that isn’t a fetchable result URL.	Pass a result `url` from a Search/Answer response (a card’s `webpage_url` or a web result’s `url`).
`401`	Missing or invalid API key.	Send a valid key in the `X-API-Key` header.
`402`	Out of credits (insufficient balance).	Top up credits — see Credits & billing.
`403`	The result’s underlying data can’t be exported.	Expected for results that came back without a `content` descriptor — don’t call Contents on them.
`404`	No such card, or the card has no exportable data.	Verify the `url` came from a recent Search/Answer result.
`408`	The request timed out.	Retry the request.

Getting Started

Build with Tako

API Reference

Integrations

Additional Resources

For Your Coding Agent

What Contents does

Minimal working example

Request parameters

Delivery modes

Give a large export to an agent

What a response looks like

The CSV behind a Tako card

Which rows a capped export keeps

When to use Contents

Common mistakes

Errors

​What Contents does

​Minimal working example

​Request parameters

​Delivery modes

​Give a large export to an agent

​What a response looks like

​The CSV behind a Tako card

​Which rows a capped export keeps

​When to use Contents

​Common mistakes

​Errors

What Contents does

Minimal working example

Request parameters

Delivery modes

Give a large export to an agent

What a response looks like

The CSV behind a Tako card

Which rows a capped export keeps

When to use Contents

Common mistakes

Errors