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

* **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](/api-reference/search-v3) (`/v3/search`) or [Answer](/api-reference/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](/api-reference/graph-related) to explore what it connects to.

<Warning>
  **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.
</Warning>

## 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:

```bash theme={null}
# 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.

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

## Example response

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

```json theme={null}
{
  "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.


## OpenAPI

````yaml GET /v1/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:
  /v1/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 you query. For example,
        resolve the entity here, find its metric with /v1/graph/related
        (relation=metrics, q=<one keyword from the metric name, such as gdp>),
        then ask /v3/search or /v1/answer for that entity + metric combination.
        Resolving the metric here instead can return a same-named metric that
        has no data for that entity. Each result's match_kind tells you whether
        q named it exactly; treat a fuzzy result with suspicion. Requires an API
        key. Search checks each returned id against the graph when it responds.
        Ids aren't durable across graph rebuilds, so search again instead of
        storing an id for later. Pass label to prefer a NER label (a ranking
        boost, not a filter); by default Tako infers the label from q. This
        endpoint was previously at /beta/graph/search. That path still works
        until 1 February 2027. Move to /v1/graph/search.
      operationId: graphSearch
      parameters:
        - description: Search text (min 1 char).
          required: true
          schema:
            type: string
            minLength: 1
          name: q
          in: query
        - description: Facets to include. Defaults to metric and entity.
          required: false
          style: form
          explode: false
          schema:
            items:
              $ref: '#/components/schemas/GraphNodeType'
            type: array
          name: types
          in: query
        - description: Max results (default 20, max 50).
          required: false
          schema:
            type: integer
            minimum: 1
          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: >-
            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.
          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'
        '401':
          description: Missing or invalid API key.
          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'
      security:
        - apiKey: []
components:
  schemas:
    GraphNodeType:
      type: string
      enum:
        - metric
        - entity
      title: GraphNodeType
      description: >-
        A `metric` is a measurable quantity, such as GDP; an `entity` is what
        one is measured for, such as France.
    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 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.
      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 (<prefix>::<name>::<hash>, where
            prefix is ent for an entity or mt for a metric). Ids are not durable
            across knowledge-graph rebuilds — resolve them at request time
            rather than storing them.
        type:
          $ref: '#/components/schemas/GraphNodeType'
          description: Whether the node is a metric or an entity.
        name:
          type: string
          title: Name
          description: >-
            Display name. Several metrics can share a name when publishers
            report different series, such as two GDP metrics; read `description`
            to tell them apart.
        aliases:
          items:
            type: string
          type: array
          title: Aliases
          description: >-
            Other names Tako matches to this node, such as abbreviations,
            tickers, and former names. /v1/graph/search matches `q` against
            these as well as `name`.
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: >-
            What the node is. For a metric, what it measures, often with its
            unit and basis. For an entity, a short identification. Absent when
            Tako has none.
        subtype:
          anyOf:
            - $ref: '#/components/schemas/EntityClassName'
            - type: 'null'
          description: >-
            The entity's class, such as Companies, Countries, or People. Absent
            for metrics, and for an entity whose class Tako didn't resolve for
            this response. /v1/graph/search and /v1/graph/related resolve it;
            /v1/graph/node doesn't.
        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.
        match_kind:
          anyOf:
            - $ref: '#/components/schemas/GraphMatchKind'
            - type: 'null'
          description: >-
            How this result matched `q`: `name` when `q` is the node's name,
            `alias` when `q` is one of its aliases, `mention` when a phrase in
            `q` is the node's name or alias (Apple Inc. for `q=Apple revenue`),
            and `fuzzy` for any other partial or approximate match. A `fuzzy`
            result can be unrelated to what you asked for, so check it before
            you rely on it. Set on /v1/graph/search results only.
      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
        - SERVICE_OVERLOADED
        - UNSUPPORTED_CONTENT_FORMAT
        - PLACEHOLDER_CARD
        - VARIABLE_COST_NOT_REQUESTED
      title: APIErrorType
    EntityClassName:
      type: string
      enum:
        - Companies
        - Cryptocurrencies
        - Financial Instruments
        - Internet Browsers
        - Commodities
        - People
        - Currencies
        - Stock Exchanges
        - Securities
        - IPOs
        - Government Debt Instruments
        - Treasury Securities
        - Segments
        - Airports
        - Airlines
        - Vehicle Types
        - Transportation Modes
        - Drugs
        - Drug Categories
        - Diseases
        - Injury Mechanisms
        - Injury Intents
        - Chemical Elements
        - Chemical Compounds
        - Celestial Bodies
        - Occupations
        - Social Media Platforms
        - Operating Systems
        - Search Engines
        - Device Types
        - LLMs
        - LLM Families
        - LLM Benchmarks
        - AI Gateway Entity
        - Industries
        - NAICS Industries
        - BLS Industries
        - PSC Categories
        - Purchase 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
        - Golf Players
        - Golf Tournaments
        - Golf Venues
        - Golf Courses
        - 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
        - Ice Hockey Teams
        - Ice Hockey Conferences
        - Ice Hockey Divisions
        - Sports
        - Sports Leagues
      title: EntityClassName
    GraphMatchKind:
      type: string
      enum:
        - name
        - alias
        - mention
        - fuzzy
      title: GraphMatchKind
      description: How a search result matched the query text.
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-API-Key
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.