Skip to main content
POST
/
v1
/
agent
/
runs
Dispatch an agent run
curl --request POST \
  --url https://tako.com/api/v1/agent/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
  }
}
'
{
  "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": "S&P Global is a US-based financial data and analytics company that provides products and services to the financial industry.",
            "source_index": "tako",
            "url": "https://xignite.com",
            "source_text": "Domestic (28.1%) $154,061,981 | International (71.9%) $394,144,531 | Worldwide $548,206,512. Release Date Nov 7, 2025. Distributor 20th Century Studios."
          }
        ],
        "methodologies": [
          {
            "methodology_name": "Where the Data Comes From - S&P Global",
            "methodology_description": "The financial metrics are collected from S&P Global, where information is sourced from original regulatory filings, press releases, and subsequent restatements. Data points, including over 5,000 financial, supplemental, segment, ratio, and industry-specific items, are standardized across over 180,000 companies to ensure consistency and comparability across different reporting formats. This comprehensive and methodical process enables robust historical analysis and back-testing by seamlessly integrating diverse financial datasets while preserving the granularity of the original reports."
          }
        ],
        "source_indexes": [],
        "card_type": "<string>",
        "content": {
          "cost": 0,
          "data": "<string>",
          "total_rows": 123,
          "truncated": false
        },
        "relevance_score": 123
      }
    ],
    "web_results": [
      {
        "title": "<string>",
        "url": "<string>",
        "snippet": "<string>",
        "source_name": "<string>",
        "publish_date": "<string>",
        "content": {
          "cost": 0,
          "data": "<string>",
          "total_rows": 123,
          "truncated": false
        },
        "citation_number": 123
      }
    ],
    "request_id": "<string>"
  },
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

Notes

  • To authenticate, you’ll need a Tako API key. It’s best practice to store it as an environment variable to avoid hardcoding sensitive credentials in your code.
  • The agent is asynchronous: this endpoint returns 202 with an AgentRun whose status is queued. Poll Poll a run until status is completed or failed — the result (a markdown answer plus the cards and web_results that back it) is populated on completed.
  • To stream progress live instead of polling, send Accept: text/event-stream. The response is then a Server-Sent Events stream of AgentStreamEnvelope events. See the Agent guide for an end-to-end example.

Choosing sources

By default the agent researches both Tako’s curated knowledge graph and the live web. source_indexes is optional — pass it only to restrict to one source. It’s a non-empty subset of ["data", "web"]:
  • ["data", "web"] (default) — both.
  • ["data"] — Tako’s curated knowledge graph only.
  • ["web"] — the live web only.
The legacy value tako is accepted as 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.

Authorizations

X-API-Key
string
header
required

Body

application/json
query
string
required

Natural-language request for the agent.

Example:

"Compare Nvidia and AMD headcount since 2013"

thread_id
string<uuid> | null

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

effort
enum<string>
default:medium

Agent effort level. Only 'medium' is currently supported.

Available options:
medium
source_indexes
enum<string>[]

Which sources the agent may use: 'data' (curated knowledge) and/or 'web' (open-web search). Defaults to ['data', 'web']. The legacy value 'tako' is accepted 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 (a non-English locale makes the agent respond in that language) and the locale used when rendering card preview images. Defaults to en-US.

timezone
string | null

IANA timezone (e.g. 'America/New_York') used to render dates/times in card preview images. Does not affect the returned data.

output_settings
AgentOutputSettings · object

Settings controlling the response/rendering.

Response

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

The 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
AgentResult · object

Final agent output. answer is markdown; cards reuse the sibling TakoCard.

error
ErrorObject · object