> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/graphprotocol/graph-node/llms.txt
> Use this file to discover all available pages before exploring further.

# GraphQL API Overview

> Complete guide to Graph Node's GraphQL query interface for subgraph data

Graph Node exposes a powerful GraphQL API for querying indexed blockchain data from subgraphs. The API automatically generates query types based on your subgraph schema and provides advanced filtering, sorting, and pagination capabilities.

## API Endpoint

Once Graph Node is running, the GraphQL HTTP server is available at:

```
http://localhost:8000
```

You can query specific subgraphs using these URL patterns:

<CodeGroup>
  ```bash By Name theme={null}
  curl -X POST http://localhost:8000/subgraphs/name/<subgraph-name>
  ```

  ```bash By IPFS Hash theme={null}
  curl -X POST http://localhost:8000/subgraphs/id/<ipfs-hash>
  ```
</CodeGroup>

## Schema-Based Type Generation

Graph Node automatically generates GraphQL query types from your subgraph schema. For each entity type in your schema, the API provides:

* **Single entity query**: `entityName(id: ID!): EntityType`
* **Collection query**: `entityNames(first, skip, orderBy, orderDirection, where): [EntityType!]!`

### Example Schema

```graphql schema.graphql theme={null}
type Token @entity {
  id: ID!
  name: String!
  symbol: String!
  decimals: Int!
  totalSupply: BigInt!
}

type Transfer @entity(immutable: true) {
  id: ID!
  from: Bytes!
  to: Bytes!
  amount: BigInt!
  blockNumber: BigInt!
  timestamp: Timestamp!
}
```

### Generated Query Types

From the schema above, Graph Node generates:

```graphql Generated API theme={null}
type Query {
  # Single entity queries
  token(id: ID!, block: Block_height): Token
  transfer(id: ID!, block: Block_height): Transfer
  
  # Collection queries
  tokens(
    first: Int = 100
    skip: Int = 0
    orderBy: Token_orderBy
    orderDirection: OrderDirection
    where: Token_filter
    block: Block_height
  ): [Token!]!
  
  transfers(
    first: Int = 100
    skip: Int = 0
    orderBy: Transfer_orderBy
    orderDirection: OrderDirection
    where: Transfer_filter
    block: Block_height
  ): [Transfer!]!
}
```

## Entity Types and Fields

### Supported GraphQL Types

Graph Node supports the following scalar types in entity definitions:

<ResponseField name="ID" type="String">
  Unique identifier for entities. Stored as `text` or `bytea` in PostgreSQL.
</ResponseField>

<ResponseField name="String" type="String">
  UTF-8 encoded text strings.
</ResponseField>

<ResponseField name="Bytes" type="Bytes">
  Byte arrays, typically for Ethereum addresses and hashes. Must be prefixed with `0x`.
</ResponseField>

<ResponseField name="Int" type="Int">
  32-bit signed integer.
</ResponseField>

<ResponseField name="Int8" type="Int8">
  64-bit signed integer.
</ResponseField>

<ResponseField name="BigInt" type="BigInt">
  Arbitrary precision integer, stored as PostgreSQL `numeric`.
</ResponseField>

<ResponseField name="BigDecimal" type="BigDecimal">
  Arbitrary precision decimal, stored as PostgreSQL `numeric`.
</ResponseField>

<ResponseField name="Boolean" type="Boolean">
  Boolean value (`true` or `false`).
</ResponseField>

<ResponseField name="Timestamp" type="Timestamp">
  Unix timestamp in microseconds since epoch. Available from spec version 1.1.0.
</ResponseField>

### Entity Attributes

<Accordion title="@entity Directive">
  Marks a GraphQL type as a storable entity.

  ```graphql theme={null}
  type Account @entity {
    id: ID!
    balance: BigInt!
  }
  ```

  **Options:**

  * `immutable: true` - Entity versions are never updated (optimized storage)
  * `timeseries: true` - Entity is a timeseries data point (immutable with timestamp)
</Accordion>

<Accordion title="@derivedFrom Directive">
  Creates reverse lookups for entity relationships.

  ```graphql theme={null}
  type Token @entity {
    id: ID!
    transfers: [Transfer!]! @derivedFrom(field: "token")
  }

  type Transfer @entity {
    id: ID!
    token: Token!
    amount: BigInt!
  }
  ```

  The `transfers` field on `Token` is automatically populated from `Transfer` entities.
</Accordion>

<Accordion title="Immutable Entities">
  Immutable entities are write-once and never updated, enabling storage optimizations.

  ```graphql theme={null}
  type Event @entity(immutable: true) {
    id: ID!
    blockNumber: BigInt!
    timestamp: Timestamp!
    data: String!
  }
  ```

  **Storage Optimization:**

  * Uses `block$` column instead of `block_range`
  * Simple BTree indexes instead of GiST indexes
  * Enforces `unique(id)` constraint
</Accordion>

## Query Arguments

All collection queries support these arguments:

<ResponseField name="first" type="Int" default="100">
  Number of entities to return. Maximum value is configurable per Graph Node instance.
</ResponseField>

<ResponseField name="skip" type="Int" default="0">
  Number of entities to skip. Useful for pagination.
</ResponseField>

<ResponseField name="orderBy" type="Enum">
  Field to sort results by. Can be any field in the entity or nested field (e.g., `token__symbol`).
</ResponseField>

<ResponseField name="orderDirection" type="Enum">
  Sort direction: `asc` (ascending) or `desc` (descending). Default is `asc`.
</ResponseField>

<ResponseField name="where" type="Filter">
  Filter conditions for entities. See [Query Filters](/api/queries#filters) for details.
</ResponseField>

<ResponseField name="block" type="Block_height">
  Query historical state at a specific block. See [Time-Travel Queries](/api/time-travel).
</ResponseField>

## Basic Query Examples

<CodeGroup>
  ```graphql Single Entity theme={null}
  query {
    token(id: "0x1234") {
      id
      name
      symbol
      decimals
      totalSupply
    }
  }
  ```

  ```graphql Collection with Pagination theme={null}
  query {
    tokens(first: 10, skip: 20) {
      id
      name
      symbol
    }
  }
  ```

  ```graphql Sorting theme={null}
  query {
    tokens(
      first: 100
      orderBy: totalSupply
      orderDirection: desc
    ) {
      id
      name
      totalSupply
    }
  }
  ```

  ```graphql Nested Fields theme={null}
  query {
    token(id: "0x1234") {
      id
      name
      transfers(first: 5, orderBy: timestamp) {
        id
        from
        to
        amount
        timestamp
      }
    }
  }
  ```
</CodeGroup>

## Response Format

Graph Node returns responses in standard GraphQL format:

```json theme={null}
{
  "data": {
    "tokens": [
      {
        "id": "0x1234",
        "name": "Example Token",
        "symbol": "EXT",
        "decimals": 18,
        "totalSupply": "1000000000000000000000000"
      }
    ]
  },
  "errors": []
}
```

### Error Handling

Errors are returned in the `errors` array:

```json theme={null}
{
  "data": null,
  "errors": [
    {
      "message": "Entity not found",
      "locations": [{"line": 2, "column": 3}],
      "path": ["token"]
    }
  ]
}
```

## Interfaces

Graph Node supports GraphQL interfaces for polymorphic entities:

```graphql theme={null}
interface Transaction {
  id: ID!
  hash: Bytes!
  blockNumber: BigInt!
}

type Swap implements Transaction @entity {
  id: ID!
  hash: Bytes!
  blockNumber: BigInt!
  amountIn: BigInt!
  amountOut: BigInt!
}

type Transfer implements Transaction @entity {
  id: ID!
  hash: Bytes!
  blockNumber: BigInt!
  from: Bytes!
  to: Bytes!
  amount: BigInt!
}
```

Query interfaces to fetch all implementing types:

```graphql theme={null}
query {
  transactions(first: 10) {
    id
    hash
    blockNumber
    ... on Swap {
      amountIn
      amountOut
    }
    ... on Transfer {
      from
      to
      amount
    }
  }
}
```

## Performance Considerations

<Accordion title="Pagination">
  Always use `first` and `skip` for pagination to avoid loading excessive data:

  ```graphql theme={null}
  # Good: Paginated query
  query {
    tokens(first: 100, skip: 0) {
      id
      name
    }
  }

  # Avoid: No limit (defaults to 100 but can be expensive)
  query {
    tokens {
      id
      name
    }
  }
  ```
</Accordion>

<Accordion title="Field Selection">
  Only query fields you need. Large text fields and arrays can be expensive:

  ```graphql theme={null}
  # Good: Selective fields
  query {
    tokens(first: 100) {
      id
      symbol
    }
  }

  # Avoid: All fields when not needed
  query {
    tokens(first: 100) {
      id
      name
      symbol
      decimals
      totalSupply
      largeDescriptionField
    }
  }
  ```
</Accordion>

<Accordion title="Nested Queries">
  Be cautious with nested queries that can multiply data fetched:

  ```graphql theme={null}
  # Can fetch large amounts of data
  query {
    tokens(first: 100) {
      id
      transfers(first: 100) {
        # This fetches up to 10,000 transfers (100 * 100)
        id
        amount
      }
    }
  }
  ```
</Accordion>

## Next Steps

* Learn about [advanced query filters and operators](/api/queries)
* Explore [aggregation queries](/api/aggregations) for timeseries data
* Understand [time-travel queries](/api/time-travel) for historical state