curl --request GET \
--url https://tako.com/api/v1/agent/retrieval/runs/{run_id} \
--header 'X-API-Key: <api-key>'import requests
url = "https://tako.com/api/v1/agent/retrieval/runs/{run_id}"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://tako.com/api/v1/agent/retrieval/runs/{run_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://tako.com/api/v1/agent/retrieval/runs/{run_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://tako.com/api/v1/agent/retrieval/runs/{run_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://tako.com/api/v1/agent/retrieval/runs/{run_id}")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://tako.com/api/v1/agent/retrieval/runs/{run_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"run_id": "<string>",
"created_at": "<string>",
"object": "agent.retrieval.run",
"thread_id": "<string>",
"completed_at": "<string>",
"result": {
"answer": "<string>",
"cards": [
{
"card_id": "<string>",
"title": "<string>",
"description": "<string>",
"semantic_description": "<string>",
"webpage_url": "<string>",
"image_url": "<string>",
"embed_url": "<string>",
"sources": [
{
"source_name": "S&P Global",
"source_description": "<string>",
"url": "https://xignite.com",
"source_text": "<string>"
}
],
"methodologies": [
{
"methodology_name": "Where the Data Comes From - S&P Global",
"methodology_description": "Financial metrics standardized by S&P Global from company regulatory filings, press releases, and restatements."
}
],
"source_indexes": [],
"card_type": "<string>",
"content": {
"cost": 0,
"data": "<string>",
"records": [
{}
],
"dataset": {
"columns": [
{
"name": "<string>",
"unit": "<string>"
}
],
"rows": [
[
"<string>"
]
],
"total_rows": 123,
"truncated": true,
"ref": "<string>",
"sources": [
{
"name": "<string>",
"index": "data"
}
],
"provenance": "query"
},
"card_data": {},
"url": "<string>",
"expires_at": "<string>",
"total_rows": 123,
"truncated": false,
"export_pricing": {
"baseline_usd": 123,
"row_cpm_usd": 123,
"free_rows": 123,
"max_rows_ceiling": 123
},
"manifest": [
{
"name": "<string>",
"metric": "<string>",
"entity": "<string>",
"unit": "<string>"
}
]
},
"exportable": false,
"relevance_score": 123,
"nodes": [
{
"id": "<string>",
"name": "<string>",
"description": "<string>"
}
],
"metric_definitions": [
{
"name": "<string>",
"definition": "<string>"
}
],
"data_freshness": {
"data_as_of": "2026-06-30",
"last_updated": "2026-07-14"
}
}
],
"citations": [
{
"index": 123,
"title": "<string>",
"url": "<string>",
"source_name": "<string>",
"excerpt": "<string>",
"publish_date": "<string>",
"content": {
"cost": 0,
"data": "<string>",
"records": [
{}
],
"dataset": {
"columns": [
{
"name": "<string>",
"unit": "<string>"
}
],
"rows": [
[
"<string>"
]
],
"total_rows": 123,
"truncated": true,
"ref": "<string>",
"sources": [
{
"name": "<string>",
"index": "data"
}
],
"provenance": "query"
},
"card_data": {},
"url": "<string>",
"expires_at": "<string>",
"total_rows": 123,
"truncated": false,
"export_pricing": {
"baseline_usd": 123,
"row_cpm_usd": 123,
"free_rows": 123,
"max_rows_ceiling": 123
},
"manifest": [
{
"name": "<string>",
"metric": "<string>",
"entity": "<string>",
"unit": "<string>"
}
]
}
}
],
"metadata": {
"citations": [
{
"index": 123,
"title": "<string>",
"url": "<string>",
"source_name": "<string>",
"excerpt": "<string>",
"publish_date": "<string>",
"content": {
"cost": 0,
"data": "<string>",
"records": [
{}
],
"dataset": {
"columns": [
{
"name": "<string>",
"unit": "<string>"
}
],
"rows": [
[
"<string>"
]
],
"total_rows": 123,
"truncated": true,
"ref": "<string>",
"sources": [
{
"name": "<string>",
"index": "data"
}
],
"provenance": "query"
},
"card_data": {},
"url": "<string>",
"expires_at": "<string>",
"total_rows": 123,
"truncated": false,
"export_pricing": {
"baseline_usd": 123,
"row_cpm_usd": 123,
"free_rows": 123,
"max_rows_ceiling": 123
},
"manifest": [
{
"name": "<string>",
"metric": "<string>",
"entity": "<string>",
"unit": "<string>"
}
]
}
}
],
"definitions": [
{
"term": "<string>",
"definition": "<string>",
"source_ref": 123
}
],
"assumptions": [
{
"title": "<string>",
"description": "<string>",
"category": "<string>",
"source_ref": 123
}
],
"methodology": [
{
"title": "<string>",
"description": "<string>"
}
]
},
"structured_output": {},
"structured_output_citations": {},
"unfilled_fields": [
"<string>"
],
"structured_output_error": {
"code": "<string>",
"message": "<string>"
},
"request_id": "<string>"
},
"error": {
"code": "<string>",
"message": "<string>"
},
"usage": {
"total_cost_usd": 123,
"compute": {
"cost_usd": 123
},
"data": {
"cost_usd": 123,
"datasets": 123
}
},
"request": {
"query": "<string>",
"thread_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"effort": "medium",
"source_indexes": [],
"cards": true,
"output_schema": {},
"locale": "en-US",
"timezone": "<string>",
"output_settings": {
"image_dark_mode": true
}
}
}{
"code": "<string>",
"message": "<string>"
}{
"code": "<string>",
"message": "<string>"
}{
"code": "<string>",
"message": "<string>"
}Poll a Retrieval Agent run
Retrieve the current state and result of a Retrieval Agent run
curl --request GET \
--url https://tako.com/api/v1/agent/retrieval/runs/{run_id} \
--header 'X-API-Key: <api-key>'import requests
url = "https://tako.com/api/v1/agent/retrieval/runs/{run_id}"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://tako.com/api/v1/agent/retrieval/runs/{run_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://tako.com/api/v1/agent/retrieval/runs/{run_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://tako.com/api/v1/agent/retrieval/runs/{run_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://tako.com/api/v1/agent/retrieval/runs/{run_id}")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://tako.com/api/v1/agent/retrieval/runs/{run_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"run_id": "<string>",
"created_at": "<string>",
"object": "agent.retrieval.run",
"thread_id": "<string>",
"completed_at": "<string>",
"result": {
"answer": "<string>",
"cards": [
{
"card_id": "<string>",
"title": "<string>",
"description": "<string>",
"semantic_description": "<string>",
"webpage_url": "<string>",
"image_url": "<string>",
"embed_url": "<string>",
"sources": [
{
"source_name": "S&P Global",
"source_description": "<string>",
"url": "https://xignite.com",
"source_text": "<string>"
}
],
"methodologies": [
{
"methodology_name": "Where the Data Comes From - S&P Global",
"methodology_description": "Financial metrics standardized by S&P Global from company regulatory filings, press releases, and restatements."
}
],
"source_indexes": [],
"card_type": "<string>",
"content": {
"cost": 0,
"data": "<string>",
"records": [
{}
],
"dataset": {
"columns": [
{
"name": "<string>",
"unit": "<string>"
}
],
"rows": [
[
"<string>"
]
],
"total_rows": 123,
"truncated": true,
"ref": "<string>",
"sources": [
{
"name": "<string>",
"index": "data"
}
],
"provenance": "query"
},
"card_data": {},
"url": "<string>",
"expires_at": "<string>",
"total_rows": 123,
"truncated": false,
"export_pricing": {
"baseline_usd": 123,
"row_cpm_usd": 123,
"free_rows": 123,
"max_rows_ceiling": 123
},
"manifest": [
{
"name": "<string>",
"metric": "<string>",
"entity": "<string>",
"unit": "<string>"
}
]
},
"exportable": false,
"relevance_score": 123,
"nodes": [
{
"id": "<string>",
"name": "<string>",
"description": "<string>"
}
],
"metric_definitions": [
{
"name": "<string>",
"definition": "<string>"
}
],
"data_freshness": {
"data_as_of": "2026-06-30",
"last_updated": "2026-07-14"
}
}
],
"citations": [
{
"index": 123,
"title": "<string>",
"url": "<string>",
"source_name": "<string>",
"excerpt": "<string>",
"publish_date": "<string>",
"content": {
"cost": 0,
"data": "<string>",
"records": [
{}
],
"dataset": {
"columns": [
{
"name": "<string>",
"unit": "<string>"
}
],
"rows": [
[
"<string>"
]
],
"total_rows": 123,
"truncated": true,
"ref": "<string>",
"sources": [
{
"name": "<string>",
"index": "data"
}
],
"provenance": "query"
},
"card_data": {},
"url": "<string>",
"expires_at": "<string>",
"total_rows": 123,
"truncated": false,
"export_pricing": {
"baseline_usd": 123,
"row_cpm_usd": 123,
"free_rows": 123,
"max_rows_ceiling": 123
},
"manifest": [
{
"name": "<string>",
"metric": "<string>",
"entity": "<string>",
"unit": "<string>"
}
]
}
}
],
"metadata": {
"citations": [
{
"index": 123,
"title": "<string>",
"url": "<string>",
"source_name": "<string>",
"excerpt": "<string>",
"publish_date": "<string>",
"content": {
"cost": 0,
"data": "<string>",
"records": [
{}
],
"dataset": {
"columns": [
{
"name": "<string>",
"unit": "<string>"
}
],
"rows": [
[
"<string>"
]
],
"total_rows": 123,
"truncated": true,
"ref": "<string>",
"sources": [
{
"name": "<string>",
"index": "data"
}
],
"provenance": "query"
},
"card_data": {},
"url": "<string>",
"expires_at": "<string>",
"total_rows": 123,
"truncated": false,
"export_pricing": {
"baseline_usd": 123,
"row_cpm_usd": 123,
"free_rows": 123,
"max_rows_ceiling": 123
},
"manifest": [
{
"name": "<string>",
"metric": "<string>",
"entity": "<string>",
"unit": "<string>"
}
]
}
}
],
"definitions": [
{
"term": "<string>",
"definition": "<string>",
"source_ref": 123
}
],
"assumptions": [
{
"title": "<string>",
"description": "<string>",
"category": "<string>",
"source_ref": 123
}
],
"methodology": [
{
"title": "<string>",
"description": "<string>"
}
]
},
"structured_output": {},
"structured_output_citations": {},
"unfilled_fields": [
"<string>"
],
"structured_output_error": {
"code": "<string>",
"message": "<string>"
},
"request_id": "<string>"
},
"error": {
"code": "<string>",
"message": "<string>"
},
"usage": {
"total_cost_usd": 123,
"compute": {
"cost_usd": 123
},
"data": {
"cost_usd": 123,
"datasets": 123
}
},
"request": {
"query": "<string>",
"thread_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"effort": "medium",
"source_indexes": [],
"cards": true,
"output_schema": {},
"locale": "en-US",
"timezone": "<string>",
"output_settings": {
"image_dark_mode": true
}
}
}{
"code": "<string>",
"message": "<string>"
}{
"code": "<string>",
"message": "<string>"
}{
"code": "<string>",
"message": "<string>"
}Notes
- Poll with the
run_idreturned by Dispatch a Retrieval Agent run.statusprogressesqueued→running→completed/failed; theresult(aRetrievalAgentResult) is populated oncestatusiscompleted. - The result carries
answer,cards,citations, and — when the request supplied anoutput_schema— thestructured_output*fields. There is noweb_resultsfield; web and Tako sources alike land in the top-levelcitationsregistry. - To resume or tail the run as a live Server-Sent Events stream, send
Accept: text/event-stream. Usestarting_after(or theLast-Event-IDheader) to replay only events whoseseqis greater than a value you’ve already seen. See the Retrieval Agent guide.
Authorizations
Path Parameters
The run ID from the POST /v1/agent/retrieval/runs response.
Query Parameters
SSE resume cursor (Accept: text/event-stream only). The stream replays events with seq greater than this value. It is equivalent to the Last-Event-ID header.
x >= 0Response
Current state of the agent run. With Accept: text/event-stream, the response replays and then follows the run as an SSE stream of RetrievalAgentStreamEnvelope events. Use starting_after or Last-Event-ID to resume. If the stream ends without an agent_result event, poll this endpoint with Accept: application/json for the terminal status.
The retrieval-agent run resource returned by dispatch (202) and poll (GET).
queued, running, completed, failed "agent.retrieval.run"Final retrieval-agent output. answer is markdown prose with [n] citation markers. cards reuse the sibling TakoCard. citations is the unified top-level registry for data and web sources — there is no web_results field. metadata carries definitions, assumptions, and methodology. The structured_output_* fields carry the caller-shaped output_schema result; they are present only if the request supplied output_schema. See each field's description for the exact presence rules.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Usage for one metered request. total_cost_usd is always present (the
total quoted charge). compute and data are the additive breakdown;
each appears only where it applies. total_cost_usd always equals the sum
of the components that appear.
Show child attributes
Show child attributes
Request body for POST /v1/agent/retrieval/runs.
Show child attributes
Show child attributes