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 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.

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.0,
      "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.

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, or it may be large.
`inline`	The content directly in the response (`data`), with `total_rows` and `truncated`.	You want the data in-process immediately. CSV is capped at 1000 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"
  }'

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 (default `0.0`). A Tako card’s CSV is free; web text extraction may carry a cost. See Credits & billing.
`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 1000-row cap truncated it).
`truncated`	boolean	inline mode: `true` when the inline CSV was capped at 1000 rows.

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.

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
Trusting an inline CSV is complete	Inline CSV is capped at 1000 rows — check `truncated` and `total_rows`, or use `url` mode for the full file
Reusing the download `url` later	It’s short-lived — honor `expires_at` and re-request if it has expired

Errors

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

Status	Meaning	Fix
`400`	Malformed request (bad JSON, missing `url`, or a URL with no downloadable content).	Pass a result `url` that carried a `content` descriptor in the Search/Answer response.
`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.
`408`	The request timed out.	Retry the request.

​What Contents does

​Minimal working example

​Request parameters

​Delivery modes

​What a response looks like

​The CSV behind a Tako card

​When to use Contents

​Common mistakes

​Errors

What Contents does

Minimal working example

Request parameters

Delivery modes

What a response looks like

The CSV behind a Tako card

When to use Contents

Common mistakes

Errors