Dispatch an Answer Agent run

Dispatch an answer agent run

curl --request POST \
  --url https://tako.com/api/v1/agent/answer/runs \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "query": "<string>",
  "thread_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "effort": "medium",
  "source_indexes": [],
  "locale": "en-US",
  "timezone": "<string>",
  "output_settings": {
    "image_dark_mode": true
  }
}
'

import requests

url = "https://tako.com/api/v1/agent/answer/runs"

payload = {
    "query": "<string>",
    "thread_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "effort": "medium",
    "source_indexes": [],
    "locale": "en-US",
    "timezone": "<string>",
    "output_settings": { "image_dark_mode": True }
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    query: '<string>',
    thread_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    effort: 'medium',
    source_indexes: [],
    locale: 'en-US',
    timezone: '<string>',
    output_settings: {image_dark_mode: true}
  })
};

fetch('https://tako.com/api/v1/agent/answer/runs', 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/answer/runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'query' => '<string>',
    'thread_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'effort' => 'medium',
    'source_indexes' => [
        
    ],
    'locale' => 'en-US',
    'timezone' => '<string>',
    'output_settings' => [
        'image_dark_mode' => true
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://tako.com/api/v1/agent/answer/runs"

	payload := strings.NewReader("{\n  \"query\": \"<string>\",\n  \"thread_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"effort\": \"medium\",\n  \"source_indexes\": [],\n  \"locale\": \"en-US\",\n  \"timezone\": \"<string>\",\n  \"output_settings\": {\n    \"image_dark_mode\": true\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://tako.com/api/v1/agent/answer/runs")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": \"<string>\",\n  \"thread_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"effort\": \"medium\",\n  \"source_indexes\": [],\n  \"locale\": \"en-US\",\n  \"timezone\": \"<string>\",\n  \"output_settings\": {\n    \"image_dark_mode\": true\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://tako.com/api/v1/agent/answer/runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": \"<string>\",\n  \"thread_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"effort\": \"medium\",\n  \"source_indexes\": [],\n  \"locale\": \"en-US\",\n  \"timezone\": \"<string>\",\n  \"output_settings\": {\n    \"image_dark_mode\": true\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "run_id": "<string>",
  "created_at": "<string>",
  "object": "agent.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": {},
          "card_data_schema": {},
          "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": {
          "coverage_end": "2026",
          "data_as_of": "2026-10-01",
          "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": {},
          "card_data_schema": {},
          "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": {
      "definitions": [
        {
          "term": "<string>",
          "definition": "<string>",
          "source_ref": 123
        }
      ],
      "assumptions": [
        {
          "title": "<string>",
          "description": "<string>",
          "category": "<string>",
          "source_ref": 123
        }
      ],
      "methodology": [
        {
          "title": "<string>",
          "description": "<string>"
        }
      ]
    },
    "refusal_code": "<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": [],
    "locale": "en-US",
    "timezone": "<string>",
    "output_settings": {
      "image_dark_mode": true
    }
  }
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

POST

agent

answer

runs

Dispatch an answer agent run

curl --request POST \
  --url https://tako.com/api/v1/agent/answer/runs \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "query": "<string>",
  "thread_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "effort": "medium",
  "source_indexes": [],
  "locale": "en-US",
  "timezone": "<string>",
  "output_settings": {
    "image_dark_mode": true
  }
}
'

import requests

url = "https://tako.com/api/v1/agent/answer/runs"

payload = {
    "query": "<string>",
    "thread_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "effort": "medium",
    "source_indexes": [],
    "locale": "en-US",
    "timezone": "<string>",
    "output_settings": { "image_dark_mode": True }
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    query: '<string>',
    thread_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    effort: 'medium',
    source_indexes: [],
    locale: 'en-US',
    timezone: '<string>',
    output_settings: {image_dark_mode: true}
  })
};

fetch('https://tako.com/api/v1/agent/answer/runs', 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/answer/runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'query' => '<string>',
    'thread_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'effort' => 'medium',
    'source_indexes' => [
        
    ],
    'locale' => 'en-US',
    'timezone' => '<string>',
    'output_settings' => [
        'image_dark_mode' => true
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://tako.com/api/v1/agent/answer/runs"

	payload := strings.NewReader("{\n  \"query\": \"<string>\",\n  \"thread_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"effort\": \"medium\",\n  \"source_indexes\": [],\n  \"locale\": \"en-US\",\n  \"timezone\": \"<string>\",\n  \"output_settings\": {\n    \"image_dark_mode\": true\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://tako.com/api/v1/agent/answer/runs")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": \"<string>\",\n  \"thread_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"effort\": \"medium\",\n  \"source_indexes\": [],\n  \"locale\": \"en-US\",\n  \"timezone\": \"<string>\",\n  \"output_settings\": {\n    \"image_dark_mode\": true\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://tako.com/api/v1/agent/answer/runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": \"<string>\",\n  \"thread_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"effort\": \"medium\",\n  \"source_indexes\": [],\n  \"locale\": \"en-US\",\n  \"timezone\": \"<string>\",\n  \"output_settings\": {\n    \"image_dark_mode\": true\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "run_id": "<string>",
  "created_at": "<string>",
  "object": "agent.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": {},
          "card_data_schema": {},
          "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": {
          "coverage_end": "2026",
          "data_as_of": "2026-10-01",
          "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": {},
          "card_data_schema": {},
          "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": {
      "definitions": [
        {
          "term": "<string>",
          "definition": "<string>",
          "source_ref": 123
        }
      ],
      "assumptions": [
        {
          "title": "<string>",
          "description": "<string>",
          "category": "<string>",
          "source_ref": 123
        }
      ],
      "methodology": [
        {
          "title": "<string>",
          "description": "<string>"
        }
      ]
    },
    "refusal_code": "<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": [],
    "locale": "en-US",
    "timezone": "<string>",
    "output_settings": {
      "image_dark_mode": true
    }
  }
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

The Answer Agent researches a natural-language question across Tako’s knowledge and the live web, then returns a synthesized, opinionated answer (markdown) with the citations and cards that back it. Use it for open-ended questions that need reasoning across many entities. See the Answer Agent guide for examples, citations, streaming, threads, and sources.

Notes

To authenticate, send your Tako API key in the X-API-Key header. Store it as an environment variable rather than hardcoding it.
The agent is asynchronous: this endpoint returns 202 with an AnswerAgentRun whose status is queued. Poll Poll an Answer Agent run until status is completed or failed.
To stream progress live instead of polling, send Accept: text/event-stream. The response is then a Server-Sent Events stream of AnswerAgentStreamEnvelope events. See the coding-agent reference.
Frozen contract: the Answer Agent never accepts an output_schema and never returns structured output or inline data — the result is answer + cards + citations + metadata. For structured data, use the Retrieval Agent.

Choosing sources

source_indexes is optional and defaults to ["data", "web"] — both. Pass it only to restrict: ["data"] (curated knowledge graph only) or ["web"] (open web only). The legacy value "tako" is a synonym for "data".

Continuing a thread

Pass the thread_id from a prior run to ask a follow-up in the same conversation. Omit it to start a new thread. A thread is pinned to the Answer Agent and to one set of source_indexes.

Authorizations

X-API-Key

string

header

required

Body

application/json

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.

Example:

"How have American Airlines' margins held up against fuel shocks?"

thread_id

string<uuid> | null

Existing thread to continue (follow-up). Omit to start a new thread.

effort

enum<string>

default:medium

Answer-agent effort. Only 'medium' is currently supported.

Available options:

medium

source_indexes

enum<string>[]

Which sources the agent may use: 'data' (curated knowledge), 'web' (open-web search), or both. Defaults to ['data', 'web']. Tako accepts the legacy value 'tako' as a synonym for 'data'.

Available options:

data,

web

Examples:

["data"]

["web"]

["data", "web"]

locale

string

default:en-US

BCP-47 locale. Drives the language of the agent's answer and the locale used when rendering card preview images. Defaults to en-US.

timezone

string | null

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 · object | null

Settings that control the response and rendering.

Show child attributes

Response

Run dispatched. With Accept: application/json, poll GET /v1/agent/answer/runs/{run_id} for the run status. With Accept: text/event-stream, the response is an SSE stream of AnswerAgentStreamEnvelope events. The stream ends at stream_done. If the stream ends without an agent_result event, poll GET /v1/agent/answer/runs/{run_id} for the terminal status.

The answer-agent run resource returned by dispatch (202) and poll (GET).

run_id

string

required

status

enum<string>

required

Available options:

queued,

running,

completed,

failed

created_at

string

required

object

string

default:agent.run

Allowed value: "agent.run"

thread_id

string | null

completed_at

string | null

result

AnswerAgentResult · object | null

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.

Show child attributes

error

ErrorObject · object | null

Show child attributes

usage

Usage · object | null

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

request

AnswerAgentRunRequest · object | null

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).

Show child attributes

⌘I

Getting Started

Build with Tako

API Reference

Integrations

Additional Resources

Dispatch an Answer Agent run

Notes

Choosing sources

Continuing a thread

Authorizations

Body

Response

​Notes

​Choosing sources

​Continuing a thread

Authorizations

Body

Response

Notes

Choosing sources

Continuing a thread