--- title: "Poll status for an Answer Agent run (free, receipt-authenticated)" method: GET path: "/api/mpp/v1/agent/answer/runs/status" --- # Poll status for an Answer Agent run (free, receipt-authenticated) `GET /api/mpp/v1/agent/answer/runs/status` ## Request - Base URL: `https://tako.com` - URL: `https://tako.com/api/mpp/v1/agent/answer/runs/status` - Auth: API key in header `Authorization` ## Query parameters - `run_id` string, required ## Response `200` Current run status, including the cited answer once complete. - AnswerAgentRun: The answer-agent run resource returned by dispatch (202) and poll (GET). - `run_id` string, required - `object` 'agent.run' - `thread_id` string, nullable - `status` 'queued' | 'running' | 'completed' | 'failed', required - `created_at` string, required - `completed_at` string, nullable - `result` AnswerAgentResult: Final answer-agent output. answer is markdown prose with [n] citation markers. citations is the unified top-level registry that the [n] markers join. cards reuse the sibling TakoCard. metadata carries definitions, assumptions, and methodology. There is no inline data, no structured output, and no web_results — ever. A prose-only result (empty cards) is legitimate. - `answer` string, nullable - `cards` TakoCard[] - `card_id` string, nullable - `title` string, nullable - `description` string, nullable - `semantic_description` string, nullable - `webpage_url` string, nullable - `image_url` string, nullable - `embed_url` string, nullable - `sources` TakoCardSource[], nullable - `source_name` string, nullable: The name of the source - `source_description` string, nullable: The description of the source - `source_index` 'data' | 'web', required: Public source taxonomy for the SDK card surfaces (v3 search, v1 answer, agent). It is symmetric with the request taxonomy {data, web}. - `url` string, nullable: The URL of the source - `source_text` string, nullable: Raw excerpts retrieved from the source page — the unmodified web content that grounded the answer. Present for WEB sources; null for DATA sources. - `methodologies` KnowledgeCardMethodology[], nullable - `methodology_name` string, nullable, required: The name of the methodology - `methodology_description` string, nullable, required: 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. - `source_indexes` TakoSourceIndex[], nullable - `card_type` string, nullable - `relevance` 'High' | 'Medium' | 'Low' - `content` ResultContent: 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 record 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. - `content_format` 'csv' | 'json_records' | 'json_compact' | 'card_json': Serialization of tabular (Tako card) data. Web content is always raw text and carries no content format (content_format is null). - `cost` number: 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` string, nullable: 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` object[], nullable: 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` TakoDataset: 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. - `columns` TakoDatasetColumn[], required: Ordered column headers (name + type), one per position in every row. - `name` string, required: Column name. - `type` 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'array', required: 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'. - `unit` string, nullable: Structured unit for the column values, e.g. 'USD billions', '%'. Null when unitless. - `rows` array[], required: Row data as positional cell arrays aligned to `columns` order. Cells are string/number/boolean/null, or an array of objects in a column typed 'array'; nulls are preserved, never coerced. - union[] - … - `total_rows` integer, required: True total number of rows in the underlying data, before any truncation. - `truncated` boolean, required: True when `rows` was capped and total_rows exceeds the number returned. - `ref` string, required: Source URL the dataset was derived from (e.g. the Tako card URL). - `sources` TakoDatasetSource[], required: Provenance for the dataset: the sources the rows were drawn from. - `name` string, required: Human-readable source name (e.g. 'FRED', 'S&P Global'). - `index` 'data' | 'web': Source index the rows came from: 'data' (Tako) or 'web'. - `provenance` 'query' | 'web_extraction': How the rows were produced: 'query' (Tako data) or 'web_extraction'. - `redacted_cells` object, nullable: 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. - `card_data` object, nullable: 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` object, nullable: 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` string, nullable: Presigned download URL for the content, returned in 'url' delivery mode. Null for inline delivery and for quotes; pair with expires_at. - `expires_at` string, nullable: ISO-8601 timestamp after which the presigned url stops working. Null whenever url is null. - `total_rows` integer, nullable: 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. On a search or answer card that returns no rows, it's set when the card can hold premium values, and gives the rows a /contents export of the card returns. A list of companies or people that match a name or a set of filters, such as fintechs in London, shows the top of a search its /contents export runs again, so on a search or answer card, returned rows or not, total_rows is the most rows that export returns, and truncated is true. Null for web text. - `total_matching` integer, nullable: 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` boolean: 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. On a search or answer response, it's also true when a /contents export of a list card returns more rows than the card shows, and then total_rows counts the export's rows. 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. - `export_pricing` ExportPricing: 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, and premium_rows[c] the export's premium record count for class c. 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. - `baseline_usd` number, required: Flat USD charged once per card export, independent of row count. - `row_cpm_usd` number, required: 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` object: USD charged per 1,000 premium records, keyed by premium class ('company_record', 'person_contact'), added on top of row_cpm_usd when a /contents export passes premium=true. A premium record is a distinct company or person that the delivered rows hold a non-null value for 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` integer: 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. - `max_rows_ceiling` integer, required: 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` number, nullable: 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. On a search or answer card, it also bounds the minimum charge for serving that card with its data. - `manifest` ColumnDescriptor[], nullable: 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. - `name` string, nullable: The column header as exported. This is the CSV header, the json_records key, and the dataset column label for this column. - `metric` string, nullable: What the column measures, for example 'Median Sales Price'. - `entity` string, nullable: 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` string, nullable: The unit of every value in the column, for example 'USD'. - `dtype` 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'array': 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'. - `premium_class` 'person_contact' | 'company_record': The price class of a premium column. Person and company records are licensed at different per-record rates. - `premium` boolean: 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. - `premium_rows` object, nullable: Per premium class ('company_record', 'person_contact'), the number of distinct records that the delivered rows hold a value for in a column of that class, whether revealed or withheld: one per company for 'company_record' and one per person for 'person_contact'. A row whose record can't be identified counts as its own record. 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 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 records when total_rows is within max_rows_ceiling. On a search or answer card that returns no rows, it counts the rows the card shows, and it's null for a card that can't hold a premium value. When truncated is true there, an export reads more rows than the card shows, so these counts are a preview's: ask /contents with quote_only for the premium price. It's set wherever total_rows is. - `redacted_cells` object, nullable: 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. - `exportable` boolean: 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. - `relevance_score` number, nullable: 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` TakoCardNode[], nullable: 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. - `id` string, required: 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` 'metric' | 'entity', required: A `metric` is a measurable quantity, such as GDP; an `entity` is what one is measured for, such as France. - `name` string, required: 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` string, nullable: 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. - `metric_definitions` MetricDefinition[], nullable: Definitions of the metrics this card displays (name + definition). Null when no displayed metric has a definition available. - `name` string, required: The metric's display name - `definition` string, required: Human-readable definition of the metric - `data_freshness` DataFreshness: 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. - `coverage_end` string, nullable: 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. - `data_as_of` string, nullable: 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. - `last_updated` string, nullable: 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. - `placeholder` PlaceholderInfo: Why a card carries no data points. - `withheld_source` string, required: The name of the source whose data the card withholds. - `reason` 'not_served' | 'over_cap' - `citations` AgentAnswerCitation[] - `index` integer, required - `title` string, required - `url` string, nullable - `source_name` string, nullable - `source_index` 'data' | 'web': Public source taxonomy for the SDK card surfaces (v3 search, v1 answer, agent). It is symmetric with the request taxonomy {data, web}. - `excerpt` string, nullable - `publish_date` string, nullable - `content` ResultContent: 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 record 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. - `content_format` 'csv' | 'json_records' | 'json_compact' | 'card_json': Serialization of tabular (Tako card) data. Web content is always raw text and carries no content format (content_format is null). - `cost` number: 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` string, nullable: 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` object[], nullable: 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` TakoDataset: 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. - `columns` TakoDatasetColumn[], required: Ordered column headers (name + type), one per position in every row. - `name` string, required: Column name. - `type` 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'array', required: 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'. - `unit` string, nullable: Structured unit for the column values, e.g. 'USD billions', '%'. Null when unitless. - `rows` array[], required: Row data as positional cell arrays aligned to `columns` order. Cells are string/number/boolean/null, or an array of objects in a column typed 'array'; nulls are preserved, never coerced. - union[] - … - `total_rows` integer, required: True total number of rows in the underlying data, before any truncation. - `truncated` boolean, required: True when `rows` was capped and total_rows exceeds the number returned. - `ref` string, required: Source URL the dataset was derived from (e.g. the Tako card URL). - `sources` TakoDatasetSource[], required: Provenance for the dataset: the sources the rows were drawn from. - `name` string, required: Human-readable source name (e.g. 'FRED', 'S&P Global'). - `index` 'data' | 'web': Source index the rows came from: 'data' (Tako) or 'web'. - `provenance` 'query' | 'web_extraction': How the rows were produced: 'query' (Tako data) or 'web_extraction'. - `redacted_cells` object, nullable: 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. - `card_data` object, nullable: 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` object, nullable: 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` string, nullable: Presigned download URL for the content, returned in 'url' delivery mode. Null for inline delivery and for quotes; pair with expires_at. - `expires_at` string, nullable: ISO-8601 timestamp after which the presigned url stops working. Null whenever url is null. - `total_rows` integer, nullable: 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. On a search or answer card that returns no rows, it's set when the card can hold premium values, and gives the rows a /contents export of the card returns. A list of companies or people that match a name or a set of filters, such as fintechs in London, shows the top of a search its /contents export runs again, so on a search or answer card, returned rows or not, total_rows is the most rows that export returns, and truncated is true. Null for web text. - `total_matching` integer, nullable: 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` boolean: 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. On a search or answer response, it's also true when a /contents export of a list card returns more rows than the card shows, and then total_rows counts the export's rows. 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. - `export_pricing` ExportPricing: 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, and premium_rows[c] the export's premium record count for class c. 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. - `baseline_usd` number, required: Flat USD charged once per card export, independent of row count. - `row_cpm_usd` number, required: 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` object: USD charged per 1,000 premium records, keyed by premium class ('company_record', 'person_contact'), added on top of row_cpm_usd when a /contents export passes premium=true. A premium record is a distinct company or person that the delivered rows hold a non-null value for 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` integer: 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. - `max_rows_ceiling` integer, required: 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` number, nullable: 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. On a search or answer card, it also bounds the minimum charge for serving that card with its data. - `manifest` ColumnDescriptor[], nullable: 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. - `name` string, nullable: The column header as exported. This is the CSV header, the json_records key, and the dataset column label for this column. - `metric` string, nullable: What the column measures, for example 'Median Sales Price'. - `entity` string, nullable: 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` string, nullable: The unit of every value in the column, for example 'USD'. - `dtype` 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'array': 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'. - `premium_class` 'person_contact' | 'company_record': The price class of a premium column. Person and company records are licensed at different per-record rates. - `premium` boolean: 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. - `premium_rows` object, nullable: Per premium class ('company_record', 'person_contact'), the number of distinct records that the delivered rows hold a value for in a column of that class, whether revealed or withheld: one per company for 'company_record' and one per person for 'person_contact'. A row whose record can't be identified counts as its own record. 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 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 records when total_rows is within max_rows_ceiling. On a search or answer card that returns no rows, it counts the rows the card shows, and it's null for a card that can't hold a premium value. When truncated is true there, an export reads more rows than the card shows, so these counts are a preview's: ask /contents with quote_only for the premium price. It's set wherever total_rows is. - `redacted_cells` object, nullable: 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. - `metadata` AnswerAgentMetadata: Answer-agent metadata. Citations live in the top-level `citations` registry, so this carries only definitions, assumptions, and methodology. Distinct from the shared AgentAnswerMetadata, which retains citations for the legacy AgentResult. - `definitions` AgentAnswerDefinition[], nullable - `term` string, required - `definition` string, required - `source_ref` integer, nullable - `assumptions` AgentAnswerAssumption[], nullable - `title` string, required - `description` string, required - `category` string, nullable - `source_ref` integer, nullable - `methodology` AgentAnswerMethodologyNote[], nullable - `title` string, required - `description` string, required - `refusal_code` string, nullable: Set when Tako rejected the query before the agent ran. Null on normal runs. Tako can add new codes, so accept a code you do not recognize. The current code is 'rejected_input_classifier'. - `request_id` string, nullable - `error` ErrorObject - `code` string, required - `message` string, required - `usage` Usage: Usage for one metered request. `total_cost_usd` is always present (the total quoted charge). `compute`, `data`, and `variable_cost` are the additive breakdown; each appears only where it applies. total_cost_usd always equals the sum of the components that appear. - `total_cost_usd` number, required: Total quoted USD cost of this request: the sum of the components present. - `compute` UsageCompute: The cost of running the operation. Absent on surfaces with no compute step (contents). - `cost_usd` number, required: USD cost of running the operation. - `data` UsageData: 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. - `cost_usd` number, required: USD cost of the inline data delivered in the response. - `datasets` integer, required: Number of billed datasets or content items included in the response. - `data_points` integer, nullable: Number of billed quantitative data points included in the response. - `variable_cost` UsageVariableCost: The variable-cost charge: the per-unit minimum of a variable-cost source the response served, above the response's base price. - `cost_usd` number, required: USD cost of the variable-cost charge. - `request` AnswerAgentRunRequest: Request body for POST /v1/agent/answer/runs. Frozen contract: no output_schema, no structured outputs, and no inline data — ever. Cards are the only data-export path (via /v1/contents). - `query` string, required: Natural-language request for the answer agent. - `thread_id` string, uuid, nullable: Existing thread to continue (follow-up). Omit to start a new thread. - `effort` 'medium' | 'high': Effort levels for the Answer Agent (POST /v1/agent/answer/runs). 'medium' is the default. 'high' uses the same models and the same data. It only makes the model reason more, and it gives the run more time. A 'high' run can give a better answer, and it always takes longer. 'low' is not available. A request that sends 'low' gets a 400 response. The effort is fixed for the life of a thread. A follow-up that sends a different effort gets a 409 response with the code 'effort_mismatch'. To use a different effort, start a new thread. - `source_indexes` string[], nullable: Which sources the agent may use: 'data' (curated knowledge), 'web' (open-web search), or both. Omit it on a new thread and the agent uses both; omit it on a follow-up and the run keeps the thread's sources. Tako accepts the legacy value 'tako' as a synonym for 'data'. - `locale` string: BCP-47 locale. Drives the language of the agent's answer and the locale used when rendering card preview images. - `timezone` string, nullable: IANA timezone (for example, 'America/New_York'). The agent uses it to render dates and times in card preview images. It does not affect the returned data. - `output_settings` AgentOutputSettings - `image_dark_mode` boolean, nullable: Render card preview images in dark mode. Omit to use the default (dark). ## Other responses - `400`: run_id query parameter is required. - `401`: Missing, invalid, or expired receipt token. - `403`: You do not have access to this run. - `404`: Run not found. - `429`: Rate limit exceeded. Wait Retry-After seconds, then retry. ## Changes - **2026-11-03** `b88b0829e406`: 1 info - added the optional property `result/anyOf[subschema #1: AnswerAgentResult]/cards/items/placeholder/anyOf[subschema #1: PlaceholderInfo]/reason` to the response with the `200` status - **2026-11-02** `169f9f7268d1`: 4 breaking, 4 warning - response property `result/anyOf[subschema #1: AnswerAgentResult]/cards/items/content/anyOf[subschema #1: ResultContent]/dataset/anyOf[subschema #1: TakoDataset]/rows/items/items/` list-of-types was widened by adding types `array` to media type `application/json` of response `200` - response property `result/anyOf[subschema #1: AnswerAgentResult]/cards/items/content/anyOf[subschema #1: ResultContent]/records/anyOf[subschema #1]/items/additionalProperties/` list-of-types was widened by adding types `array` to media type `application/json` of response `200` - response property `result/anyOf[subschema #1: AnswerAgentResult]/citations/items/content/anyOf[subschema #1: ResultContent]/dataset/anyOf[subschema #1: TakoDataset]/rows/items/items/` list-of-types was widened by adding types `array` to media type `application/json` of response `200` - response property `result/anyOf[subschema #1: AnswerAgentResult]/citations/items/content/anyOf[subschema #1: ResultContent]/records/anyOf[subschema #1]/items/additionalProperties/` list-of-types was widened by adding types `array` to media type `application/json` of response `200` - …4 more - **2026-10-20** `2af0a2d68ee3`: 1 info - endpoint added [Operation history](https://skmtc.dev/tako/apis/tako-api/changes/api/mpp/v1/agent/answer/runs/status/get.md) --- [API](https://skmtc.dev/tako/apis/tako-api.md) - [All operations](https://skmtc.dev/tako/apis/tako-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tako/apis/tako-api/revisions/b88b0829e406?raw)