> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tako.com/llms.txt
> Use this file to discover all available pages before exploring further.

# For Your Coding Agent

> The build reference for coding agents integrating Tako Contents. Self-contained and copy-paste-ready — endpoint, X-API-Key auth, the url/mode request, both delivery modes, the CSV export behind a Tako card and the full extracted text behind a web page, and runnable cURL examples. Use this page to fetch the full content behind a Search or Answer result.

export const ContentsContextWarning = () => <Warning>
    <strong>Don't read a large export into a model's context.</strong> A card export can hold up to 100,000 rows, and at about 15 tokens per row, 10,000 rows cost about 150,000 tokens. Write the export to a file, on disk or in memory, and have your agent parse it with code. Give the model only the rows or results it needs. To cap the export instead, set <code>max_rows</code>.
  </Warning>;

This page is a complete, self-contained reference for building against **Tako Contents** — the endpoint that downloads the structured data behind a [Search](/documentation/integrating-tako/search/for-coding-agent) or [Answer](/documentation/integrating-tako/answer/for-coding-agent) 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](/api-reference/contents); for a narrative introduction, see the [Overview](/documentation/integrating-tako/contents/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](https://tako.com/console/api-keys).
* **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](#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.

```bash cURL theme={null}
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/"
  }'
```

```json Response theme={null}
{
  "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](#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](/documentation/integrating-tako/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`. |

<ContentsContextWarning />

```bash inline mode theme={null}
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.

<CodeGroup>
  ```bash On disk theme={null}
  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"
  ```

  ```python In memory theme={null}
  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"])
  ```
</CodeGroup>

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](/documentation/integrating-tako/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:

```csv theme={null}
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](/documentation/integrating-tako/search/for-coding-agent) or [Answer](/documentation/integrating-tako/answer/for-coding-agent) — 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`](/documentation/integrating-tako/search/for-coding-agent#choosing-sources) setting.

## Common mistakes

<Warning>
  Avoid these — they are the patterns coding agents most often get wrong.
</Warning>

| 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](#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](/documentation/additional-resources/credits-and-billing#running-out-402). |
| `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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.