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

> Explore the nodes connected to a metric or entity in Tako's data graph

## Notes

* **Public and unauthenticated** — no API key required.
* Start from a `node_id` returned by [Graph Search](/api-reference/graph-search), then use graph related to **find which entity + metric combinations Tako actually covers.** Once you've found a covered combination, query [Search](/api-reference/search-v3) (`/v3/search`) or [Answer](/api-reference/answer) (`/v1/answer`) for it.
* **Related is symmetric** — for any node, the response groups everything it connects to into `metrics` and `entities` (from the tables the node belongs to). An entity, for example, returns the metrics tracked for it and other entities that appear in the same tables.

## Response shape: overview vs. one facet

The response always includes the resolved `node`. The rest depends on whether you paginate:

* **No `relation_type`** → `related` holds a grouped **overview**: `metrics` and `entities`, each with its own `items` and `total`. Use this to see everything a node connects to at a glance.
* **`relation_type` set** (`metric` / `entity`) → `relation` holds a single paginated `GraphRelationPage` for that one facet, with `items`, `total`, and a `next_cursor`. Pass `next_cursor` back as `cursor` to page through.

## Narrowing with `q`

The optional `q` is a case-insensitive substring filter on related nodes' name/aliases. It filters **every facet** of the overview, or the single paginated facet when `relation_type` is set:

```bash theme={null}
# Metrics available for an entity, matching "gdp"
curl "https://tako.com/api/beta/graph/related?node_id=china-9f2a1b&relation_type=metric&q=gdp"
```

<Note>
  A `404` means the node does not exist **or has no exportable data.**
</Note>

## Example response (overview)

```json theme={null}
{
  "node": {
    "id": "china-9f2a1b",
    "type": "entity",
    "name": "China",
    "subtype": "Countries"
  },
  "related": {
    "metrics": { "items": [/* ... */], "total": 184 },
    "entities": { "items": [], "total": 0 }
  }
}
```


## OpenAPI

````yaml GET /beta/graph/related
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/related:
    get:
      tags:
        - tako
      summary: Get a graph node's related nodes
      description: >-
        Explore what a node connects to. The overview returns an ordered
        `relations` list: named relationships (e.g. `rel:competes_with`,
        `rel:in_industry`) first, then a node's metrics and entities (the entity
        + metric combinations Tako covers — query /v3/search or /v1/answer for
        one), then similar nodes and membership (part_of / members). Each group
        carries a stable `key`; pass `relation`=<key> + cursor to paginate that
        one group, and the optional q to narrow by a case-insensitive substring
        on name/aliases (e.g. metrics for an entity matching 'gdp'). Public and
        unauthenticated.
      operationId: graphRelated
      parameters:
        - description: Opaque public id of the node.
          required: true
          schema:
            type: string
          name: node_id
          in: query
        - description: >-
            Relation key to paginate, e.g. `rel:competes_with`, `metrics`,
            `entities`, `siblings`, or `members`.
          required: false
          schema:
            type: string
          name: relation
          in: query
        - description: >-
            Deprecated: use `relation`. Legacy facet
            (metric/entity/sibling/member) mapped to a key.
          required: false
          deprecated: true
          schema:
            type: string
          name: relation_type
          in: query
        - description: >-
            Optional case-insensitive substring filter on the related nodes'
            name/aliases. Filters every group of the overview, or the single
            paginated group when `relation` is set.
          required: false
          schema:
            type: string
          name: q
          in: query
        - description: Opaque pagination cursor.
          required: false
          schema:
            type: string
          name: cursor
          in: query
        - description: Page size (default 50, max 100).
          required: false
          schema:
            type: integer
          name: limit
          in: query
        - description: >-
            Prefer related nodes with this NER label (boost, not a filter —
            matching nodes rank higher within each relation; totals are
            unchanged). 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; applies only when q is
            present. Default true.
          required: false
          schema:
            type: boolean
          name: infer_label
          in: query
      responses:
        '200':
          description: A node's details plus related nodes by facet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphRelatedResponse'
        '400':
          description: Invalid request data (validation or malformed body).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '404':
          description: The requested resource does not exist or has no exportable data.
          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:
    GraphRelatedResponse:
      properties:
        node:
          $ref: '#/components/schemas/GraphNode'
        relations:
          anyOf:
            - items:
                $ref: '#/components/schemas/GraphRelation'
              type: array
            - type: 'null'
          title: Relations
        relation:
          anyOf:
            - $ref: '#/components/schemas/GraphRelationPage'
            - type: 'null'
        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:
        - node
      title: GraphRelatedResponse
    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 (<name-slug>-<token>).
        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
    GraphRelation:
      properties:
        key:
          type: string
          title: Key
          description: >-
            Stable pagination handle. Fixed keys: metrics, entities, siblings,
            part_of, members. Named relations: rel:<phrase>.
        kind:
          $ref: '#/components/schemas/RelationKind'
        label:
          type: string
          title: Label
          description: Human-readable group label.
        items:
          items:
            $ref: '#/components/schemas/GraphNode'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        total_capped:
          type: boolean
          title: Total Capped
          description: >-
            True when `total` hit the server-side fetch cap; the true count is
            at least `total`. Render as 'total+'.
          default: false
      type: object
      required:
        - key
        - kind
        - label
        - items
        - total
      title: GraphRelation
    GraphRelationPage:
      properties:
        key:
          type: string
          title: Key
          description: The relation key that was paginated.
        kind:
          $ref: '#/components/schemas/RelationKind'
        label:
          type: string
          title: Label
          description: Human-readable group label.
        items:
          items:
            $ref: '#/components/schemas/GraphNode'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        total_capped:
          type: boolean
          title: Total Capped
          description: >-
            True when `total` hit the server-side fetch cap; the true count is
            at least `total`. Pagination ends at the cap — narrow with `q` to
            reach the tail.
          default: false
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
      type: object
      required:
        - key
        - kind
        - label
        - items
        - total
      title: GraphRelationPage
    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
    RelationKind:
      type: string
      enum:
        - related
        - data
        - sibling
        - membership
      title: RelationKind
      description: |-
        How a relation group was derived. The SOURCE kind is Tako-internal only
        and intentionally absent from this public twin.

````