> ## 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.
# Contents
> Download the data behind a search result
export const ContentsContextWarning = () =>
Don't read a large export into a model's context. 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 max_rows.
;
## Notes
* To authenticate, you'll need a [Tako API key](https://tako.com/console/api-keys). 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](/api-reference/search-v3) or [Answer](/api-reference/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`.
## OpenAPI
````yaml POST /v1/contents
openapi: 3.1.0
info:
title: Knowledge Search API
version: 1.0.0
servers:
- url: https://tako.com/api/
description: Tako Production API Server
security: []
paths:
/v1/contents:
post:
tags:
- tako
summary: Download content
description: >-
Download the content behind a search result: a CSV of a Tako card's
underlying data, or the full text of a web page. Returns a short-lived
presigned download URL. Send `content_format: card_json` for a rich,
card-type-specific JSON object under `card_data` (for example a weather
forecast with hourly and daily records). A card_json export is truncated
to `max_rows` like every other format, so Tako never delivers more
record rows than it bills. A card whose record array is unbounded caps
that array at the platform export ceiling and sets `truncated`. A card
type without a card_json shape returns 422. A card returns 403 when Tako
cannot export its data. A data provider that does not permit export and
a card whose sources Tako cannot confirm both return 403, and the error
message states which. Send `quote_only: true` to get only the export's
price (`cost` + `export_pricing`) with an empty payload. A quote charges
nothing, fetches nothing, and calls no data provider. Every format
prices a quote from `max_rows`, so the quote is an upper bound on the
charge and never falls below it.
operationId: contents
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContentsRequest'
required: true
responses:
'200':
description: >-
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.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentsResponse'
'400':
description: Invalid request data (validation or malformed body).
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
'401':
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
'403':
description: >-
Action not permitted for this resource. For a data export, either a
data provider does not permit export, or Tako cannot confirm the
data sources for the card. The message states which.
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
'404':
description: The requested resource does not exist or has no exportable data.
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
'422':
description: >-
The card can't be served in the requested form. The response body's
error_type names the case. UNSUPPORTED_CONTENT_FORMAT: this card
type doesn't support content_format='card_json'; use 'csv',
'json_records', or 'json_compact' for that card. PLACEHOLDER_CARD:
the card is a placeholder whose data is withheld from this caller,
and every content format refuses it. VARIABLE_COST_NOT_REQUESTED:
the card's data comes from a variable-cost source that is not served
to this caller. Both apply to an MPP request and to a contract
account whose terms are not signed yet. Any other caller gets the
card's data. For an MPP request, call the API with an API key. For a
contract account, contact your account manager to sign terms.
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
'503':
description: >-
An upstream data provider is temporarily unavailable or
rate-limited. Retry after the interval in the Retry-After header.
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
security:
- apiKey: []
components:
schemas:
ContentsRequest:
properties:
url:
type: string
title: Url
description: >-
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.
examples:
- https://tako.com/card/abc123
mode:
$ref: '#/components/schemas/ContentsDeliveryMode'
description: >-
Delivery mode. 'url' returns a presigned download link. 'inline'
returns the content in the response body: card data up to 2,000 rows
unless max_rows asks for more, up to the card's
export_pricing.max_rows_ceiling, at most 100,000 (with total_rows
and truncated reported), or web text. A card export can hold up to
100,000 rows. Don't read a large export directly into a model's
context: 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
the agent parse it with code. Give the model only the rows or
results it needs. To cap the export instead, set max_rows.
default: url
content_format:
$ref: '#/components/schemas/ContentsFormat'
description: >-
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).
default: csv
max_rows:
anyOf:
- type: integer
minimum: 1
- type: 'null'
title: Max Rows
description: >-
Optional cap on the rows a Tako card export returns and is priced
against. When omitted, it depends on mode: 'url' returns the whole
card, up to the card's export_pricing.max_rows_ceiling (at most
100,000 rows), and 'inline' returns up to 2,000 rows. Tako clamps
larger values to that ceiling. 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 forecast. A card without a date
column keeps its first rows instead. Sports cards cut differently: a
league schedule keeps the tab the card shows, then the tabs nearest
to it, and a game, standings, or team stats card keeps an even share
of each table. 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, a forecast or ranking keeps its first records,
and those sports cards keep rows from the same tabs and tables as
their csv. 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. A card
export can hold up to 100,000 rows. Don't read a large export
directly into a model's context: 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 the agent parse it with code. Give the model
only the rows or results it needs. To cap the export instead, set
max_rows.
examples:
- 100
max_chars:
type: integer
maximum: 1000000
minimum: 1
title: Max Chars
description: >-
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.
default: 1000000
examples:
- 50000
quote_only:
type: boolean
title: Quote Only
description: >-
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. An omitted
`max_rows` defaults the way a real export does: the whole card for
mode 'url', and 2,000 rows for 'inline'. The quote reads `mode` only
for that default. 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. For a card with data from a source priced per
unit, the quote also covers the most that data can charge, which
`export_pricing` reports as `variable_cost_max_usd`. 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.
default: false
premium:
type: boolean
title: Premium
description: >-
When true, reveal premium cells and bill them. A card's premium
columns (see manifest[].premium_class) are withheld by default: a
withheld cell reads [premium: withheld] in CSV and is null in JSON
formats. 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.
default: false
highlights:
anyOf:
- $ref: '#/components/schemas/ContentsHighlights'
- type: 'null'
description: >-
Return only the passages of a web page that match highlights.query,
instead of its full text. The passages arrive in the same text
payload, joined with ' … ', and max_chars doesn't apply. Tako card
URLs reject it, and so do accounts whose web provider can't return
highlights. It bills at the same flat rate as full text.
additionalProperties: false
type: object
required:
- url
title: ContentsRequest
description: >-
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).
ContentsResponse:
properties:
contents:
items:
$ref: '#/components/schemas/ContentItem'
type: array
title: Contents
description: Downloadable artifacts for the requested URL.
request_id:
type: string
title: Request Id
description: Unique identifier for this request.
usage:
anyOf:
- $ref: '#/components/schemas/Usage'
- type: 'null'
type: object
required:
- request_id
title: ContentsResponse
description: >-
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.
BaseAPIError:
properties:
error_message:
type: string
title: Error Message
error_type:
$ref: '#/components/schemas/APIErrorType'
type: object
required:
- error_message
- error_type
title: BaseAPIError
ContentsDeliveryMode:
type: string
enum:
- url
- inline
title: ContentsDeliveryMode
description: |-
How contents reach the caller. URL returns a short-lived presigned file
download; INLINE returns the content in the response body.
ContentsFormat:
type: string
enum:
- csv
- json_records
- json_compact
- card_json
title: ContentsFormat
description: >-
Serialization of tabular (Tako card) data. Web content is always raw
text
and carries no content format (content_format is null).
ContentsHighlights:
properties:
query:
anyOf:
- type: string
- type: 'null'
title: Query
description: >-
The question the passages should answer. Omit it to receive the
page's leading passages.
examples:
- funded backlog fiscal 2027 guidance
max_characters:
type: integer
maximum: 20000
minimum: 100
title: Max Characters
description: Total character budget for the returned passages.
default: 4000
additionalProperties: false
type: object
title: ContentsHighlights
description: Return the passages of a web page instead of its full text.
ContentItem:
properties:
content_format:
anyOf:
- $ref: '#/components/schemas/ContentsFormat'
- type: 'null'
description: >-
Serialization of the returned card data: 'csv', 'json_records',
'json_compact', or 'card_json'. Null for web text (always returned
as raw text) and for a quote-only response (nothing was serialized).
cost:
type: number
title: Cost
description: >-
Price of this item in USD. On a /contents response this is the
amount actually billed. On a quote_only response it is a prospective
/contents export price, because Tako fetched nothing and billed
nothing. On a search or answer downloadable card it is also a
prospective price, unless Tako inlined rows for the card; then it is
the amount this response billed for the card. Use export_pricing on
its own to price a /contents export of the same card. Do not add
this value to that result: they are two prices for the same rows,
not two charges.
default: 0
data:
anyOf:
- type: string
- type: 'null'
title: Data
description: >-
Inline payload as text: card data serialized to CSV, or a web page's
extracted text. Set only for the 'csv' card format and for web text;
null otherwise. A card export can hold up to 100,000 rows. Don't
read a large export directly into a model's context: 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 the agent parse it
with code. Give the model only the rows or results it needs. To cap
the export instead, set max_rows.
records:
anyOf:
- items:
additionalProperties:
anyOf:
- type: string
- type: number
- type: integer
- type: boolean
- type: 'null'
type: object
type: array
- type: 'null'
title: Records
description: >-
Inline card data as verbose JSON: a list of row objects keyed by
column name. Set only when content_format is 'json_records'. A card
export can hold up to 100,000 rows. Don't read a large export
directly into a model's context: 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 the agent parse it with code. Give the model
only the rows or results it needs. To cap the export instead, set
max_rows.
dataset:
anyOf:
- $ref: '#/components/schemas/TakoDataset'
- type: 'null'
description: >-
Inline card data as a compact TakoDataset (typed column headers plus
positional row arrays). Set only when content_format is
'json_compact'. A card export can hold up to 100,000 rows. Don't
read a large export directly into a model's context: 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 the agent parse it
with code. Give the model only the rows or results it needs. To cap
the export instead, set max_rows.
card_data:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Card Data
description: >-
Inline card data as a card-type-specific JSON object. The
'card_type' field inside the object names its shape. Set only when
content_format is 'card_json'. Tako truncates the record rows in the
object to 'max_rows', the same cap every other format takes, and
bills the rows it returns. A card whose record array is unbounded
caps that array at the platform export ceiling and reports
'truncated': true. The payload then also carries the true count for
its record array. Card types without a card_json shape return 422 on
/contents and fall back to 'json_compact' on search and answer
include_contents. A card export can hold up to 100,000 rows. Don't
read a large export directly into a model's context: 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 the agent parse it
with code. Give the model only the rows or results it needs. To cap
the export instead, set max_rows.
card_data_schema:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Card Data Schema
description: >-
JSON Schema for the object in 'card_data'. Read it to learn the
shape of the payload without parsing the payload. Tako sets this
whenever content_format is 'card_json'. It is also set in 'url'
delivery mode and on a Contents quote, where 'card_data' is null and
the shape is all Tako returns. A search or answer card that you did
not ask to inline carries a price but no schema. The 'title' field
and the 'card_type' default inside the schema name the shape. The
schema describes the payload type, so 'card_data' can omit a field
the schema declares: Tako drops a measure the provider did not
supply. Null for every other content_format and for web text.
url:
anyOf:
- type: string
- type: 'null'
title: Url
description: >-
Presigned download URL for the content, returned in 'url' delivery
mode. Null for inline delivery and for quotes; pair with expires_at.
expires_at:
anyOf:
- type: string
- type: 'null'
title: Expires At
description: >-
ISO-8601 timestamp after which the presigned url stops working. Null
whenever url is null.
total_rows:
anyOf:
- type: integer
- type: 'null'
title: Total Rows
description: >-
Total number of rows in the card's data, independent of how many
rows were returned. Compare with the rows returned to tell whether a
larger max_rows returns more. A card that lists a capped slice of a
larger set, such as the 30 soonest-closing of 330 open
solicitations, has only that slice as its data, so total_rows is 30
and total_matching gives the set's size. On an agent run card, it's
set for a card whose rows are stored with the card, such as a people
list, and null for other agent run cards. Null for web text.
total_matching:
anyOf:
- type: integer
- type: 'null'
title: Total Matching
description: >-
Size of the whole set behind a card that lists a capped slice of it,
such as 330 for a card listing the 30 soonest-closing of 330 open
solicitations. It's the count the card's description states, and
it's the same on every content format. A larger max_rows doesn't
return more of that set. Tako reports it for the cards that list
such a slice: open solicitations, international tenders, a federal
agency's contracts, and a company's news. Null when the card's rows
are the whole set, when Tako doesn't count the set (truncated is
still true), and for web text.
truncated:
type: boolean
title: Truncated
description: >-
True when the card has more rows than Tako returned. Tako caps a
card at the request max_rows or at the card's max_rows_ceiling (at
most 100,000), and then total_rows is larger than the rows returned.
It's also true when the card itself lists a capped slice of a larger
set; then total_matching gives the set's size when Tako counts it.
An inline /contents export that omits max_rows returns up to 2,000
rows. On a search or answer response, all cards share a budget of
2,000 billable rows and a budget of 20,000 inline rows, both spent
in card order, so a later card can return fewer rows than max_rows
asked for. A card the billable budget can no longer pay for still
returns a small preview. A card that arrives after the inline budget
runs out returns no inline rows, and its export_pricing still prices
a /contents export of them.
default: false
export_pricing:
anyOf:
- $ref: '#/components/schemas/ExportPricing'
- type: 'null'
description: >-
Rate card for a downloadable card CSV, so a caller can compute a
full export's cost before fetching. Null for web text and other
non-downloadable content.
manifest:
anyOf:
- items:
$ref: '#/components/schemas/ColumnDescriptor'
type: array
- type: 'null'
title: Manifest
description: >-
Per-column metadata, one entry per exported column, in column order:
entry i describes column i (CSV header i, json_records key i, or
dataset.columns[i]). Each entry carries name (the column header),
dtype, unit, metric, entity, and premium_class. On an agent run
card, it's set wherever total_rows is. Null for web text and for
other quotes that carry no tabular columns.
premium:
type: boolean
title: Premium
description: >-
True when this item's premium cells are revealed: a /contents
response to premium=true. False on every search and answer card and
on a /contents response without the flag. There, a withheld premium
cell reads [premium: withheld] in CSV and is null in JSON formats,
and redacted_cells says which rows held a value.
default: false
premium_rows:
anyOf:
- additionalProperties:
type: integer
type: object
- type: 'null'
title: Premium Rows
description: >-
Per premium class ('company_record', 'person_contact'), the number
of delivered rows with at least one non-null cell in a column of
that class, whether revealed or withheld. Multiply by
export_pricing.premium_row_cpm_usd[class] / 1000 to price the
premium part of an export before asking for it. A row with cells of
two classes counts once in each. Empty for a card with no premium
columns; null for web text. On an agent run card, it counts every
row of the card, so a premium=true export of all total_rows rows
bills exactly these rows when total_rows is within max_rows_ceiling.
It's set wherever total_rows is.
redacted_cells:
anyOf:
- additionalProperties:
items:
type: integer
type: array
type: object
- type: 'null'
title: Redacted Cells
description: >-
Column header to the 0-based positions, among the delivered rows,
whose premium value was withheld. Present only when a premium cell
was withheld; null when premium=true, when nothing was withheld, and
for web text. Positions index the delivered rows: CSV data rows in
order, json_records entries, or dataset.rows. In CSV, the same cells
read [premium: withheld]; a premium cell with no value is blank.
source_url:
type: string
title: Source Url
description: The originating result URL from the request.
type: object
required:
- source_url
title: ContentItem
description: >-
A single downloadable artifact.
It inherits `content_format`, `cost`, the payload fields (`data`,
`records`, `dataset`, `total_rows`, `truncated`), and the presigned
`url`
and `expires_at` from ResultContent. URL mode populates `url` and
`expires_at`. INLINE mode populates one of the payload fields and leaves
`url` and `expires_at` null. A `quote_only` request yields a third
shape:
`cost` (plus `export_pricing` for a card) with every payload and url
field null and `content_format` null — the price of the export, with
nothing fetched or charged.
`card_data_schema` is the one field that does NOT follow that rule: a
card_json quote and a card_json `url` delivery both return it beside a
null
`card_data`, because the shape is what those two shapes have to offer.
Test
`content_format` for null to tell a quote from a delivery; a null
payload
field cannot do it.
Usage:
properties:
total_cost_usd:
type: number
title: Total Cost Usd
description: >-
Total quoted USD cost of this request: the sum of the components
present.
compute:
anyOf:
- $ref: '#/components/schemas/UsageCompute'
- type: 'null'
description: >-
Compute cost breakdown. Present only on surfaces with a compute step
(absent for contents).
data:
anyOf:
- $ref: '#/components/schemas/UsageData'
- type: 'null'
description: >-
Inline-data cost breakdown. Present only when the surface emitted
billable inline data.
variable_cost:
anyOf:
- $ref: '#/components/schemas/UsageVariableCost'
- type: 'null'
description: >-
Variable-cost charge. Present only when the data a request or agent
run served had a per-unit minimum above its own price: on a search,
answer or contents request that set variable_cost, and on an agent
run once it completes.
type: object
required:
- total_cost_usd
title: Usage
description: |-
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.
APIErrorType:
type: string
enum:
- BAD_REQUEST
- AUTHENTICATION_ERROR
- INTERNAL_SERVER_ERROR
- RELEVANT_RESULTS_NOT_FOUND
- RATE_LIMIT_EXCEEDED
- PAYMENT_REQUIRED
- REQUEST_TIMEOUT
- FORBIDDEN
- NOT_FOUND
- SERVICE_UNAVAILABLE
- SERVICE_OVERLOADED
- UNSUPPORTED_CONTENT_FORMAT
- PLACEHOLDER_CARD
- VARIABLE_COST_NOT_REQUESTED
title: APIErrorType
TakoDataset:
properties:
columns:
items:
$ref: '#/components/schemas/TakoDatasetColumn'
type: array
title: Columns
description: Ordered column headers (name + type), one per position in every row.
rows:
items:
items:
anyOf:
- type: string
- type: number
- type: integer
- type: boolean
- type: 'null'
type: array
type: array
title: Rows
description: >-
Row data as positional cell arrays aligned to `columns` order. Cells
are string/number/boolean/null; nulls are preserved, never coerced.
total_rows:
type: integer
title: Total Rows
description: >-
True total number of rows in the underlying data, before any
truncation.
truncated:
type: boolean
title: Truncated
description: >-
True when `rows` was capped and total_rows exceeds the number
returned.
ref:
type: string
title: Ref
description: Source URL the dataset was derived from (e.g. the Tako card URL).
sources:
items:
$ref: '#/components/schemas/TakoDatasetSource'
type: array
title: Sources
description: 'Provenance for the dataset: the sources the rows were drawn from.'
provenance:
type: string
enum:
- query
- web_extraction
title: Provenance
description: 'How the rows were produced: ''query'' (Tako data) or ''web_extraction''.'
default: query
redacted_cells:
anyOf:
- additionalProperties:
items:
type: integer
type: array
type: object
- type: 'null'
title: Redacted Cells
description: >-
Column name to the 0-based positions in `rows` whose premium value
was withheld; those cells are null. Set on a structured-output
dataset slot when a premium cell was withheld, and null otherwise.
An inline /contents dataset reports this on the content item
instead.
type: object
required:
- columns
- rows
- total_rows
- truncated
- ref
- sources
title: TakoDataset
description: |-
The dataset-slot envelope: exact retrieved rows as positional arrays
in `columns` order. The rows come directly from the data source; the LLM
never transcribes them.
ExportPricing:
properties:
baseline_usd:
type: number
title: Baseline Usd
description: Flat USD charged once per card export, independent of row count.
row_cpm_usd:
type: number
title: Row Cpm Usd
description: >-
USD charged per 1,000 rows delivered. Card-level rate; use this
value rather than deriving one from the card's sources. It is the
sum of the rates of the card's separately priced data feeds, or the
standard rate once for a card with none. Credited producers and
cited web pages never add to it. This is 0 if your account's row
charges are waived, in which case an export costs baseline_usd
whatever its size.
premium_row_cpm_usd:
additionalProperties:
type: number
type: object
title: Premium Row Cpm Usd
description: >-
USD charged per 1,000 premium rows, keyed by premium class
('company_record', 'person_contact'), added on top of row_cpm_usd
when a /contents export passes premium=true. A premium row is a
delivered row with at least one non-null cell in a column of that
class; the item's premium_rows reports the count per class. Empty
when the card has no premium columns. Not affected by a row-charge
waiver.
free_rows:
type: integer
title: Free Rows
description: >-
Deprecated and always 0. Row allowances are gone: an account that
pays nothing per row now reports row_cpm_usd of 0 instead, which the
cost formula already accounts for. Stop reading this field; it will
be removed.
default: 0
deprecated: true
max_rows_ceiling:
type: integer
title: Max Rows Ceiling
description: >-
Hard cap on rows a single export can return and bill; a larger
requested max_rows is clamped to this. No format bills more than the
clamped max_rows, and none bills more rows than it returns. Every
format obeys this ceiling, including card_json.
variable_cost_max_usd:
anyOf:
- type: number
- type: 'null'
title: Variable Cost Max Usd
description: >-
Set only for a card with data from a source priced per unit: the
most the source's minimum charge for an export of this card can be.
An export charges whichever is larger, its own price or that
minimum, and the quoted cost already accounts for it. The minimum is
known only after the export, so the actual charge can be lower. The
export's usage.variable_cost reports a different amount: only what
the export charged above its own price.
type: object
required:
- baseline_usd
- row_cpm_usd
- max_rows_ceiling
title: ExportPricing
description: >-
Card-CSV export pricing RATE for the /contents endpoint, published so a
caller can compute an export's cost before fetching. A /contents
export's
own price = baseline_usd + row_cpm_usd * rows / 1000 + sum over classes
c of
premium_row_cpm_usd[c] * premium_rows[c] / 1000, rows <=
max_rows_ceiling.
For a card with data from a source priced per unit, the export charges
the
larger of its own price and that source's minimum, and
variable_cost_max_usd is the most that minimum can be.
row_cpm_usd is the card-level rate and is authoritative: don't derive it
from the card's listed sources. It is the sum of the rates of the card's
separately priced data feeds. A card with no separately priced feed
bills
the standard rate once, however many sources it lists. An organization
the
card credits only as the producer of a redistributed number, and a web
page
it cites, never adds to the rate. There is no per-source breakdown. It
is
per-CALLER: an account whose row charges are waived sees 0 here, and the
same formula then yields the baseline alone, which is exactly what that
account is billed.
ColumnDescriptor:
properties:
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: >-
The column header as exported. This is the CSV header, the
json_records key, and the dataset column label for this column.
metric:
anyOf:
- type: string
- type: 'null'
title: Metric
description: What the column measures, for example 'Median Sales Price'.
entity:
anyOf:
- type: string
- type: 'null'
title: Entity
description: >-
What the column is measured FOR: the resolved values of every
dimension the series is filtered to, joined with an em dash — for
example 'Austin, TX — Condo'. A card filtered on one dimension
reports that one value. This field reports resolved display values
only and never an internal identifier.
unit:
anyOf:
- type: string
- type: 'null'
title: Unit
description: The unit of every value in the column, for example 'USD'.
dtype:
anyOf:
- $ref: '#/components/schemas/TakoDatasetColumnType'
- type: 'null'
description: The data type of the column, inferred from the exported values.
premium_class:
anyOf:
- $ref: '#/components/schemas/PremiumClass'
- type: 'null'
description: >-
Set when the column is premium: 'company_record' or
'person_contact'. Unless the export passed premium=true, a cell that
held a value reads [premium: withheld] in CSV and is null in JSON
formats, so a CSV reader can't parse this column as its dtype; the
item's redacted_cells says which rows held a value. Null for every
other column.
type: object
title: ColumnDescriptor
description: >-
Structured description of one exported value column.
Producers set the semantic parts they know (``metric``, ``entity``,
``unit``). ``name`` and ``dtype`` are filled centrally: ``name`` is the
rendered canonical header (set by ``apply_descriptor_names``), and
``dtype``
is inferred from the real column data in ``finalize_export_frame``. A
producer-set ``dtype`` would drift from the cells, and a producer cannot
know
the disambiguated ``name`` before the whole frame is rendered.
In the exported manifest ``name`` equals the column's actual header, and
the
manifest is positionally aligned with the exported columns (manifest
entry
``i`` describes column ``i``).
UsageCompute:
properties:
cost_usd:
type: number
title: Cost Usd
description: USD cost of running the operation.
type: object
required:
- cost_usd
title: UsageCompute
description: |-
The cost of running the operation. Absent on surfaces with no compute
step (contents).
UsageData:
properties:
cost_usd:
type: number
title: Cost Usd
description: USD cost of the inline data delivered in the response.
datasets:
type: integer
title: Datasets
description: Number of billed datasets or content items included in the response.
data_points:
anyOf:
- type: integer
- type: 'null'
title: Data Points
description: Number of billed quantitative data points included in the response.
type: object
required:
- cost_usd
- datasets
title: UsageData
description: |-
The cost and quantity of data delivered in the response.
`datasets` counts billed datasets or content items. `data_points` counts
billed quantitative values in generated answer output.
UsageVariableCost:
properties:
cost_usd:
type: number
title: Cost Usd
description: USD cost of the variable-cost charge.
type: object
required:
- cost_usd
title: UsageVariableCost
description: |-
The variable-cost charge: the per-unit minimum of a variable-cost source
the response served, above the response's own price.
TakoDatasetColumn:
properties:
name:
type: string
title: Name
description: Column name.
type:
$ref: '#/components/schemas/TakoDatasetColumnType'
description: >-
Logical column type: 'string', 'number', 'boolean', 'date', or
'datetime'. Temporal cells are ISO-8601 strings.
unit:
anyOf:
- type: string
- type: 'null'
title: Unit
description: >-
Structured unit for the column values, e.g. 'USD billions', '%'.
Null when unitless.
type: object
required:
- name
- type
title: TakoDatasetColumn
description: Typed header entry; `type` is the JSON-facing column type.
TakoDatasetSource:
properties:
name:
type: string
title: Name
description: Human-readable source name (e.g. 'FRED', 'S&P Global').
index:
type: string
enum:
- data
- web
title: Index
description: 'Source index the rows came from: ''data'' (Tako) or ''web''.'
default: data
type: object
required:
- name
title: TakoDatasetSource
description: |-
Per-dataset provenance entry. `index` names the source index, not a
citation display number. It is "data" for every dataset today — web
content never fills a dataset slot.
TakoDatasetColumnType:
type: string
enum:
- string
- number
- boolean
- date
- datetime
title: TakoDatasetColumnType
description: |-
Logical column type declared in a TakoDataset header. Temporal cells
are ISO-8601 strings. Each column declares 'date' or 'datetime' on its
own: a temporal column whose non-null values are all timezone-naive
midnights declares 'date'.
PremiumClass:
type: string
enum:
- person_contact
- company_record
title: PremiumClass
description: >-
The price class of a premium column. Person and company records are
licensed at different per-record rates.
securitySchemes:
apiKey:
type: apiKey
name: X-API-Key
in: header
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.