> ## 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.
# Search
> Search Tako knowledge cards and the web with a natural language query
## 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.
* Search returns Tako knowledge cards and web results for a natural language query — the results themselves, with no written answer on top. Use it when you want to render or post-process the cards and web results directly.
* Want a written answer over the same results? Use [Answer](/api-reference/answer) — it takes the same request body and adds a synthesized `answer`.
## Choosing sources
`sources` controls where results come from — an object whose keys are the sources to search. A source is searched only if its key is present; omit `sources` to use the default (both sources, 5 results each):
* `{ "data": {} }` — Tako knowledge cards from the curated knowledge graph.
* `{ "web": {} }` — web results.
* `{ "data": {}, "web": {} }` — both (same as omitting `sources`).
The legacy value `tako` is accepted as a synonym for `data`.
Each source takes optional per-source settings: `count` (1–20, default 5) and `include_contents` (inline the underlying data).
A result whose underlying data is downloadable includes a `content` descriptor. Pass that result's URL to [Contents](/api-reference/contents) to download it — a CSV for a Tako card, or extracted text for a web page.
## OpenAPI
````yaml POST /v3/search
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:
/v3/search:
post:
tags:
- tako
summary: Search
description: >-
Fast-pipeline knowledge search. Returns Tako cards (and web results when
requested) with no LLM synthesis.
operationId: search
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRequest'
required: true
responses:
'200':
description: Fast-pipeline search results (Tako cards + web results)
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
'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'
'408':
description: The request exceeded the processing time limit.
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
'529':
description: >-
Tako is overloaded and did not process this request. Do not retry
automatically. The response carries the header x-should-retry:
false. Send the request again later.
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
security:
- apiKey: []
components:
schemas:
SearchRequest:
properties:
query:
type: string
minLength: 1
pattern: \S
title: Query
description: Natural language search query.
examples:
- Intel vs Nvidia headcount since 2013
effort:
$ref: '#/components/schemas/SearchEffortLevel'
description: 'Search effort level: ''fast'', ''instant'', or ''deep''.'
default: fast
sources:
$ref: '#/components/schemas/Sources'
description: >-
Per-source settings. The search includes an index only if its key is
present. Omit it and Tako searches data and web with no counts set.
Tako accepts the legacy key 'tako' as a synonym for 'data'.
location:
anyOf:
- $ref: '#/components/schemas/GeoLocation'
- type: 'null'
description: >-
Optional coordinates of the end user. Resolves the location for
implicit-location queries (for example, weather) and, when
`timezone` is absent, the timezone Tako renders preview images in.
An explicit location in the query overrides these coordinates.
country_code:
type: string
title: Country Code
description: ISO 3166-1 alpha-2 country code for localization.
default: US
locale:
type: string
title: Locale
description: BCP-47 locale tag for language and formatting.
default: en-US
timezone:
anyOf:
- type: string
- type: 'null'
title: Timezone
description: >-
IANA timezone (for example, 'America/New_York') Tako renders preview
images in. Defaults to the zone at `location` when you send
coordinates. Card text keeps each surface's own timezone.
output_settings:
anyOf:
- $ref: '#/components/schemas/OutputSettings'
- type: 'null'
description: Settings that control the response shape.
include_related:
anyOf:
- type: integer
maximum: 20
minimum: 1
- type: 'null'
title: Include Related
description: >-
Applies to POST /v3/search only. Return follow-up query suggestions
in `related`. Omit this field to disable them. The value sets the
maximum number of suggestions, from 1 to 20. POST /v1/answer accepts
this field but ignores it: the answer response has no `related`
field.
variable_cost:
anyOf:
- type: boolean
- type: 'null'
title: Variable Cost
description: >-
Return data from sources priced per unit, such as web traffic and
SEO data. Such data adds a charge above the request's own price,
which the response's `usage` object reports as `variable_cost`. Set
it to false and each such card is a placeholder with its title and
no data points. Leave it out and your account's default applies: on
for a contract account with signed terms, off otherwise. A contract
account without signed terms gets placeholders whatever you send.
additionalProperties: false
type: object
required:
- query
title: SearchRequest
description: Shared request for POST /api/v3/search and POST /api/v1/answer.
SearchResponse:
properties:
cards:
items:
$ref: '#/components/schemas/TakoCard'
type: array
title: Cards
web_results:
items:
$ref: '#/components/schemas/WebResult'
type: array
title: Web Results
request_id:
type: string
title: Request Id
usage:
anyOf:
- $ref: '#/components/schemas/Usage'
- type: 'null'
related:
anyOf:
- items:
$ref: '#/components/schemas/RelatedSuggestion'
type: array
- type: 'null'
title: Related
description: >-
Follow-up queries you can run next. Set `include_related` on the
request to receive them. Absent when you did not ask for them, or
when Tako found none.
results:
anyOf:
- items:
$ref: '#/components/schemas/FlatResult'
type: array
- type: 'null'
title: Results
description: >-
Cards and web results as one list, present only when the request set
output_settings.flat_results. cards and web_results are then empty.
type: object
required:
- request_id
title: SearchResponse
BaseAPIError:
properties:
error_message:
type: string
title: Error Message
error_type:
$ref: '#/components/schemas/APIErrorType'
type: object
required:
- error_message
- error_type
title: BaseAPIError
SearchEffortLevel:
type: string
enum:
- fast
- instant
- deep
title: SearchEffortLevel
description: >-
Public effort taxonomy for search and answer. FAST is the default.
INSTANT serves cached embeds without a new data retrieval and works in
all
environments. On /v1/answer it also writes the answer with the fastest
synthesis model, so it trades answer quality for latency. On /v1/answer
FAST
and DEEP both write the answer with a stronger model. DEEP also widens
Tako
retrieval and adds a second, higher-quality reranking pass; it's slower
and
bills at a premium tier.
Sources:
properties:
data:
$ref: '#/components/schemas/DataSourceSettings'
description: >-
Tako data source (curated knowledge). The search includes it only if
present. Tako accepts the legacy key 'tako' as a synonym.
web:
$ref: '#/components/schemas/WebSourceSettings'
description: Web source. The search includes it only if present.
additionalProperties: false
type: object
minProperties: 1
title: Sources
description: |-
Per-source settings. The search includes an index only if its field is
present.
The Tako data source is named `data`. Tako still accepts the legacy key
`tako` as a synonym and maps it to `data` before validation.
GeoLocation:
properties:
latitude:
type: number
maximum: 90
minimum: -90
title: Latitude
description: Latitude of the end user (degrees, -90 to 90).
longitude:
type: number
maximum: 180
minimum: -180
title: Longitude
description: Longitude of the end user (degrees, -180 to 180).
additionalProperties: false
type: object
required:
- latitude
- longitude
title: GeoLocation
OutputSettings:
properties:
image_dark_mode:
anyOf:
- type: boolean
- type: 'null'
title: Image Dark Mode
description: >-
Whether to render card preview images in dark mode. Omit it and Tako
renders dark.
force_refresh:
type: boolean
title: Force Refresh
description: >-
Instant mode only, and currently informational: on these endpoints,
instant (effort='instant') always operates in build-and-refresh mode
regardless of this flag. Instant retrieves data for embeds that are
missing or stale, then creates or refreshes their static embeds.
Embeds that are already fresh (within the refresh cadence) return
as-is; Tako does not re-retrieve them. Identical queries therefore
reuse the same content-addressed embed and return a stable embed
URL.
default: false
flat_results:
anyOf:
- $ref: '#/components/schemas/FlatResultsSettings'
- type: 'null'
description: >-
Return cards and web results as one list, results, of one shape.
Send an object to turn the mode on; an empty object uses the
defaults. Omit it for the grouped cards and web_results lists.
additionalProperties: false
type: object
title: OutputSettings
description: Settings that control the response shape.
TakoCard:
properties:
card_id:
anyOf:
- type: string
- type: 'null'
title: Card Id
title:
anyOf:
- type: string
- type: 'null'
title: Title
description:
anyOf:
- type: string
- type: 'null'
title: Description
semantic_description:
anyOf:
- type: string
- type: 'null'
title: Semantic Description
webpage_url:
anyOf:
- type: string
- type: 'null'
title: Webpage Url
image_url:
anyOf:
- type: string
- type: 'null'
title: Image Url
embed_url:
anyOf:
- type: string
- type: 'null'
title: Embed Url
sources:
anyOf:
- items:
$ref: '#/components/schemas/TakoCardSource'
type: array
- type: 'null'
title: Sources
methodologies:
anyOf:
- items:
$ref: '#/components/schemas/KnowledgeCardMethodology'
type: array
- type: 'null'
title: Methodologies
source_indexes:
anyOf:
- items:
$ref: '#/components/schemas/TakoSourceIndex'
type: array
- type: 'null'
title: Source Indexes
card_type:
anyOf:
- type: string
- type: 'null'
title: Card Type
relevance:
anyOf:
- $ref: '#/components/schemas/KnowledgeCardRelevance'
- type: 'null'
description: >-
Tako's relevance label for this card, from the same ladder the flat
`results` relevance uses. On `effort: deep` an LLM scores cards as
integers 1 to 5, so a 5 is High and a 4 is Medium. A card the LLM
leaves unscored keeps its continuous retrieval score and can be High
below 5. Other efforts score continuously and can label the same
card higher.
content:
anyOf:
- $ref: '#/components/schemas/ResultContent'
- type: 'null'
exportable:
type: boolean
title: Exportable
description: >-
Whether the /contents endpoint can download this card's data. false
means the export is not available; use the card's chart and inline
preview instead. true means the export is eligible but not
guaranteed; the /contents endpoint can still return 403, so fall
back to the preview on error.
default: false
relevance_score:
anyOf:
- type: number
- type: 'null'
title: Relevance Score
description: >-
Numeric relevance of this card to the query on a 1.0-5.0 scale (5.0
= exact match; higher is more relevant). Only populated for entitled
accounts; null otherwise.
nodes:
anyOf:
- items:
$ref: '#/components/schemas/TakoCardNode'
type: array
- type: 'null'
title: Nodes
description: >-
Graph nodes (entities and metrics) behind this card. The response
includes them by default. Absent for web-only cards or when node
resolution was not available. Use each id with /v1/graph/node/{id}
for full detail (aliases, subtype), or pass ids in
sources.data.node_ids to pin these nodes in future searches.
metric_definitions:
anyOf:
- items:
$ref: '#/components/schemas/MetricDefinition'
type: array
- type: 'null'
title: Metric Definitions
description: >-
Definitions of the metrics this card displays (name + definition).
Null when no displayed metric has a definition available.
data_freshness:
anyOf:
- $ref: '#/components/schemas/DataFreshness'
- type: 'null'
description: >-
Freshness dates for the card's data: where the data ends
(coverage_end), the same point as a full date (data_as_of,
deprecated), and the last refresh date (last_updated). Null when no
date is available.
placeholder:
anyOf:
- $ref: '#/components/schemas/PlaceholderInfo'
- type: 'null'
description: >-
Set when the card is a placeholder: it carries its title and no data
points, because the request didn't include its source's data. Null
on every card that carries its data.
type: object
title: TakoCard
description: |-
A Tako knowledge card on the search and answer surfaces. It carries a
`content` download descriptor.
WebResult:
properties:
title:
type: string
title: Title
description: Title of the web page.
url:
type: string
title: Url
description: URL of the web page.
snippet:
anyOf:
- type: string
- type: 'null'
title: Snippet
description: Excerpt(s) from the page that matched the query.
source_name:
anyOf:
- type: string
- type: 'null'
title: Source Name
description: Publisher or domain name, when Tako can extract it from the URL.
publish_date:
anyOf:
- type: string
- type: 'null'
title: Publish Date
description: Publication date of the page, when available.
content:
anyOf:
- $ref: '#/components/schemas/ResultContent'
- type: 'null'
description: >-
Downloadable content descriptor for this result, fetched via the
Contents endpoint. Web results are always downloadable as text. None
for callers that do not populate it.
type: object
required:
- title
- url
title: WebResult
description: |-
A single raw web search result from the WEB source index.
Distinct from `KnowledgeCardSource` (a citation inside a synthesized
answer) and `KnowledgeCard` (a Tako visualization). Web results are
raw retrieval output — title, URL, optional snippet. They do not depend
on any LLM synthesis that may also happen over them.
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.
RelatedSuggestion:
properties:
query:
type: string
title: Query
description: >-
The follow-up query. Send it as the `query` of another search
request.
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: >-
What the query asks for, in words. Tako sets this only when the
query text does not say on its own, such as a lookup by identifier.
Most suggestions omit it because the query already reads as a
question. Tako composes it from the data on the card; no language
model writes it.
node_ids:
items:
type: string
type: array
title: Node Ids
description: >-
Graph node ids that identify the data this query asks for. Pass them
as `sources.data.node_ids` on the follow-up search to make the
search return that data. The list is empty when Tako cannot resolve
the ids; the query still works on its own.
type: object
required:
- query
title: RelatedSuggestion
description: |-
One follow-up query for the caller to run next.
A suggestion is deterministic: Tako derives it from the data a returned
card already holds. No language model writes these.
FlatResult:
properties:
type:
$ref: '#/components/schemas/TakoSourceIndex'
description: data for a Tako card, web for a web page.
title:
anyOf:
- type: string
- type: 'null'
title: Title
url:
anyOf:
- type: string
- type: 'null'
title: Url
description: The card page for a card, the page URL for a web result.
snippet:
anyOf:
- type: string
- type: 'null'
title: Snippet
description: >-
Markdown. For a card: the data description, then sections headed ###
Sources, ### Methodology, and ### Metrics, each omitted when empty.
For a web page: the matching excerpt.
published_date:
anyOf:
- type: string
- type: 'null'
title: Published Date
description: >-
Calendar date, YYYY-MM-DD, or null. For a card, the date Tako last
refreshed the data. For a web page, its publication date.
sources:
items:
$ref: '#/components/schemas/ResultSource'
type: array
title: Sources
description: Publishers behind this result.
relevance:
anyOf:
- $ref: '#/components/schemas/KnowledgeCardRelevance'
- type: 'null'
description: >-
Tako's relevance label for a card. Omitted for a web page. On
`effort: deep` an LLM scores cards as integers 1 to 5, so a 5 is
High and a 4 is Medium. A card the LLM leaves unscored keeps its
continuous retrieval score and can be High below 5. Other efforts
score continuously and can label the same card higher.
content:
anyOf:
- $ref: '#/components/schemas/ResultContent'
- type: 'null'
image_url:
anyOf:
- type: string
- type: 'null'
title: Image Url
description: Chart image for a card. Omitted for a web page.
card_id:
anyOf:
- type: string
- type: 'null'
title: Card Id
description: Tako card id. Omitted for a web page.
type: object
required:
- type
title: FlatResult
description: 'One row of results: a Tako card or a web page in the same shape.'
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
DataSourceSettings:
properties:
count:
anyOf:
- type: integer
maximum: 20
minimum: 1
- type: 'null'
title: Count
description: >-
Maximum number of data cards to return, 1 to 20. Omit it and Tako
uses 5, unless a result cap set elsewhere in the request sizes
retrieval instead. Fast and instant return at most 4 cards and deep
at most 8, whatever count you send.
include_contents:
type: boolean
title: Include Contents
description: >-
Inline this source's underlying data directly in the response. For
the Tako data source, that is serialized card data (see
content_format). For web results, that is the page text.
default: false
mode:
$ref: '#/components/schemas/ContentsDeliveryMode'
description: >-
Delivery for inlined card data when include_contents is true. For
Tako cards, include_contents always returns the most-recent rows in
the response body, up to max_rows, or up to the default inline row
cap for your account if you omit max_rows. This field therefore has
no effect on Tako cards; it stays for schema stability. total_rows
and truncated on the returned content indicate when more data is
available. For a presigned download link, call POST /api/v1/contents
with mode='url'.
default: inline
content_format:
$ref: '#/components/schemas/ContentsFormat'
description: >-
Serialization for card data: 'json_compact', 'json_records', 'csv',
or 'card_json'. The first three return a row-capped preview.
'card_json' returns a rich card-type-specific JSON object under
card_data, truncated to the same row cap. Tako bills the rows it
returns on every one of the four. A card type with no card_json
shape falls back to 'json_compact' for that card.
default: json_compact
max_rows:
anyOf:
- type: integer
minimum: 1
- type: 'null'
title: Max Rows
description: >-
Maximum number of card data rows to inline when include_contents is
true. Omit it and Tako uses your account's inline row cap. That cap
is deliberately smaller than the whole card POST /api/v1/contents
returns by default: a search response inlines many cards, so the
same number bills once per card. Raise it to inline more rows, up to
the card's export_pricing.max_rows_ceiling (at most 100,000). Tako
clamps a larger value to that ceiling. Every inlined row is billed:
a flat per-card baseline fee plus the per-1,000-row rate, the same
rate POST /api/v1/contents charges. total_rows and truncated report
whether more rows remain. A single response also has a 2,000
billable-row budget and a 20,000-row total budget, both shared
across all cards. A later card can therefore return fewer rows than
you requested, or no inlined rows at all. Such a card still carries
its export_pricing quote, so you can fetch its rows with POST
/api/v1/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.
examples:
- 100
node_ids:
items:
type: string
type: array
maxItems: 20
title: Node Ids
description: >-
Graph node ids to pin into the search, from /v1/graph/search or
/v1/graph/related. For example, pin a company, one of its segments,
and a metric to get that segment's figures without wording the query
exactly. Pinned nodes always become retrieval candidates and get a
strong boost; organic results do not change. Ids are not durable
across knowledge-graph rebuilds: the search skips an id that no
longer resolves (in strict mode it simply cannot match). Malformed
ids fail the request with a 400. Max 20.
strict:
type: boolean
title: Strict
description: >-
When true, return only data cards that match at least one node in
node_ids (which must then be non-empty). When false, pinned nodes
rank first but organic results still return. Web results do not
change either way.
default: false
additionalProperties: false
type: object
title: DataSourceSettings
description: >-
Tako data (card) source settings. It adds the two contents-export
fields on top of the base count and include_contents. Web sources use
the
base SourceSettings: Tako always inlines web content as raw text, so web
carries neither field.
WebSourceSettings:
properties:
count:
anyOf:
- type: integer
maximum: 20
minimum: 1
- type: 'null'
title: Count
description: >-
Maximum number of web results to return, 1 to 20. Omit it and Tako
uses 5 on search and 3 on answer, unless a result cap set elsewhere
in the request sizes retrieval instead.
include_contents:
type: boolean
title: Include Contents
description: >-
Inline the page text of each web result in the response. Tako
returns it free of charge, on a best-effort basis: if a page's text
isn't available at search time, content.data is null. To fetch a
page directly, use POST /api/v1/contents.
default: false
category:
anyOf:
- $ref: '#/components/schemas/WebCategory'
- type: 'null'
description: >-
Restrict web results to a category. 'news' filters to news sources.
'sports' and 'finance' are accepted but have no effect yet. Omit for
a general web search.
include_domains:
items:
type: string
type: array
maxItems: 20
title: Include Domains
description: >-
Return only results from these domains. Max 20. Send a bare host
that includes a top-level domain: 'cnn.com', not 'cnn'.
exclude_domains:
items:
type: string
type: array
maxItems: 20
title: Exclude Domains
description: >-
Drop results from these domains. Max 20. Send a bare host that
includes a top-level domain: 'cnn.com', not 'cnn'.
snippet_max_chars:
anyOf:
- type: integer
maximum: 20000
minimum: 1
- type: 'null'
title: Snippet Max Chars
description: >-
Character cap on the text excerpt returned per web result, up to
20000. Omit it and Tako uses 4000 on search and 1000 on answer,
unless Tako has agreed a different cap for your account. Send a
value and Tako uses it exactly.
highlights:
type: boolean
title: Highlights
description: >-
Return query-relevant highlight passages as each web result's
snippet, instead of the opening text of the page. Highlights usually
carry the answer-bearing sentences, and stay within
snippet_max_chars. Unless you also set include_contents, Tako
requests no page text, so a page with no highlight returns snippet:
null. The snippet can also hold more than one passage from different
parts of the page, joined by ' … '. Read the snippet as a whole. Do
not cut the snippet to a fixed length. Do not quote the snippet as
one continuous sentence.
default: false
article_content_max_chars:
type: integer
maximum: 1000000
minimum: 1
title: Article Content Max Chars
description: >-
Character cap on the full article text when include_contents is
true.
default: 30000
published_after:
anyOf:
- type: string
format: date
- type: 'null'
title: Published After
description: >-
Keep only web results published on or after this date (ISO
'YYYY-MM-DD'). Tako applies the date on the provider where possible,
and always filters the returned results. Results with no known
publication date are kept. Omit for no lower bound.
published_before:
anyOf:
- type: string
format: date
- type: 'null'
title: Published Before
description: >-
Keep only web results published on or before this date (ISO
'YYYY-MM-DD'). Results with no known publication date are kept. Omit
for no upper bound.
additionalProperties: false
type: object
title: WebSourceSettings
description: |-
Web source settings. Adds category, domain filters, and character caps
on top of the base count and include_contents.
FlatResultsSettings:
properties:
max_results:
anyOf:
- type: integer
maximum: 40
minimum: 1
- type: 'null'
title: Max Results
description: >-
The number of results you want in results. The range is 1 to 40.
Each source retrieves up to this many, capped at 20, unless you gave
that source its own count, which always stands. Either way Tako cuts
the merged list to this length, dropping Low-relevance cards first,
then trailing web results, then trailing Medium-relevance cards,
then trailing High-relevance cards. High- and Medium-relevance cards
rank above every web result, so a small max_results can return cards
alone. Omit it for no cut.
snippet_max_chars:
anyOf:
- type: integer
maximum: 20000
minimum: 1
- type: 'null'
title: Snippet Max Chars
description: >-
Character cap on every snippet in results. Tako sends it to the web
source as its snippet cap and truncates card snippets by section.
Don't combine it with sources.web.snippet_max_chars; Tako rejects a
request that sets both. Omit it for no cap.
additionalProperties: false
type: object
title: FlatResultsSettings
description: |-
Settings for the flat results mode. Sending this object turns the mode
on. Send an empty object to turn it on with defaults.
TakoCardSource:
properties:
source_name:
anyOf:
- type: string
- type: 'null'
title: Source Name
description: The name of the source
examples:
- S&P Global
- The World Bank
source_description:
anyOf:
- type: string
- type: 'null'
title: Source Description
description: The description of the source
source_index:
$ref: '#/components/schemas/TakoSourceIndex'
description: The index of the source
examples:
- data
- web
url:
anyOf:
- type: string
- type: 'null'
title: Url
description: The URL of the source
examples:
- https://xignite.com
source_text:
anyOf:
- type: string
- type: 'null'
title: Source Text
description: >-
Raw excerpts retrieved from the source page — the unmodified web
content that grounded the answer. Present for WEB sources; null for
DATA sources.
type: object
required:
- source_index
title: TakoCardSource
description: |-
A source that backs a TakoCard on the SDK surfaces. It uses the
{data, web} TakoSourceIndex taxonomy.
KnowledgeCardMethodology:
properties:
methodology_name:
anyOf:
- type: string
- type: 'null'
title: Methodology Name
description: The name of the methodology
examples:
- Where the Data Comes From - S&P Global
methodology_description:
anyOf:
- type: string
- type: 'null'
title: Methodology Description
description: >-
A concise, one-sentence summary of the methodology: the source and
what it measures. When no concise summary is available, this carries
the full methodology text.
examples:
- >-
Financial metrics standardized by S&P Global from company
regulatory filings, press releases, and restatements.
type: object
required:
- methodology_name
- methodology_description
title: KnowledgeCardMethodology
TakoSourceIndex:
type: string
enum:
- data
- web
title: TakoSourceIndex
description: |-
Public source taxonomy for the SDK card surfaces (v3 search, v1 answer,
agent). It is symmetric with the request taxonomy {data, web}.
KnowledgeCardRelevance:
type: string
enum:
- High
- Medium
- Low
title: KnowledgeCardRelevance
ResultContent:
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.
type: object
title: ResultContent
description: >-
Describes the downloadable content behind a result.
Pricing: for a Tako card CSV export, the charge is a flat per-export
baseline plus a per-row CPM on every row returned, at the rate that
``export_pricing.row_cpm_usd`` publishes. Web text bills at the standard
Contents
rate on POST /v1/contents; web text inlined on a search or answer
response
is free.
The meaning of `cost` depends on the surface. On `/contents` responses,
`cost` is the actual charge, and it reconciles with what that response
billed. The exception is a `quote_only` response, where `cost` is a
prospective price: Tako neither fetched nor billed the export, and the
payload and url fields are null. On a search or answer downloadable
card, `cost` is a prospective `/contents` quote (the per-export baseline
floor) unless Tako inlined rows for the card, in which case it is what
this
response billed for the card. The billed cards sum to
`usage.data.cost_usd`, never to `usage.total_cost_usd` (which always
adds
the flat per-request compute rate).
On a search or answer WEB result, `cost` is always a prospective
`/v1/contents` quote and NEVER a charge -- including when Tako inlined
the
page text, because inlined web text is free, so the card rule above does
not
carry over. That quote arrives on `cost` alone: `export_pricing` is null
for
web text, so zeroing `cost` on an inlined result would leave a caller no
way
to price a later fetch. A response whose only inlined contents were web
text
therefore reports `usage.data` as null -- nothing was billed for data.
`export_pricing` carries the `/contents` export rate, so a caller can
compute the full charge of a later export before fetching: baseline_usd
+
row_cpm_usd * billed_rows / 1000 + sum over classes c of
premium_row_cpm_usd[c] * premium_rows[c] / 1000, where `billed_rows` is
the
SMALLER of the rows the export returns and `max_rows` clamped to
`max_rows_ceiling`, `premium_rows` is this item's per-class count, and
the
premium term applies only to an export that passes `premium=true`. One
formula covers every format, card_json included: every export returns no
more rows than that cap, so a card with fewer rows than the cap bills
only
the rows it returns. `row_cpm_usd` is the CALLER'S rate -- 0 where their
row
charges are waived, the same waiver a billed inline card's `cost` uses,
and
/contents resolves it too. `export_pricing` is null for web text
and non-downloadable content.
Do NOT combine `cost` with `export_pricing` on a billed inline card.
There,
`cost` is the amount THIS response charged, over the rows this response
inlined, so it is not a `/contents` price for the same card: the two
cover
different row counts, because a search response's default inline cap is
far
smaller than what `/contents` returns. Read `cost` for what this
response
billed. Use `export_pricing` alone
to price a `/contents` export of the same card.
Tako populates exactly one payload group once it delivers contents:
`data` (CSV or web text), `records` (verbose JSON), `dataset` (compact
TakoDataset), `card_data` (rich card-type-specific JSON), or `url` plus
`expires_at` (presigned download).
`content_format` names the serialization; it is null for web text and
for an undelivered quote. Read `content_format` to tell a quote from a
delivery: when it is null, this is just the quote (`cost`); fetch the
content later via the Contents endpoint.
Do NOT use "every payload field is null" as that test.
`card_data_schema`
is set on a card_json quote and on a card_json `url` delivery, where
`card_data` is null, so a caller reading absent payloads as "quote"
reads
those two as quotes.
TakoCardNode:
properties:
id:
type: string
title: Id
description: >-
Opaque, human-friendly public id (::::, where
prefix is ent for an entity or mt for a metric). Ids are not durable
across knowledge-graph rebuilds — resolve them at request time
rather than storing them.
type:
$ref: '#/components/schemas/GraphNodeType'
description: Whether the node is a metric or an entity.
name:
type: string
title: Name
description: >-
Display name. Several metrics can share a name when publishers
report different series, such as two GDP metrics; read `description`
to tell them apart.
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: >-
What the node is. For a metric, what it measures, often with its
unit and basis. For an entity, a short identification. Absent when
Tako has none.
type: object
required:
- id
- type
- name
title: TakoCardNode
description: |-
Slim graph node for the search and answer card surface
(TakoCard.nodes). It is deliberately narrower than GraphNode: it carries
no `aliases` and no `subtype`. For a node's aliases, resolve the id via
/v1/graph/node/{id}; for an entity's subtype, use /v1/graph/related.
MetricDefinition:
properties:
name:
type: string
title: Name
description: The metric's display name
examples:
- Gross Domestic Product (current US$)
definition:
type: string
title: Definition
description: Human-readable definition of the metric
type: object
required:
- name
- definition
title: MetricDefinition
description: |-
Definition of a metric shown on a card. Sourced from the metric's
ValueType definition — the same text as the in-app methodology 'Metrics'
tab.
DataFreshness:
properties:
coverage_end:
anyOf:
- type: string
- type: 'null'
title: Coverage End
description: >-
The last data point in the card's data, at the granularity of the
underlying series. An annual series reports a year (2026). A monthly
or quarterly series reports a month (2026-06). A daily or intraday
series reports a full date (2026-06-30). This value can be in the
future when the card includes projections. Null for card types
without a coverage date. The value uses ISO 8601 reduced precision,
so examine the length before you parse it. A date parser reads 2026
as 2026-01-01, which is the start of the period and not the end. On
a card with tabs, only the tab this response built is rendered, so
this date describes THAT tab -- the same card can report a different
date on a request that opens a different tab. Cache it against the
response, not against the card id.
examples:
- '2026'
- 2026-06
- '2026-06-30'
data_as_of:
anyOf:
- type: string
- type: 'null'
title: Data As Of
description: >-
Deprecated: use coverage_end. The same point, always as a full ISO
date (YYYY-MM-DD). For a series whose points are periods, this date
is the period boundary. It is not a day on which Tako observed a
value.
deprecated: true
examples:
- '2026-10-01'
last_updated:
anyOf:
- type: string
- type: 'null'
title: Last Updated
description: >-
Date Tako last refreshed the underlying data, as an ISO date
(YYYY-MM-DD). On a card with tabs this is the ACTIVE tab's refresh
date, for the same reason coverage_end is tab-scoped: only the tab
this response built is rendered.
examples:
- '2026-07-14'
type: object
title: DataFreshness
description: |-
When the card's data ends and when Tako last refreshed it. Either field
may be null when that date is not available for the card type.
PlaceholderInfo:
properties:
withheld_source:
type: string
title: Withheld Source
description: The name of the source whose data the card withholds.
type: object
required:
- withheld_source
title: PlaceholderInfo
description: Why a card carries no data points.
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.
ResultSource:
properties:
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: Publisher name.
examples:
- S&P Global
- bea.gov
url:
anyOf:
- type: string
- type: 'null'
title: Url
description: Publisher URL.
examples:
- https://www.bea.gov
type: object
title: ResultSource
description: One publisher behind a flat result.
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).
WebCategory:
type: string
enum:
- news
- sports
- finance
title: WebCategory
description: |-
Web search category filter. Only 'news' maps to a provider category
today; 'sports' and 'finance' are accepted but have no effect yet.
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``).
GraphNodeType:
type: string
enum:
- metric
- entity
title: GraphNodeType
description: >-
A `metric` is a measurable quantity, such as GDP; an `entity` is what
one is measured for, such as France.
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.