Skip to main content
POST
Download content

Notes

  • To authenticate, you’ll need a Tako API key. It’s best practice to store it as an environment variable to avoid hardcoding sensitive credentials in your code.
  • Contents downloads the data behind a result returned by Search or Answer. Pass the result’s URL and Tako returns a short-lived download URL — a CSV of a Tako card’s data, or the 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.
A result is downloadable when it carries a content descriptor in the Search or Answer response. Use that result’s URL here — a card’s webpage_url or a web result’s url.

Authorizations

X-API-Key
string
header
required

Body

application/json

Request body for POST /api/v1/contents.

The caller passes the result URL it wants downloadable content for, and the endpoint detects the right content from the URL itself. A Tako card URL resolves to the card's underlying data. Any other URL resolves to the page's extracted full text. mode controls delivery: url returns a presigned download link, and inline returns the content in the response. content_format selects the card serialization (csv, json_records, json_compact, or card_json); web URLs ignore it (always text).

url
string
required

The result URL to fetch downloadable content for (a TakoCard.webpage_url or a WebResult.url). A Tako card URL yields a CSV of the card's data; any other URL yields the page's extracted text.

Example:

"https://tako.com/card/abc123"

mode
enum<string>
default:url

Delivery mode. 'url' returns a presigned download link. 'inline' returns the content in the response body: CSV data up to the 2,000-row system ceiling (with total_rows and truncated reported), or web text.

Available options:
url,
inline
content_format
enum<string>
default:csv

Serialization for Tako card data: 'csv', 'json_records', 'json_compact', or 'card_json' (a rich card-type-specific JSON object; not all card types support it). Ignored for web URLs (always text).

Available options:
csv,
json_records,
json_compact,
card_json
max_rows
integer | null

Optional cap on the rows a Tako card export returns and is priced against. When omitted, it defaults to the whole card, up to the 2,000-row system ceiling (Tako clamps larger values). When a card holds more rows than the cap, csv, json_records, and json_compact keep the rows with the latest dates, counting back from the card's latest date even when that date is in the future, as on a schedule or a forecast. A card without a date column keeps its first rows instead. The kept rows stay in the card's own order. card_json cuts each card type its own way: a price or indicator series keeps its newest readings, and a forecast, schedule, or ranking keeps its first records. Every row returned bills at the per-1,000-row rate, on top of the flat per-export baseline. Tako never bills more rows than it returns, so a card holding fewer rows than this cap bills only what it holds. Every card format returns the rows up to this cap and bills them, including card_json. Web URLs ignore this field.

Required range: x >= 1
Example:

100

max_chars
integer
default:1000000

Character cap on extracted web page text. Ignored for Tako card URLs (they use max_rows). Omit it and Tako returns the full page text, up to the maximum this field allows. To truncate, pass a smaller value.

Required range: 1 <= x <= 1000000
Example:

50000

quote_only
boolean
default:false

When true, return only the price of the export (cost + export_pricing) without fetching content or charging. The response item's payload and url fields are null, and the request is free. One exception: a card_json quote returns 'card_data_schema', the shape the export would deliver. Test 'content_format' for null to tell a quote from a delivery. max_rows shapes the quote and defaults to the whole card, as a real export does. The request ignores mode. Every format prices a quote from max_rows, so a quote is instant and makes no call to a data provider. A quote is an upper bound on the charge: an export of a card with fewer rows than the cap bills less. A card_json export is truncated to max_rows like every other format, so the charge can never exceed the quote for the same cap. A card_json quote reports no total_rows, because it does not build the payload. The same export-safe gate applies, so an unexportable card still returns 403, and a card type with no card_json shape still returns 422.

premium
boolean
default:false

When true, reveal premium cells and bill them. A card's premium columns (see manifest[].premium_class) are null by default, and this is the only way to receive their values. The export then adds export_pricing.premium_row_cpm_usd[class] per 1,000 rows that hold a value in a column of that class, on top of the standard row rate; premium_rows on the item reports the counts. The flag has no effect on a card without premium columns and on web URLs, and is rejected with content_format=card_json, which carries no premium plumbing.

Response

Downloadable content for a result: a presigned URL plus format and cost metadata. For a quote_only request the item instead carries only the price (cost + export_pricing) with all payload and url fields null.

Response for POST /api/v1/contents.

contents is a list so that the contract stays stable if a single result ever yields multiple artifacts. Today it always carries exactly one item.

request_id
string
required

Unique identifier for this request.

contents
ContentItem · object[]

Downloadable artifacts for the requested URL.

usage
Usage · object | null

Usage for one metered request. total_cost_usd is always present (the total quoted charge). compute and data are the additive breakdown; each appears only where it applies. total_cost_usd always equals the sum of the components that appear.