{"uid":"cap_YonRNmhYLc9wQt9oojodv","slug":"tako-search-8ba77264","name":"Tako Search","description":"Search across Tako data and the web","url":"https://tako.com/api/mpp/v1/search?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","title":"SearchRequest","required":["query"],"properties":{"query":{"type":"string","title":"Query","pattern":"\\S","examples":["Intel vs Nvidia headcount since 2013"],"minLength":1,"description":"Natural language search query."},"effort":{"enum":["fast","instant","deep"],"type":"string","title":"SearchEffortLevel","description":"Public effort taxonomy for search and answer. FAST is the default.\nINSTANT serves cached embeds without a new data retrieval and works in all\nenvironments. On /v1/answer it also writes the answer with the fastest\nsynthesis model, so it trades answer quality for latency. On /v1/answer FAST\nand DEEP both write the answer with a stronger model. DEEP also widens Tako\nretrieval and adds a second, higher-quality reranking pass; it's slower and\nbills at a premium tier."},"locale":{"type":"string","title":"Locale","default":"en-US","description":"BCP-47 locale tag for language and formatting.","x-tako-published-default":"en-US on every endpoint. Converts when any endpoint infers locale from Accept-Language."},"sources":{"type":"object","title":"Sources","properties":{"web":{"type":"object","title":"WebSourceSettings","properties":{"count":{"anyOf":[{"type":"integer","maximum":20,"minimum":1},{"type":"null"}],"title":"Count","default":null,"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."},"category":{"anyOf":[{"enum":["news","sports","finance"],"type":"string","title":"WebCategory","description":"Web search category filter. Only 'news' maps to a provider category\ntoday; 'sports' and 'finance' are accepted but have no effect yet."},{"type":"null"}],"default":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."},"highlights":{"type":"boolean","title":"Highlights","default":false,"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.","x-tako-published-default":"False is off on every endpoint. Converts the day highlights become the default snippet on any endpoint."},"exclude_domains":{"type":"array","items":{"type":"string"},"title":"Exclude Domains","maxItems":20,"description":"Drop results from these domains. Max 20. Send a bare host that includes a top-level domain: 'cnn.com', not 'cnn'."},"include_domains":{"type":"array","items":{"type":"string"},"title":"Include Domains","maxItems":20,"description":"Return only results from these domains. Max 20. Send a bare host that includes a top-level domain: 'cnn.com', not 'cnn'."},"published_after":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Published After","default":null,"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."},"include_contents":{"type":"boolean","title":"Include Contents","default":false,"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.","x-tako-published-default":"False is off on every endpoint. Converts when any endpoint or plan inlines page text without being asked."},"published_before":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Published Before","default":null,"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."},"snippet_max_chars":{"anyOf":[{"type":"integer","maximum":20000,"minimum":1},{"type":"null"}],"title":"Snippet Max Chars","default":null,"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."},"article_content_max_chars":{"type":"integer","title":"Article Content Max Chars","default":30000,"maximum":1000000,"minimum":1,"description":"Character cap on the full article text when include_contents is true.","x-tako-published-default":"30000 on every endpoint; include_contents requires a web source, so no other fallback is reachable. Converts if the cap becomes per-endpoint or per-plan."}},"description":"Web source settings. Adds category, domain filters, and character caps\non top of the base count and include_contents.","additionalProperties":false},"data":{"type":"object","title":"DataSourceSettings","properties":{"mode":{"enum":["url","inline"],"type":"string","title":"ContentsDeliveryMode","description":"How contents reach the caller. URL returns a short-lived presigned file\ndownload; INLINE returns the content in the response body."},"count":{"anyOf":[{"type":"integer","maximum":20,"minimum":1},{"type":"null"}],"title":"Count","default":null,"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."},"strict":{"type":"boolean","title":"Strict","default":false,"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.","x-tako-published-default":"False is off everywhere; strict has no server-side default to fill."},"max_rows":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"title":"Max Rows","default":null,"examples":[100],"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."},"node_ids":{"type":"array","items":{"type":"string"},"title":"Node Ids","maxItems":20,"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."},"content_format":{"enum":["csv","json_records","json_compact","card_json"],"type":"string","title":"ContentsFormat","description":"Serialization of tabular (Tako card) data. Web content is always raw text\nand carries no content format (content_format is null)."},"include_contents":{"type":"boolean","title":"Include Contents","default":false,"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.","x-tako-published-default":"False is off on every endpoint. Converts when any endpoint or plan inlines contents without being asked."}},"description":"Tako data (card) source settings. It adds the two contents-export\nfields on top of the base count and include_contents. Web sources use the\nbase SourceSettings: Tako always inlines web content as raw text, so web\ncarries neither field.","additionalProperties":false}},"description":"Per-source settings. The search includes an index only if its field is\npresent.\n\nThe Tako data source is named `data`. Tako still accepts the legacy key\n`tako` as a synonym and maps it to `data` before validation.","minProperties":1,"additionalProperties":false},"location":{"anyOf":[{"type":"object","title":"GeoLocation","required":["latitude","longitude"],"properties":{"latitude":{"type":"number","title":"Latitude","maximum":90,"minimum":-90,"description":"Latitude of the end user (degrees, -90 to 90)."},"longitude":{"type":"number","title":"Longitude","maximum":180,"minimum":-180,"description":"Longitude of the end user (degrees, -180 to 180)."}},"additionalProperties":false},{"type":"null"}],"default":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."},"timezone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Timezone","default":null,"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."},"country_code":{"type":"string","title":"Country Code","default":"US","description":"ISO 3166-1 alpha-2 country code for localization.","x-tako-published-default":"US on every endpoint. Converts when any endpoint infers country from location or a header."},"variable_cost":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Variable Cost","default":null,"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."},"include_related":{"anyOf":[{"type":"integer","maximum":20,"minimum":1},{"type":"null"}],"title":"Include Related","default":null,"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."},"output_settings":{"anyOf":[{"type":"object","title":"OutputSettings","properties":{"flat_results":{"anyOf":[{"type":"object","title":"FlatResultsSettings","properties":{"max_results":{"anyOf":[{"type":"integer","maximum":40,"minimum":1},{"type":"null"}],"title":"Max Results","default":null,"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 Medium-relevance cards, then trailing web results, then trailing High-relevance cards. High-relevance cards are cut last, so a small max_results can return cards alone. A small max_results can also return web results alone, because it sizes web retrieval too and Medium-relevance cards rank below every web result. Omit it for no cut."},"snippet_max_chars":{"anyOf":[{"type":"integer","maximum":20000,"minimum":1},{"type":"null"}],"title":"Snippet Max Chars","default":null,"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."}},"description":"Settings for the flat results mode. Sending this object turns the mode\non. Send an empty object to turn it on with defaults.","additionalProperties":false},{"type":"null"}],"default":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."},"force_refresh":{"type":"boolean","title":"Force Refresh","default":false,"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.","x-tako-published-default":"Informational on every endpoint that accepts it, and False everywhere. Converts the day an endpoint acts on it and picks its own baseline."},"image_dark_mode":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Image Dark Mode","default":null,"description":"Whether to render card preview images in dark mode. Omit it and Tako renders dark."}},"description":"Settings that control the response shape.","additionalProperties":false},{"type":"null"}],"default":null,"description":"Settings that control the response shape."}},"description":"Shared request for POST /api/v3/search and POST /api/v1/answer.","additionalProperties":false},"responseSchema":{"type":"object","title":"SearchResponse","required":["request_id"],"properties":{"cards":{"type":"array","items":{"type":"object","title":"TakoCard","properties":{"nodes":{"anyOf":[{"type":"array","items":{"type":"object","title":"TakoCardNode","required":["id","type","name"],"properties":{"id":{"type":"string","title":"Id","description":"Opaque, human-friendly public id (<prefix>::<name>::<hash>, 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."},"name":{"type":"string","title":"Name"},"type":{"$ref":"#/components/schemas/GraphNodeType"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","default":null}},"description":"Slim graph node for the search and answer card surface\n(TakoCard.nodes). It is deliberately narrower than GraphNode: it carries\nno `aliases` and no `subtype`. Callers that need the full node resolve\nthe id via /v1/graph/node/{id}."}},{"type":"null"}],"title":"Nodes","default":null,"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."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","default":null},"card_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Card Id","default":null},"content":{"anyOf":[{"type":"object","title":"ResultContent","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","default":null,"description":"Presigned download URL for the content, returned in 'url' delivery mode. Null for inline delivery and for quotes; pair with expires_at."},"cost":{"type":"number","title":"Cost","default":0,"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."},"data":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data","default":null,"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."},"dataset":{"anyOf":[{"$ref":"#/components/schemas/TakoDataset"},{"type":"null"}],"default":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."},"premium":{"type":"boolean","title":"Premium","default":false,"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."},"records":{"anyOf":[{"type":"array","items":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]}}},{"type":"null"}],"title":"Records","default":null,"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."},"manifest":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/ColumnDescriptor"}},{"type":"null"}],"title":"Manifest","default":null,"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."},"card_data":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}],"title":"Card Data","default":null,"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."},"truncated":{"type":"boolean","title":"Truncated","default":false,"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."},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At","default":null,"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","default":null,"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."},"premium_rows":{"anyOf":[{"type":"object","additionalProperties":{"type":"integer"}},{"type":"null"}],"title":"Premium Rows","default":null,"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."},"content_format":{"anyOf":[{"$ref":"#/components/schemas/ContentsFormat"},{"type":"null"}],"default":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)."},"export_pricing":{"anyOf":[{"$ref":"#/components/schemas/ExportPricing"},{"type":"null"}],"default":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."},"redacted_cells":{"anyOf":[{"type":"object","additionalProperties":{"type":"array","items":{"type":"integer"}}},{"type":"null"}],"title":"Redacted Cells","default":null,"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."},"total_matching":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Matching","default":null,"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."},"card_data_schema":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}],"title":"Card Data Schema","default":null,"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."}},"description":"Describes the downloadable content behind a result.\n\nPricing: for a Tako card CSV export, the charge is a flat per-export\nbaseline plus a per-row CPM on every row returned, at the rate that\n``export_pricing.row_cpm_usd`` publishes. Web text bills at the standard Contents\nrate on POST /v1/contents; web text inlined on a search or answer response\nis free.\n\nThe meaning of `cost` depends on the surface. On `/contents` responses,\n`cost` is the actual charge, and it reconciles with what that response\nbilled. The exception is a `quote_only` response, where `cost` is a\nprospective price: Tako neither fetched nor billed the export, and the\npayload and url fields are null. On a search or answer downloadable\ncard, `cost` is a prospective `/contents` quote (the per-export baseline\nfloor) unless Tako inlined rows for the card, in which case it is what this\nresponse billed for the card. The billed cards sum to\n`usage.data.cost_usd`, never to `usage.total_cost_usd` (which always adds\nthe flat per-request compute rate).\n\nOn a search or answer WEB result, `cost` is always a prospective\n`/v1/contents` quote and NEVER a charge -- including when Tako inlined the\npage text, because inlined web text is free, so the card rule above does not\ncarry over. That quote arrives on `cost` alone: `export_pricing` is null for\nweb text, so zeroing `cost` on an inlined result would leave a caller no way\nto price a later fetch. A response whose only inlined contents were web text\ntherefore reports `usage.data` as null -- nothing was billed for data.\n\n`export_pricing` carries the `/contents` export rate, so a caller can\ncompute the full charge of a later export before fetching: baseline_usd +\nrow_cpm_usd * billed_rows / 1000 + sum over classes c of\npremium_row_cpm_usd[c] * premium_rows[c] / 1000, where `billed_rows` is the\nSMALLER of the rows the export returns and `max_rows` clamped to\n`max_rows_ceiling`, `premium_rows` is this item's per-class count, and the\npremium term applies only to an export that passes `premium=true`. One\nformula covers every format, card_json included: every export returns no\nmore rows than that cap, so a card with fewer rows than the cap bills only\nthe rows it returns. `row_cpm_usd` is the CALLER'S rate -- 0 where their row\ncharges are waived, the same waiver a billed inline card's `cost` uses, and\n/contents resolves it too. `export_pricing` is null for web text\nand non-downloadable content.\n\nDo NOT combine `cost` with `export_pricing` on a billed inline card. There,\n`cost` is the amount THIS response charged, over the rows this response\ninlined, so it is not a `/contents` price for the same card: the two cover\ndifferent row counts, because a search response's default inline cap is far\nsmaller than what `/contents` returns. Read `cost` for what this response\nbilled. Use `export_pricing` alone\nto price a `/contents` export of the same card.\n\nTako populates exactly one payload group once it delivers contents:\n`data` (CSV or web text), `records` (verbose JSON), `dataset` (compact\nTakoDataset), `card_data` (rich card-type-specific JSON), or `url` plus\n`expires_at` (presigned download).\n`content_format` names the serialization; it is null for web text and\nfor an undelivered quote. Read `content_format` to tell a quote from a\ndelivery: when it is null, this is just the quote (`cost`); fetch the\ncontent later via the Contents endpoint.\n\nDo NOT use \"every payload field is null\" as that test. `card_data_schema`\nis set on a card_json quote and on a card_json `url` delivery, where\n`card_data` is null, so a caller reading absent payloads as \"quote\" reads\nthose two as quotes."},{"type":"null"}],"default":null},"sources":{"anyOf":[{"type":"array","items":{"type":"object","title":"TakoCardSource","required":["source_index"],"properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","default":null,"examples":["https://xignite.com"],"description":"The URL of the source"},"source_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Name","default":null,"examples":["S&P Global","The World Bank"],"description":"The name of the source"},"source_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Text","default":null,"description":"Raw excerpts retrieved from the source page — the unmodified web content that grounded the answer. Present for WEB sources; null for DATA sources."},"source_index":{"$ref":"#/components/schemas/TakoSourceIndex","examples":["data","web"],"description":"The index of the source"},"source_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Description","default":null,"description":"The description of the source"}},"description":"A source that backs a TakoCard on the SDK surfaces. It uses the\n{data, web} TakoSourceIndex taxonomy."}},{"type":"null"}],"title":"Sources","default":null},"card_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Card Type","default":null},"embed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Embed Url","default":null},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url","default":null},"relevance":{"anyOf":[{"enum":["High","Medium","Low"],"type":"string","title":"KnowledgeCardRelevance"},{"type":"null"}],"default":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."},"exportable":{"type":"boolean","title":"Exportable","default":false,"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."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","default":null},"placeholder":{"anyOf":[{"type":"object","title":"PlaceholderInfo","required":["withheld_source"],"properties":{"withheld_source":{"type":"string","title":"Withheld Source","description":"The name of the source whose data the card withholds."}},"description":"Why a card carries no data points."},{"type":"null"}],"default":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."},"webpage_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Webpage Url","default":null},"methodologies":{"anyOf":[{"type":"array","items":{"type":"object","title":"KnowledgeCardMethodology","required":["methodology_name","methodology_description"],"properties":{"methodology_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Methodology Name","examples":["Where the Data Comes From - S&P Global"],"description":"The name of the methodology"},"methodology_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Methodology Description","examples":["Financial metrics standardized by S&P Global from company regulatory filings, press releases, and restatements."],"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."}}}},{"type":"null"}],"title":"Methodologies","default":null},"data_freshness":{"anyOf":[{"type":"object","title":"DataFreshness","properties":{"data_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data As Of","default":null,"examples":["2026-10-01"],"deprecated":true,"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."},"coverage_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Coverage End","default":null,"examples":["2026","2026-06","2026-06-30"],"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."},"last_updated":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Updated","default":null,"examples":["2026-07-14"],"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."}},"description":"When the card's data ends and when Tako last refreshed it. Either field\nmay be null when that date is not available for the card type."},{"type":"null"}],"default":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."},"source_indexes":{"anyOf":[{"type":"array","items":{"enum":["data","web"],"type":"string","title":"TakoSourceIndex","description":"Public source taxonomy for the SDK card surfaces (v3 search, v1 answer,\nagent). It is symmetric with the request taxonomy {data, web}."}},{"type":"null"}],"title":"Source Indexes","default":null},"relevance_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Relevance Score","default":null,"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."},"metric_definitions":{"anyOf":[{"type":"array","items":{"type":"object","title":"MetricDefinition","required":["name","definition"],"properties":{"name":{"type":"string","title":"Name","examples":["Gross Domestic Product (current US$)"],"description":"The metric's display name"},"definition":{"type":"string","title":"Definition","description":"Human-readable definition of the metric"}},"description":"Definition of a metric shown on a card. Sourced from the metric's\nValueType definition — the same text as the in-app methodology 'Metrics'\ntab."}},{"type":"null"}],"title":"Metric Definitions","default":null,"description":"Definitions of the metrics this card displays (name + definition). Null when no displayed metric has a definition available."},"semantic_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Semantic Description","default":null}},"description":"A Tako knowledge card on the search and answer surfaces. It carries a\n`content` download descriptor."},"title":"Cards"},"usage":{"anyOf":[{"type":"object","title":"Usage","required":["total_cost_usd"],"properties":{"data":{"anyOf":[{"type":"object","title":"UsageData","required":["cost_usd","datasets"],"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","default":null,"description":"Number of billed quantitative data points included in the response."}},"description":"The cost and quantity of data delivered in the response.\n\n`datasets` counts billed datasets or content items. `data_points` counts\nbilled quantitative values in generated answer output."},{"type":"null"}],"default":null,"description":"Inline-data cost breakdown. Present only when the surface emitted billable inline data."},"compute":{"anyOf":[{"type":"object","title":"UsageCompute","required":["cost_usd"],"properties":{"cost_usd":{"type":"number","title":"Cost Usd","description":"USD cost of running the operation."}},"description":"The cost of running the operation. Absent on surfaces with no compute\nstep (contents)."},{"type":"null"}],"default":null,"description":"Compute cost breakdown. Present only on surfaces with a compute step (absent for contents)."},"variable_cost":{"anyOf":[{"type":"object","title":"UsageVariableCost","required":["cost_usd"],"properties":{"cost_usd":{"type":"number","title":"Cost Usd","description":"USD cost of the variable-cost charge."}},"description":"The variable-cost charge: the per-unit minimum of a variable-cost source\nthe response served, above the response's own price."},{"type":"null"}],"default":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."},"total_cost_usd":{"type":"number","title":"Total Cost Usd","description":"Total quoted USD cost of this request: the sum of the components present."}},"description":"Usage for one metered request. `total_cost_usd` is always present (the\ntotal quoted charge). `compute` and `data` are the additive breakdown;\neach appears only where it applies. total_cost_usd always equals the sum\nof the components that appear."},{"type":"null"}],"default":null},"related":{"anyOf":[{"type":"array","items":{"type":"object","title":"RelatedSuggestion","required":["query"],"properties":{"query":{"type":"string","title":"Query","description":"The follow-up query. Send it as the `query` of another search request."},"node_ids":{"type":"array","items":{"type":"string"},"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."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","default":null,"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."}},"description":"One follow-up query for the caller to run next.\n\nA suggestion is deterministic: Tako derives it from the data a returned\ncard already holds. No language model writes these."}},{"type":"null"}],"title":"Related","default":null,"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":[{"type":"array","items":{"type":"object","title":"FlatResult","required":["type"],"properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","default":null,"description":"The card page for a card, the page URL for a web result."},"type":{"enum":["data","web"],"type":"string","title":"TakoSourceIndex","description":"Public source taxonomy for the SDK card surfaces (v3 search, v1 answer,\nagent). It is symmetric with the request taxonomy {data, web}."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","default":null},"card_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Card Id","default":null,"description":"Tako card id. Omitted for a web page."},"content":{"anyOf":[{"type":"object","title":"ResultContent","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","default":null,"description":"Presigned download URL for the content, returned in 'url' delivery mode. Null for inline delivery and for quotes; pair with expires_at."},"cost":{"type":"number","title":"Cost","default":0,"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."},"data":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data","default":null,"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."},"dataset":{"anyOf":[{"$ref":"#/components/schemas/TakoDataset"},{"type":"null"}],"default":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."},"premium":{"type":"boolean","title":"Premium","default":false,"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."},"records":{"anyOf":[{"type":"array","items":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]}}},{"type":"null"}],"title":"Records","default":null,"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."},"manifest":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/ColumnDescriptor"}},{"type":"null"}],"title":"Manifest","default":null,"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."},"card_data":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}],"title":"Card Data","default":null,"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."},"truncated":{"type":"boolean","title":"Truncated","default":false,"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."},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At","default":null,"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","default":null,"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."},"premium_rows":{"anyOf":[{"type":"object","additionalProperties":{"type":"integer"}},{"type":"null"}],"title":"Premium Rows","default":null,"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."},"content_format":{"anyOf":[{"$ref":"#/components/schemas/ContentsFormat"},{"type":"null"}],"default":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)."},"export_pricing":{"anyOf":[{"$ref":"#/components/schemas/ExportPricing"},{"type":"null"}],"default":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."},"redacted_cells":{"anyOf":[{"type":"object","additionalProperties":{"type":"array","items":{"type":"integer"}}},{"type":"null"}],"title":"Redacted Cells","default":null,"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."},"total_matching":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Matching","default":null,"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."},"card_data_schema":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}],"title":"Card Data Schema","default":null,"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."}},"description":"Describes the downloadable content behind a result.\n\nPricing: for a Tako card CSV export, the charge is a flat per-export\nbaseline plus a per-row CPM on every row returned, at the rate that\n``export_pricing.row_cpm_usd`` publishes. Web text bills at the standard Contents\nrate on POST /v1/contents; web text inlined on a search or answer response\nis free.\n\nThe meaning of `cost` depends on the surface. On `/contents` responses,\n`cost` is the actual charge, and it reconciles with what that response\nbilled. The exception is a `quote_only` response, where `cost` is a\nprospective price: Tako neither fetched nor billed the export, and the\npayload and url fields are null. On a search or answer downloadable\ncard, `cost` is a prospective `/contents` quote (the per-export baseline\nfloor) unless Tako inlined rows for the card, in which case it is what this\nresponse billed for the card. The billed cards sum to\n`usage.data.cost_usd`, never to `usage.total_cost_usd` (which always adds\nthe flat per-request compute rate).\n\nOn a search or answer WEB result, `cost` is always a prospective\n`/v1/contents` quote and NEVER a charge -- including when Tako inlined the\npage text, because inlined web text is free, so the card rule above does not\ncarry over. That quote arrives on `cost` alone: `export_pricing` is null for\nweb text, so zeroing `cost` on an inlined result would leave a caller no way\nto price a later fetch. A response whose only inlined contents were web text\ntherefore reports `usage.data` as null -- nothing was billed for data.\n\n`export_pricing` carries the `/contents` export rate, so a caller can\ncompute the full charge of a later export before fetching: baseline_usd +\nrow_cpm_usd * billed_rows / 1000 + sum over classes c of\npremium_row_cpm_usd[c] * premium_rows[c] / 1000, where `billed_rows` is the\nSMALLER of the rows the export returns and `max_rows` clamped to\n`max_rows_ceiling`, `premium_rows` is this item's per-class count, and the\npremium term applies only to an export that passes `premium=true`. One\nformula covers every format, card_json included: every export returns no\nmore rows than that cap, so a card with fewer rows than the cap bills only\nthe rows it returns. `row_cpm_usd` is the CALLER'S rate -- 0 where their row\ncharges are waived, the same waiver a billed inline card's `cost` uses, and\n/contents resolves it too. `export_pricing` is null for web text\nand non-downloadable content.\n\nDo NOT combine `cost` with `export_pricing` on a billed inline card. There,\n`cost` is the amount THIS response charged, over the rows this response\ninlined, so it is not a `/contents` price for the same card: the two cover\ndifferent row counts, because a search response's default inline cap is far\nsmaller than what `/contents` returns. Read `cost` for what this response\nbilled. Use `export_pricing` alone\nto price a `/contents` export of the same card.\n\nTako populates exactly one payload group once it delivers contents:\n`data` (CSV or web text), `records` (verbose JSON), `dataset` (compact\nTakoDataset), `card_data` (rich card-type-specific JSON), or `url` plus\n`expires_at` (presigned download).\n`content_format` names the serialization; it is null for web text and\nfor an undelivered quote. Read `content_format` to tell a quote from a\ndelivery: when it is null, this is just the quote (`cost`); fetch the\ncontent later via the Contents endpoint.\n\nDo NOT use \"every payload field is null\" as that test. `card_data_schema`\nis set on a card_json quote and on a card_json `url` delivery, where\n`card_data` is null, so a caller reading absent payloads as \"quote\" reads\nthose two as quotes."},{"type":"null"}],"default":null},"snippet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Snippet","default":null,"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."},"sources":{"type":"array","items":{"type":"object","title":"ResultSource","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","default":null,"examples":["https://www.bea.gov"],"description":"Publisher URL."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","default":null,"examples":["S&P Global","bea.gov"],"description":"Publisher name."}},"description":"One publisher behind a flat result."},"title":"Sources","description":"Publishers behind this result."},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url","default":null,"description":"Chart image for a card. Omitted for a web page."},"relevance":{"anyOf":[{"enum":["High","Medium","Low"],"type":"string","title":"KnowledgeCardRelevance"},{"type":"null"}],"default":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."},"published_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Published Date","default":null,"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."}},"description":"One row of results: a Tako card or a web page in the same shape."}},{"type":"null"}],"title":"Results","default":null,"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."},"request_id":{"type":"string","title":"Request Id"},"web_results":{"type":"array","items":{"type":"object","title":"WebResult","required":["title","url"],"properties":{"url":{"type":"string","title":"Url","description":"URL of the web page."},"title":{"type":"string","title":"Title","description":"Title of the web page."},"content":{"anyOf":[{"type":"object","title":"ResultContent","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","default":null,"description":"Presigned download URL for the content, returned in 'url' delivery mode. Null for inline delivery and for quotes; pair with expires_at."},"cost":{"type":"number","title":"Cost","default":0,"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."},"data":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data","default":null,"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."},"dataset":{"anyOf":[{"$ref":"#/components/schemas/TakoDataset"},{"type":"null"}],"default":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."},"premium":{"type":"boolean","title":"Premium","default":false,"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."},"records":{"anyOf":[{"type":"array","items":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]}}},{"type":"null"}],"title":"Records","default":null,"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."},"manifest":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/ColumnDescriptor"}},{"type":"null"}],"title":"Manifest","default":null,"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."},"card_data":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}],"title":"Card Data","default":null,"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."},"truncated":{"type":"boolean","title":"Truncated","default":false,"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."},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At","default":null,"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","default":null,"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."},"premium_rows":{"anyOf":[{"type":"object","additionalProperties":{"type":"integer"}},{"type":"null"}],"title":"Premium Rows","default":null,"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."},"content_format":{"anyOf":[{"$ref":"#/components/schemas/ContentsFormat"},{"type":"null"}],"default":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)."},"export_pricing":{"anyOf":[{"$ref":"#/components/schemas/ExportPricing"},{"type":"null"}],"default":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."},"redacted_cells":{"anyOf":[{"type":"object","additionalProperties":{"type":"array","items":{"type":"integer"}}},{"type":"null"}],"title":"Redacted Cells","default":null,"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."},"total_matching":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Matching","default":null,"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."},"card_data_schema":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}],"title":"Card Data Schema","default":null,"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."}},"description":"Describes the downloadable content behind a result.\n\nPricing: for a Tako card CSV export, the charge is a flat per-export\nbaseline plus a per-row CPM on every row returned, at the rate that\n``export_pricing.row_cpm_usd`` publishes. Web text bills at the standard Contents\nrate on POST /v1/contents; web text inlined on a search or answer response\nis free.\n\nThe meaning of `cost` depends on the surface. On `/contents` responses,\n`cost` is the actual charge, and it reconciles with what that response\nbilled. The exception is a `quote_only` response, where `cost` is a\nprospective price: Tako neither fetched nor billed the export, and the\npayload and url fields are null. On a search or answer downloadable\ncard, `cost` is a prospective `/contents` quote (the per-export baseline\nfloor) unless Tako inlined rows for the card, in which case it is what this\nresponse billed for the card. The billed cards sum to\n`usage.data.cost_usd`, never to `usage.total_cost_usd` (which always adds\nthe flat per-request compute rate).\n\nOn a search or answer WEB result, `cost` is always a prospective\n`/v1/contents` quote and NEVER a charge -- including when Tako inlined the\npage text, because inlined web text is free, so the card rule above does not\ncarry over. That quote arrives on `cost` alone: `export_pricing` is null for\nweb text, so zeroing `cost` on an inlined result would leave a caller no way\nto price a later fetch. A response whose only inlined contents were web text\ntherefore reports `usage.data` as null -- nothing was billed for data.\n\n`export_pricing` carries the `/contents` export rate, so a caller can\ncompute the full charge of a later export before fetching: baseline_usd +\nrow_cpm_usd * billed_rows / 1000 + sum over classes c of\npremium_row_cpm_usd[c] * premium_rows[c] / 1000, where `billed_rows` is the\nSMALLER of the rows the export returns and `max_rows` clamped to\n`max_rows_ceiling`, `premium_rows` is this item's per-class count, and the\npremium term applies only to an export that passes `premium=true`. One\nformula covers every format, card_json included: every export returns no\nmore rows than that cap, so a card with fewer rows than the cap bills only\nthe rows it returns. `row_cpm_usd` is the CALLER'S rate -- 0 where their row\ncharges are waived, the same waiver a billed inline card's `cost` uses, and\n/contents resolves it too. `export_pricing` is null for web text\nand non-downloadable content.\n\nDo NOT combine `cost` with `export_pricing` on a billed inline card. There,\n`cost` is the amount THIS response charged, over the rows this response\ninlined, so it is not a `/contents` price for the same card: the two cover\ndifferent row counts, because a search response's default inline cap is far\nsmaller than what `/contents` returns. Read `cost` for what this response\nbilled. Use `export_pricing` alone\nto price a `/contents` export of the same card.\n\nTako populates exactly one payload group once it delivers contents:\n`data` (CSV or web text), `records` (verbose JSON), `dataset` (compact\nTakoDataset), `card_data` (rich card-type-specific JSON), or `url` plus\n`expires_at` (presigned download).\n`content_format` names the serialization; it is null for web text and\nfor an undelivered quote. Read `content_format` to tell a quote from a\ndelivery: when it is null, this is just the quote (`cost`); fetch the\ncontent later via the Contents endpoint.\n\nDo NOT use \"every payload field is null\" as that test. `card_data_schema`\nis set on a card_json quote and on a card_json `url` delivery, where\n`card_data` is null, so a caller reading absent payloads as \"quote\" reads\nthose two as quotes."},{"type":"null"}],"default":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."},"snippet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Snippet","default":null,"description":"Excerpt(s) from the page that matched the query."},"source_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Name","default":null,"description":"Publisher or domain name, when Tako can extract it from the URL."},"publish_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publish Date","default":null,"description":"Publication date of the page, when available."}},"description":"A single raw web search result from the WEB source index.\n\nDistinct from `KnowledgeCardSource` (a citation inside a synthesized\nanswer) and `KnowledgeCard` (a Tako visualization). Web results are\nraw retrieval output — title, URL, optional snippet. They do not depend\non any LLM synthesis that may also happen over them."},"title":"Web Results"}}},"example":null,"exampleRequest":null,"tags":["data","visualization","charts","research","search","answers","agents","reports","datasets","analytics","ai"],"displayCostAmount":"0.012","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"registry","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.012/call","primary":{"kind":"static","protocol":"mpp","network":"tempo","amountUsd":"0.012","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"mpp","network":"tempo","amountUsd":"0.012","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_sOBS2jBxmQFecoG5ZIN2X","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"0.012","costPer":"request","priority":0,"asset":"0x20c000000000000000000000b9537d11c60e8b50","unit":"request","depositMicros":null,"planRef":null}],"brandName":"Tako","brandSlug":"tako","brandBaseUrl":"https://tako.com","brandDocsUrl":"https://tako.com","whatItDoes":"Search across Tako's curated data knowledge graph and the web to retrieve citation-backed data cards, charts, and web results for a natural language query","exampleAgentPrompt":"Search Tako for data cards and web results comparing Intel vs Nvidia headcount since 2013 — use deep effort for higher-quality results.","exampleUseCases":[{"title":"Company headcount comparison research","prompt":"Search Tako for charts and data comparing Intel and Nvidia employee headcount from 2013 to today — use deep effort so I get the best results with citations."},{"title":"Financial news lookup with web filter","prompt":"Find me the latest news about Federal Reserve interest rate decisions — search the web with the news category filter and return up to 10 results."},{"title":"Market data discovery for a report","prompt":"Search Tako for knowledge cards and datasets about US semiconductor market revenue trends over the last 5 years, fast effort is fine, and give me any graph nodes I can use to pin results later."}],"resultDescription":"Returns a SearchResponse containing an array of TakoCards, each with a title, card ID, associated graph nodes (entities and metrics with opaque IDs), and content (inline or presigned URL for download). Graph nodes carry names, types, and descriptions and can be resolved further via the graph node endpoint. A request_id is always present for tracing.","failureModes":["Missing or empty query string returns 422 validation error","Invalid effort enum value returns 400","Web category filter value with no effect (sports, finance) silently accepted but not applied","Node IDs not found in knowledge graph may be silently dropped","Deep effort incurs premium billing and higher latency","Truncated response schema may limit visibility into full card content fields","Locale not matching a supported BCP-47 tag may default to en-US"],"whenToPreferThis":"Choose this endpoint when you need to retrieve structured, citation-backed knowledge cards or charts from Tako's curated data graph combined with optional web results in a single call. Prefer it over /answer when you want raw data cards and graph nodes rather than a synthesized prose answer, over /deep when you need synchronous results rather than async deep research, and over /visualize when you are searching for existing data rather than rendering your own CSV.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-11T12:44:14.456Z","isFirstParty":false,"canonicalSlug":"tako-search-8ba77264"}