> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tako.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Graph Search
> Resolve a metric or entity in Tako's data graph by name
## Notes
* **Public and unauthenticated** — no API key required.
* 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](/api-reference/search-v3) (`/v3/search`) or [Answer](/api-reference/answer) (`/v1/answer`) for that specific entity + metric combination.
* Each result is a `GraphNode` whose `id` you can pass straight to [Graph Related](/api-reference/graph-related) to explore what it connects to.
**This endpoint is in beta.** 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](/api-reference/search-v3) or [Answer](/api-reference/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).
## Disambiguating with `subtype`
Many names are homonyms — "China" is both a country and several U.S. towns. Pass `subtype` to scope results to a single **entity class** so the canonical entity wins:
```bash theme={null}
# The country, not "China, TX"
curl "https://tako.com/api/beta/graph/search?q=china&subtype=Countries"
```
* `subtype` implies **entity-only** results. Passing it alongside an explicit non-entity `types` (e.g. `types=metric`) is a `400`.
* The full set of classes is the `subtype` enum in the schema (e.g. `Countries`, `Companies`, `Cities`, `People`).
* Each entity result echoes its resolved class back in `subtype`, so you can confirm the match.
**A short response does not mean "no more matches."** When `subtype` is set, results are drawn from a bounded candidate window (`min(limit*5, 200)`) before filtering. A response shorter than `limit` does not imply the catalog is exhausted — narrow `q` instead.
## Example response
```json theme={null}
{
"results": [
{
"id": "china-9f2a1b",
"type": "entity",
"name": "China",
"aliases": ["People's Republic of China", "PRC"],
"description": "Country in East Asia",
"subtype": "Countries"
}
]
}
```
## OpenAPI
````yaml GET /beta/graph/search
openapi: 3.1.0
info:
title: Knowledge Search API
version: 1.0.0
servers:
- url: https://tako.com/api/
description: Tako Production API Server
security: []
paths:
/beta/graph/search:
get:
tags:
- tako
summary: Search the data graph
description: >-
Resolve a metric or entity in Tako's data graph by name. Use this to
discover and confirm what data exists before querying — e.g. resolve the
metric and the entity you care about here, then ask /v3/search or
/v1/answer for that specific entity + metric combination. Public and
unauthenticated. Note: results are not yet filtered to the
production-ready inventory, so a returned metric or entity that is not
backed by a production fact table may 404 when passed to
/beta/graph/related. Pass label to prefer a NER label (a ranking boost,
not a filter); by default the label is inferred from q.
operationId: graphSearch
parameters:
- description: Search text (min 2 chars).
required: true
schema:
type: string
name: q
in: query
- description: 'Comma-separated facets: metric,entity.'
required: false
schema:
type: string
name: types
in: query
- description: Max results (default 20, max 50).
required: false
schema:
type: integer
name: limit
in: query
- description: >-
Prefer results with this NER label (boost, not a filter — matching
nodes rank higher; others still return). Supplying label disables
inference.
required: false
schema:
type: string
enum:
- PERSON
- ORG
- GPE
- LOC
- PRODUCT
- EVENT
- LANGUAGE
- MONEY
- METRIC
- STOCK_TICKER
- WEBSITE
name: label
in: query
- description: >-
Infer label and grounded-node boosts from q via Tako NER; set false
to disable. Ignored when label is supplied. Default true.
required: false
schema:
type: boolean
name: infer_label
in: query
responses:
'200':
description: Matching metrics and entities
content:
application/json:
schema:
$ref: '#/components/schemas/GraphSearchResponse'
'400':
description: Invalid request data (validation or malformed body).
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
'503':
description: A backing data store is temporarily unavailable.
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
components:
schemas:
GraphSearchResponse:
properties:
results:
items:
$ref: '#/components/schemas/GraphNode'
type: array
title: Results
inferred_labels:
anyOf:
- items:
$ref: '#/components/schemas/NerLabel'
type: array
- type: 'null'
title: Inferred Labels
description: >-
Labels inferred from `q` when infer_label ran (boost applied). Empty
list: inference ran and found nothing. Absent: an explicit `label`
was given, infer_label=false, or there was no q.
type: object
required:
- results
title: GraphSearchResponse
BaseAPIError:
properties:
error_message:
type: string
title: Error Message
error_type:
$ref: '#/components/schemas/APIErrorType'
type: object
required:
- error_message
- error_type
title: BaseAPIError
GraphNode:
properties:
id:
type: string
title: Id
description: Opaque, human-friendly public id (-).
type:
$ref: '#/components/schemas/GraphNodeType'
name:
type: string
title: Name
aliases:
items:
type: string
type: array
title: Aliases
description:
anyOf:
- type: string
- type: 'null'
title: Description
subtype:
anyOf:
- $ref: '#/components/schemas/EntityClassName'
- type: 'null'
label:
anyOf:
- $ref: '#/components/schemas/NerLabel'
- type: 'null'
description: >-
Public NER label of the node (PERSON, ORG, GPE, ...). Derived from
the node's stored annotation; null when the internal annotation has
no public equivalent.
type: object
required:
- id
- type
- name
title: GraphNode
NerLabel:
type: string
enum:
- PERSON
- ORG
- GPE
- LOC
- PRODUCT
- EVENT
- LANGUAGE
- MONEY
- METRIC
- STOCK_TICKER
- WEBSITE
title: NerLabel
APIErrorType:
type: string
enum:
- BAD_REQUEST
- AUTHENTICATION_ERROR
- INTERNAL_SERVER_ERROR
- RELEVANT_RESULTS_NOT_FOUND
- RATE_LIMIT_EXCEEDED
- PAYMENT_REQUIRED
- REQUEST_TIMEOUT
- FORBIDDEN
- NOT_FOUND
- SERVICE_UNAVAILABLE
title: APIErrorType
GraphNodeType:
type: string
enum:
- metric
- entity
title: GraphNodeType
EntityClassName:
type: string
enum:
- Companies
- Cryptocurrencies
- Financial Instruments
- Internet Browsers
- Commodities
- People
- Currencies
- Stock Exchanges
- Securities
- IPOs
- Government Debt Instruments
- Treasury Securities
- Airports
- Airlines
- Vehicle Types
- Transportation Modes
- Drugs
- Drug Categories
- Diseases
- Chemical Elements
- Chemical Compounds
- Celestial Bodies
- Occupations
- Social Media Platforms
- Operating Systems
- Search Engines
- Device Types
- LLMs
- LLM Families
- LLM Benchmarks
- Industries
- NAICS Industries
- BLS Industries
- PSC Categories
- Federal Contractors
- Federal Agencies
- Federal Subagencies
- ICE Contracts
- ICE Contractors
- Elections
- Political Offices
- Pollsters
- Agricultural Products
- Tobacco Products
- Prediction Markets
- Prediction Events
- Real Estate Property Types
- Continents
- World Regions
- Countries
- States
- Counties
- Metro Areas
- Cities
- F1 Drivers
- F1 Teams
- F1 Circuits
- F1 Events
- NASCAR Drivers
- NASCAR Teams
- NASCAR Tracks
- NASCAR Events
- NASCAR Races
- NASCAR Owners
- NASCAR Manufacturers
- Soccer Teams
- Soccer Players
- Soccer Competitions
- Soccer Conferences
- Basketball Teams
- Basketball Players
- Basketball Conferences
- Basketball Divisions
- Baseball Teams
- Baseball Players
- Baseball Conferences
- Baseball Divisions
- Baseball Competitions
- Football Teams
- Football Players
- Football Conferences
- Football Divisions
- Sports
- Sports Leagues
title: EntityClassName
````