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

* **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.
* 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 — pinning the ids via `sources.data.node_ids`.
* Results in each group are **ranked by popularity, blended with how strongly each node matches `q`** when a filter is provided. On big entities, always pass `q` — unfiltered, a big entity returns hundreds of items.

## Response shape: overview vs. one group

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

* **No `relation`** → `relations` holds an ordered **overview**: one group per relation, each `{key, kind, label, items (preview), total, total_capped}`. Named semantic edges come first, then membership, data, and siblings; empty groups are dropped.
* **`relation=<key>` set** → `relation` holds a single paginated page for that one group, with `items`, `total`, `total_capped`, and a `next_cursor`. Pass `next_cursor` back as `cursor` to page through. Items live in `relation.items`.

Groups by `kind`:

| `kind` | Keys | Meaning |
| - | - | - |
| `related` | `rel:<phrase>` — e.g. `rel:competes_with`, `rel:subsidiaries_of`, `rel:in_industry` | Named semantic edges — the richest signal for entities. Keys are per-node: read the overview to discover them, then drill. |
| `membership` | `part_of`, `members` | Cohort/geo membership (Apple `part_of` FAANG; a league's `members`). |
| `data` | `metrics`, `entities` | Table co-reference — the metrics/entities sharing datasets with this node. |
| `sibling` | `siblings` | Same-type peers — the class namespace ("Other Companies"), not a curated cohort. |

<Note>
  An unknown `relation` key returns `200` with empty `items`, not an error — so a typo'd key reads as "no relation." Keys are per-node: read the overview to discover them, then drill.
</Note>

## Narrowing with `q`

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

```bash theme={null}
# Metrics available for an entity, matching "gdp"
curl "https://tako.com/api/v1/graph/related?node_id=$NODE_ID&relation=metrics&q=gdp" \
  -H "X-API-Key: $TAKO_API_KEY"
```

`label`/`infer_label` boosts work as on [Graph Search](/api-reference/graph-search) and apply within each group; inference runs only when `q` is set.

## Capped totals

`total` stops counting at **250**: `total_capped: true` means the true count is at least `total` — render it as "250+". Pagination also ends at the cap, so narrow with `q` to reach the tail.

<Note>
  A `404` means the `node_id` does not resolve. A node with **no relations** returns `200` with empty groups — that's the normal "nothing connected" outcome, not an error.
</Note>

## Example response (overview)

```json theme={null}
{
  "node": { "id": "ent::nvidia_corporation::5ea55992", "type": "entity", "name": "NVIDIA Corporation", "subtype": "Companies", "label": "ORG" },
  "relations": [
    { "key": "rel:competes_with", "kind": "related", "label": "Competes with",
      "items": [/* GraphNode previews */], "total": 179, "total_capped": false },
    { "key": "rel:subsidiaries_of", "kind": "related", "label": "Subsidiaries of",
      "items": [/* ... */], "total": 24, "total_capped": false },
    { "key": "part_of", "kind": "membership", "label": "Part of",
      "items": [/* ... */], "total": 2, "total_capped": false },
    { "key": "metrics", "kind": "data", "label": "Related Metrics",
      "items": [/* ... */], "total": 250, "total_capped": true },
    { "key": "entities", "kind": "data", "label": "Entities",
      "items": [/* ... */], "total": 62, "total_capped": false },
    { "key": "siblings", "kind": "sibling", "label": "Other Companies",
      "items": [/* ... */], "total": 250, "total_capped": true }
  ]
}
```


## OpenAPI

````yaml GET /v1/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:
  /v1/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 (for example `rel:competes_with`,
        `rel:in_industry`) first, then a node's metrics and entities, then
        similar nodes and membership (part_of, members), then breakdowns. The
        metrics and entities are the entity + metric combinations Tako covers —
        query /v3/search or /v1/answer for one. A breakdown, keyed
        `breakdown:<dimension>`, lists the values a node's data is split by. For
        example, `breakdown:segment` lists the business and geographic segments
        a company reports, such as Data Center for NVIDIA, and
        `breakdown:soc_code` lists the occupations in an employer's visa
        filings. A node can have several. To get a segment's figures, read the
        segment's own `metrics` group, then call /v3/search with the company,
        segment, and metric ids pinned in its data `node_ids` field. A segment's
        `metrics` lists what any company reports for that segment, so the search
        shows which figures exist for this company. Each group carries a stable
        `key`. Pass `relation`=<key> plus cursor to paginate that one group.
        Pass the optional q to narrow by a case-insensitive substring on names
        and aliases (for example, the metrics of an entity that match 'gdp').
        Requires an API key. This endpoint was previously at
        /beta/graph/related. That path still works until 1 February 2027. Move
        to /v1/graph/related.
      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. Read the keys from the overview, for
            example `rel:competes_with`, `breakdown:segment`,
            `breakdown:soc_code`, `metrics`, `entities`, `siblings`, or
            `members`.
          required: false
          schema:
            type: string
          name: relation
          in: query
        - description: >-
            Deprecated: use `relation`. A legacy facet name (metric, entity,
            sibling, or member) that maps 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'
            names and aliases. It filters every group of the overview, or the
            single paginated group when you set `relation`.
          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: >-
            Maximum number of nodes counted and paginated in each relation
            (default 250, max 2000). A relation with more nodes reports this
            total with `total_capped` set, and pagination ends at it. Higher
            values make the request slower.
          required: false
          schema:
            type: integer
          name: max_per_relation
          in: query
        - description: >-
            Prefer related nodes with this NER label. This is a boost, not a
            filter: matching nodes rank higher within each relation, and totals
            do not change. 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. It 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'
        '401':
          description: Missing or invalid API key.
          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'
        '504':
          description: >-
            A graph query exceeded its time limit. This doesn't mean the node is
            missing or has no connections. Narrow the request or try again
            later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
      security:
        - apiKey: []
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 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:
        - 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 (<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
    GraphRelation:
      properties:
        key:
          type: string
          title: Key
          description: >-
            Stable pagination handle. Fixed keys: metrics, entities, siblings,
            part_of, members. Named relations: rel:<phrase>. Breakdowns:
            breakdown:<dimension>.
        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 of this page.
        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
        - SERVICE_OVERLOADED
        - UNSUPPORTED_CONTENT_FORMAT
        - PLACEHOLDER_CARD
        - VARIABLE_COST_NOT_REQUESTED
      title: APIErrorType
    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.
    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.
    RelationKind:
      type: string
      enum:
        - related
        - data
        - sibling
        - membership
      title: RelationKind
      description: How Tako derived a relation group.
  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.