Graph Search

Search the data graph

curl --request GET \
  --url https://tako.com/api/v1/graph/search \
  --header 'X-API-Key: <api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://tako.com/api/v1/graph/search', 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/graph/search",
  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/graph/search"

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

}

require 'uri'
require 'net/http'

url = URI("https://tako.com/api/v1/graph/search")

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

{
  "results": [
    {
      "id": "<string>",
      "type": "metric",
      "name": "<string>",
      "aliases": [
        "<string>"
      ],
      "description": "<string>",
      "subtype": "Companies",
      "label": "PERSON"
    }
  ],
  "inferred_labels": [
    "PERSON"
  ]
}

{
  "error_message": "<string>",
  "error_type": "BAD_REQUEST"
}

{
  "error_message": "<string>",
  "error_type": "BAD_REQUEST"
}

{
  "error_message": "<string>",
  "error_type": "BAD_REQUEST"
}

GET

graph

Search the data graph

curl --request GET \
  --url https://tako.com/api/v1/graph/search \
  --header 'X-API-Key: <api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://tako.com/api/v1/graph/search', 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/graph/search",
  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/graph/search"

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

}

require 'uri'
require 'net/http'

url = URI("https://tako.com/api/v1/graph/search")

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

{
  "results": [
    {
      "id": "<string>",
      "type": "metric",
      "name": "<string>",
      "aliases": [
        "<string>"
      ],
      "description": "<string>",
      "subtype": "Companies",
      "label": "PERSON"
    }
  ],
  "inferred_labels": [
    "PERSON"
  ]
}

{
  "error_message": "<string>",
  "error_type": "BAD_REQUEST"
}

{
  "error_message": "<string>",
  "error_type": "BAD_REQUEST"
}

{
  "error_message": "<string>",
  "error_type": "BAD_REQUEST"
}

Notes

Authenticated, no credits — send the same X-API-Key header as every Tako endpoint. Graph calls consume no credits; rate limits are 180/minute and 10,000/day.
Use graph search to discover and confirm what data exists before you query it. Resolve the metric and the entity you care about here, then ask Search (/v3/search) or Answer (/v1/answer) for that specific entity + metric combination — and pin the resolved ids via sources.data.node_ids.
Each result is a GraphNode whose id you can pass straight to Graph Related to explore what it connects to.

A returned metric or entity is a guide, not a guarantee — it does not promise that a specific entity + metric combination exists, or that data is available for it. Use it to steer what you ask Search or Answer for, and confirm coverage there.

Scoping with `types`

types is a comma-separated list of facets to return. Omit it to search both:

metric — a measure (e.g. “GDP”, “stock price”).
entity — a thing the metric is tracked for (e.g. a country, a company).

Steering the ranking with `label`

Many names are homonyms — “Air China” contains a country’s name, so the airline competes with China itself in the results. Pass label to bias the ranking toward one entity category. It is a boost, not a filter — matching nodes rank higher, but off-label nodes still return:

# The airline, not the country
curl "https://tako.com/api/v1/graph/search?q=air%20china&label=ORG" \
  -H "X-API-Key: $TAKO_API_KEY"

Values: PERSON, ORG, GPE, LOC, PRODUCT, EVENT, LANGUAGE, MONEY, METRIC, STOCK_TICKER, WEBSITE. Sports teams are ORG. An unknown value is a 400.
Auto-inference is on by default (infer_label=true): with no explicit label, Tako detects the entities in q and applies the matching boost. The labels it found come back in inferred_labels — an empty list means inference ran and found nothing; the key is absent when inference didn’t run. Disable with infer_label=false (also 0/no/off); passing an explicit label also disables inference.
Each node reports its own label and subtype (e.g. Countries, Companies) in the response — read them to pick the right node rather than assuming the list is filtered.

A q shorter than 2 characters returns an empty results list (200, not an error), and limit above 50 is clamped rather than rejected.

Example response

The response to the label=ORG call above — the airline now outranks the country:

{
  "results": [
    {
      "id": "ent::air_china_limited::6af29d2b",
      "type": "entity",
      "name": "Air China Limited",
      "aliases": ["Air China", "Air China Ltd.", "CCA"],
      "description": "Air China Limited, together with its subsidiaries, provides air passenger, air cargo, and airline-related services…",
      "subtype": "Companies",
      "label": "ORG"
    }
  ]
}

Results are ordered by a relevance + popularity blend; fields that are null are omitted from the response.

Authorizations

X-API-Key

string

header

required

Query Parameters

string

required

Search text (min 1 char).

Minimum string length: 1

types

enum<string>[]

Facets to include. Defaults to metric and entity.

Available options:

metric,

entity

limit

integer

Max results (default 20, max 50).

Required range: x >= 1

label

enum<string>

Prefer results with this NER label (boost, not a filter — matching nodes rank higher; others still return). Supplying label disables inference.

Available options:

PERSON,

ORG,

GPE,

LOC,

PRODUCT,

EVENT,

LANGUAGE,

MONEY,

METRIC,

STOCK_TICKER,

WEBSITE

infer_label

boolean

When true, Tako NER infers the label and grounded-node boosts from q. Set false to disable. Tako ignores this parameter when you supply label. Default true.

Response

Matching metrics and entities

results

GraphNode · object[]

required

Show child attributes

inferred_labels

enum<string>[] | null

Labels that Tako NER inferred from q when infer_label ran (boost applied). An empty list means inference ran and found nothing. The field is absent when you supplied an explicit label, when infer_label=false, or when there was no q.

Available options:

PERSON,

ORG,

GPE,

LOC,

PRODUCT,

EVENT,

LANGUAGE,

MONEY,

METRIC,

STOCK_TICKER,

WEBSITE

Getting Started

Build with Tako

API Reference

Integrations

Additional Resources

Notes

Scoping with `types`

Steering the ranking with `label`

Example response

Authorizations

Query Parameters

Response

​Notes

​Scoping with types

​Steering the ranking with label

​Example response

Authorizations

Query Parameters

Response

Notes

Scoping with `types`

Steering the ranking with `label`

Example response